向量化模型可将文本、图像、视频等数据转换为数值向量,用于语义搜索、推荐、聚类、分类、异常检测等下游任务。
前提条件
获取 API Key 并将其设置为环境变量。如需使用 SDK,请先安装 SDK。
获取向量
文本向量化
调用 API 时,在请求中指定要向量化的文本和模型名称。
- OpenAI 兼容
- DashScope
多模态独立向量
为每种输入(文本、图像或视频)分别生成独立向量。适合为图片和文字标题各自建立索引。
多模态 Embedding 需使用 DashScope SDK 或 HTTP API,不支持 OpenAI 兼容接口。
- Python
- Java
{"image": image} 替换为 {"video": video_url}。
多模态融合向量
将多模态输入(文本 + 图片 + 视频)编码为 1 个向量。适合图文混合检索——例如输入一张衬衫图片加上文本"找相似但更年轻的款式",模型将图像和文本指令融合为一个向量。
- Python
- Java (HTTP)
各模型的融合方式
| 模型 | 融合方式 |
|---|---|
qwen3-vl-embedding | 添加 enable_fusion=True 参数 |
qwen2.5-vl-embedding | 默认即为融合模式,无需额外参数 |
tongyi-embedding-vision-plus-2026-03-06 | 将 text、image 放在同一个 content 对象中:[{"text": ..., "image": ...}] |
tongyi-embedding-vision-flash-2026-03-06 | 同上 |
tongyi-embedding-vision-plus-2026-03-06 融合示例
tongyi-embedding-vision-plus-2026-03-06 融合示例
该模型通过将 text 和 image 放在同一个 content 对象中实现融合,无需
enable_fusion 参数。模型选择
文本向量
| 模型 | 向量维度 | 批次大小 | 每批最大 Token 数 | 支持的语言 |
|---|---|---|---|---|
| qwen3.7-text-embedding | 2,560、2,048、1,536、1,024(默认)、768、512、256 | 20 | 128,000 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄语等201种主流语种与方言 |
| text-embedding-v4(属于 Qwen3-Embedding 系列) | 2,048、1,536、1,024(默认)、768、512、256、128、64 | 10 | 33,000 | 100+ 种主流语言,包括中文、英文、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄语等 |
| text-embedding-v3 | 1,024(默认)、768、512、256、128、64 | 10 | 8,192 | 50+ 种主流语言,包括中文、英文、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄语等 |
| text-embedding-v2 | 1,536 | 25 | 2,048 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄语 |
| text-embedding-v1 | 1,536 | 25 | 2,048 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语 |
| text-embedding-async-v2 | 1,536 | 100,000 | 2,048 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄语 |
| text-embedding-async-v1 | 1,536 | 100,000 | 2,048 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语 |
批次大小是指单次 API 调用中可处理的最大文本数量。例如,text-embedding-v4 的批次大小为 10,即单次请求最多可传入 10 条文本进行向量化,每条文本不超过 33,000 个 Token。此限制适用于:
- 字符串数组输入:数组最多包含 10 个元素。
- 文件输入:文本文件最多包含 10 行文本。
多模态向量
| 模型 | 向量维度 | 文本长度限制 | 图片大小限制 | 视频大小限制 |
|---|---|---|---|---|
| qwen3-vl-embedding | 2560(默认)、2048、1536、1024、768、512、256 | 32,000 Token | 单张不超过 10 MB | 不超过 50 MB |
| qwen2.5-vl-embedding | 2048、1024(默认)、768、512 | 32,000 Token | 单张不超过 5 MB | 不超过 50 MB |
| tongyi-embedding-vision-plus-2026-03-06 | 1152(默认)、1024、512、256、128、64 | 1,024 Token | 建议单张不超过 5 MB,最大 10 MB,支持最多 64 张 | 不超过 50 MB,编码类型为 H.264/H.265 |
| tongyi-embedding-vision-flash-2026-03-06 | 768(默认)、512、256、128、64 | 1,024 Token | 建议单张不超过 5 MB,最大 10 MB,支持最多 64 张 | 不超过 50 MB,编码类型为 H.264/H.265 |
| tongyi-embedding-vision-plus | 1152 | 1,024 Token | 单张不超过 3 MB,支持最多 8 张 | 不超过 10 MB |
| tongyi-embedding-vision-flash | 768 | 1,024 Token | 单张不超过 3 MB,支持最多 8 张 | 不超过 10 MB |
| multimodal-embedding-v1 | 1,024 | 512 Token | 单张不超过 3 MB | 不超过 10 MB |
只有文本数据?使用 text-embedding-v4——更快、更便宜、维度选择更多。多模态 Embedding 专为跨模态检索设计(文本+图片、文本+视频)。
输入与语种限制
融合向量模型
| 模型 | 文本 | 图片 | 视频 | 单次请求条数 |
|---|---|---|---|---|
| qwen3-vl-embedding | 中、英、日、韩、法、德等 33 种语言(中文、日语、韩语、印尼语、越南语、泰语、英语、法语、德语、俄语、葡萄牙语、西班牙语、意大利语、瑞典语、丹麦语、捷克语、挪威语、荷兰语、芬兰语、土耳其语、波兰语、斯瓦希里语、罗马尼亚语、塞尔维亚语、希腊语、哈萨克语、乌兹别克语、宿务语、阿拉伯语、乌尔都语、波斯语、印地语/天城语、希伯来语) | JPEG、PNG、WEBP、BMP、TIFF、ICO、DIB、ICNS、SGI(URL 或 Base64) | MP4、AVI、MOV(仅 URL) | 总数不超过 20,图片不超过 10,视频不超过 1 |
| qwen2.5-vl-embedding | 中、英、日、韩、法、德等 11 种语言(中文、英语、日语、韩语、法语、德语、俄语、葡萄牙语、西班牙语、意大利语、印尼语) | JPEG、PNG、WEBP、BMP、TIFF、ICO、DIB、ICNS、SGI(URL 或 Base64) | MP4、AVI、MOV(仅 URL) | 图片、文本、视频、融合对象每种类型最多 1 次 |
| 模型 | 文本 | 图片 | 视频 | 单次请求条数 |
|---|---|---|---|---|
| tongyi-embedding-vision-plus-2026-03-06 | 中、英、日、韩等超 30 种语言(中文、日语、韩语、印尼语、越南语、泰语、英语、法语、德语、俄语、葡萄牙语、西班牙语、意大利语、瑞典语、丹麦语、捷克语、挪威语、荷兰语、芬兰语、土耳其语、波兰语、斯瓦希里语、罗马尼亚语、塞尔维亚语、希腊语、哈萨克语、乌兹别克语、宿务语、阿拉伯语、乌尔都语、波斯语、印地语/天城语、希伯来语) | JPEG、PNG、WEBP、BMP、TIFF、ICO、DIB、ICNS、SGI(URL 或 Base64) | MP4、MPEG、MOV、MPG、WEBM、AVI、FLV、MKV(仅 URL) | 总数不超过 20,图片不超过 64,视频不超过 8 |
| tongyi-embedding-vision-flash-2026-03-06 | 中、英、日、韩等超 30 种语言(中文、日语、韩语、印尼语、越南语、泰语、英语、法语、德语、俄语、葡萄牙语、西班牙语、意大利语、瑞典语、丹麦语、捷克语、挪威语、荷兰语、芬兰语、土耳其语、波兰语、斯瓦希里语、罗马尼亚语、塞尔维亚语、希腊语、哈萨克语、乌兹别克语、宿务语、阿拉伯语、乌尔都语、波斯语、印地语/天城语、希伯来语) | JPEG、PNG、WEBP、BMP、TIFF、ICO、DIB、ICNS、SGI(URL 或 Base64) | MP4、MPEG、MOV、MPG、WEBM、AVI、FLV、MKV(仅 URL) | 总数不超过 20,图片不超过 64,视频不超过 8 |
| tongyi-embedding-vision-plus | 中文与英文 | JPG、PNG、BMP(URL 或 Base64) | MP4、MPEG、MOV、MPG、WEBM、AVI、FLV、MKV(仅 URL) | 无数量限制,Token 数不超过单批次上限 |
| tongyi-embedding-vision-flash | 中文与英文 | JPG、PNG、BMP(URL 或 Base64) | MP4、MPEG、MOV、MPG、WEBM、AVI、FLV、MKV(仅 URL) | 无数量限制,Token 数不超过单批次上限 |
| multimodal-embedding-v1 | 中文与英文 | JPG、PNG、BMP(URL 或 Base64) | MP4、MPEG、MOV、MPG、WEBM、AVI、FLV、MKV(仅 URL) | 总数不超过 20;图片、视频各最多 1 条,文本最多 20 条 |
核心功能
切换向量维度
qwen3.7-text-embedding、text-embedding-v4、text-embedding-v3、tongyi-embedding-vision-plus-2026-03-06、tongyi-embedding-vision-flash-2026-03-06、qwen3-vl-embedding 和 qwen2.5-vl-embedding 支持自定义向量维度。维度越高,保留的语义信息越丰富,但存储和计算开销也更大。
- 通用场景(推荐):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 |