DashScope 文本向量

POST

/api/v1/services/embeddings/text-embedding/text-embedding

import dashscope
from http import HTTPStatus

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

resp = dashscope.TextEmbedding.call(
  model=dashscope.TextEmbedding.Models.text_embedding_v4,
  input='Semantic search finds documents by meaning rather than exact keyword matching. Text embeddings map words and sentences into high-dimensional vector spaces. Retrieval-augmented generation combines search results with language models. Document clustering groups similar texts based on their vector representations.',
  dimension=1024,
  output_type="dense&sparse"
)

print(resp) if resp.status_code == HTTPStatus.OK else print(resp)

{
  "status_code": 200,
  "request_id": "1ba94ac8-e058-99bc-9cc1-7fdb37940a46",
  "code": "",
  "message": "",
  "output": {
    "embeddings": [
      {
        "sparse_embedding": [
          {
            "index": 7149,
            "value": 0.829,
            "token": "wind"
          },
          {
            "index": 111290,
            "value": 0.9004,
            "token": "sorrow"
          }
        ],
        "embedding": [
          -0.006929283495992422,
          -0.005336422007530928
        ],
        "text_index": 0
      }
    ]
  },
  "usage": {
    "total_tokens": 27
  }
}

将文本转换为向量，用于语义搜索、推荐、聚类和分类。

开始之前：获取 API Key，将其设置为环境变量，如果使用 SDK，还需安装 DashScope SDK。

设置 SDK 基础 URL

Python SDK：

import dashscope
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

Java SDK：

import com.alibaba.dashscope.utils.Constants;
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";

支持的模型

模型	向量维度	最大 Token 数	批量大小	语言支持	价格（每百万 Token）	免费额度
text-embedding-v4	2048、1536、1024（默认）、768、512、256、128、64	8,192	10	100+ 种	0.5元	100 万 Token（90 天）
text-embedding-v3	1024（默认）、768、512	8,192	10	50+ 种	0.5元	100 万 Token（90 天）

输入格式

单个字符串：最多 8,192 个 Token
数组：最多 10 个字符串，每个最多 8,192 个 Token
文本文件：最多 10 行，每行最多 8,192 个 Token

DashScope 特有功能

text_type：设置为 query 或 document，适用于检索等非对称任务。
output_type：返回稀疏向量（dense&sparse），用于混合搜索（仅 v3/v4 支持）。
instruct：添加任务描述以提升准确率约 1-5%（仅 v4 支持；建议使用英文）。

参见限流。

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

请求体

application/json

string

必填

调用的模型名称，支持 text-embedding-v4 和 text-embedding-v3。

示例:text-embedding-v4

object

必填

包含待向量化文本的输入对象。

显示子属性

string

必填

待处理的输入文本，可以是字符串或字符串数组。单个字符串最多 8,192 个 token；字符串列表最多 10 条，每条最多 8,192 个 token。

object

向量化请求的可选参数。

显示子属性

enum<string>

默认值"document"

指定文本类型，用于非对称任务。检索场景下区分 query（查询词）和 document（文档）有助于提升效果；聚类、分类等对称任务使用默认值 document。

可选值：query,document

enum<integer>

默认值1024

向量维度。可选值：2048（仅 text-embedding-v4）、1536（仅 text-embedding-v4）、1024、768、512、256（仅 text-embedding-v4）、128（仅 text-embedding-v4）、64（仅 text-embedding-v4）。默认值：1024。

可选值：2048,1536,1024,768,512,256,128,64

enum<string>

默认值"dense"

是否输出稀疏向量表示，仅适用于 text-embedding-v3 和 text-embedding-v4。默认值：dense（仅返回稠密向量）。

可选值：dense,sparse,dense&sparse

string

自定义任务描述，仅在 text-embedding-v4 且 text_type 为 query 时生效，推荐使用英文描述（可提升约 1%~5% 的效果）。

响应

200-application/json

integer

默认值"200"

状态码，200 表示请求成功。

string

默认值"1ba94ac8-e058-99bc-9cc1-7fdb37940a46"

请求的唯一标识符，可用于追踪和排查问题。

string

默认值""

请求失败时的错误码，成功时为空。

string

默认值""

请求失败时的详细错误信息，成功时为空。

object

任务输出数据。

显示子属性

object[]

结构体数组，每个结构体包含对应输入文本的向量输出。

显示子属性

object[]

稀疏向量表示，仅在 output_type 包含 sparse 时适用于 text-embedding-v3 和 text-embedding-v4。

显示子属性

integer

词或字符在词汇表中的索引。

number

该 token 的权重或重要性分数，值越高表示越重要。

string

来自词汇表的实际文本单元或词语。

number[]

稠密向量表示（dense embedding）。

integer

本结果对应输入数组中的文本索引。

object

默认值"{\"total_tokens\":27}"

Token 用量统计。

显示子属性

integer

请求中 token 的总数，按模型分词器计算。

​设置 SDK 基础 URL

​支持的模型

​输入格式

​DashScope 特有功能

鉴权

请求体

响应

设置 SDK 基础 URL

支持的模型

输入格式

DashScope 特有功能