将数据转换为向量
前提条件
获取 API Key 并将其设置为环境变量。如需使用 SDK,请先安装 SDK。
获取向量
文本向量化
调用 API 时,在请求中指定要向量化的文本和模型名称。
- OpenAI 兼容
- DashScope
支持的模型
| 模型 | 向量维度 | 批次大小 | 每批最大 Token 数 | 支持的语言 |
|---|---|---|---|---|
| text-embedding-v4(属于 Qwen3-Embedding 系列) | 2,048、1,536、1,024(默认)、768、512、256、128、64 | 10 | 8,192 | 100+ 种主流语言,包括中文、英文、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄语等 |
| text-embedding-v3 | 1,024(默认)、768、512 | 10 | 8,192 | 50+ 种主流语言,包括中文、英文、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄语等 |
批次大小是指单次 API 调用中可处理的最大文本数量。例如,text-embedding-v4 的批次大小为 10,即单次请求最多可传入 10 条文本进行向量化,每条文本不超过 8,192 个 Token。此限制适用于:
- 字符串数组输入:数组最多包含 10 个元素。
- 文件输入:文本文件最多包含 10 行文本。
核心功能
切换向量维度
text-embedding-v4 和 text-embedding-v3 支持自定义向量维度。维度越高,保留的语义信息越丰富,但存储和计算开销也更大。
- 通用场景(推荐):1024 维在性能与成本之间取得了最佳平衡,适合大多数语义检索任务。
- 高精度场景:对精度要求较高的领域,可选择 1536 或 2048 维。精度有一定提升,但存储和计算开销显著增加。
- 资源受限场景:对成本敏感的场景,可选择 768 维或更低。资源消耗显著降低,但语义信息会有一定损失。
- OpenAI 兼容
- DashScope
区分查询文本与文档文本(text_type)
该参数目前仅支持通过 DashScope SDK 和 API 启用。
text_type 参数就是为此设计的:
text_type: 'query':用于用户输入的查询文本。模型生成的向量更具方向性,类似"标题"向量,专为"提问"和"检索"优化。text_type: 'document'(默认):用于存储在数据库中的文档文本。模型生成的向量包含更全面的信息,类似"正文"向量,专为被检索优化。
query 和 document。对于所有文本角色相同的任务(如聚类或分类),无需设置此参数。
使用指令提升效果(instruct)
该参数目前仅支持通过 DashScope SDK 和 API 启用。
text-embedding-v4 针对特定检索场景优化向量质量,有效提升精度。使用此功能时,需将 text_type 参数设置为 query。
稠密向量与稀疏向量
该参数目前仅支持通过 DashScope SDK 和 API 启用。
text-embedding-v4 和 text-embedding-v3 支持三种向量输出类型,满足不同检索策略的需求。
向量类型(output_type) | 核心优势 | 主要不足 | 典型应用场景 |
|---|---|---|---|
| dense | 深度语义理解。能识别同义词和上下文,检索结果更相关。 | 计算和存储成本更高。无法保证精确的关键词匹配。 | 语义搜索、AI 对话、内容推荐。 |
| sparse | 计算效率高。专注于精确关键词匹配和快速过滤。 | 牺牲语义理解。无法处理同义词或上下文。 | 日志检索、商品 SKU 搜索、精确信息过滤。 |
| dense&sparse | 结合语义和关键词,获得最佳搜索效果。生成成本相同,API 调用开销与单向量模式一致。 | 存储需求大。系统架构和检索逻辑更复杂。 | 高质量生产级混合搜索引擎。 |
使用示例
以下代码仅供演示。在生产环境中,应预先计算向量并存储到向量数据库中。检索时只需计算查询向量。
语义搜索
通过计算查询与文档之间的向量相似度,实现精准的语义匹配。
推荐系统
通过分析用户历史行为的向量,发现用户兴趣偏好并推荐相似内容。
文本聚类
通过分析文本向量之间的距离,自动将相似文本归为一组。
文本分类
通过计算输入文本与预定义标签之间的向量相似度,无需预先标注样本即可识别和分类新类别。
异常检测
通过计算文本向量与正常样本向量中心之间的相似度,识别与正常模式显著不同的异常数据。
示例代码中的阈值仅用于演示。实际业务场景中,相似度的具体数值取决于数据内容和分布,没有固定阈值。请根据自己的数据集校准该值。
API 参考
关于多模态向量化,请参阅多模态向量化。
错误码
如果调用失败,请参阅错误信息。
限流
请参阅限流。
模型性能(MTEB/CMTEB)
- MTEB:Massive Text Embedding Benchmark,针对分类、聚类、检索等任务的通用能力综合评测。
- CMTEB:Chinese Massive Text Embedding Benchmark,专门针对中文文本的评测。
- 分数范围为 0 到 100,数值越高表示性能越好。
| 模型 | MTEB | MTEB(检索任务) | CMTEB | CMTEB(检索任务) |
|---|---|---|---|---|
| text-embedding-v3(512 维) | 62.11 | 54.30 | 66.81 | 71.88 |
| text-embedding-v3(768 维) | 62.43 | 54.74 | 67.90 | 72.29 |
| text-embedding-v3(1024 维) | 63.39 | 55.41 | 68.92 | 73.23 |
| text-embedding-v4(512 维) | 64.73 | 56.34 | 68.79 | 73.33 |
| text-embedding-v4(1024 维) | 68.36 | 59.30 | 70.14 | 73.98 |
| text-embedding-v4(2048 维) | 71.58 | 61.97 | 71.99 | 75.01 |

