向量化模型能够将文本、图像和视频数据转化为向量形式,并用于后续的语义检索、推荐等向量相关任务。
快速开始
前提条件
您需要已获取API Key并配置API Key到环境变量。如果通过OpenAI SDK或DashScope SDK进行调用,还需要安装SDK。
将需要向量化的文本信息连同文本向量模型名称(例如text-embedding-v4)的请求一并发送到相应的 API 接口。
import dashscope
from http import HTTPStatus
# 输入可以是单个字符串
# input_texts = "衣服的质量杠杠的,很漂亮,不枉我等了这么久啊,喜欢,以后还来这里买"
# 或字符串列表 (推荐,效率更高)
input_texts = ['衣服的质量杠杠的', '很漂亮,不枉我等了这么久啊', '喜欢,以后还来这里买']
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=input_texts,
# 仅 text-embedding-v3及 text-embedding-v4支持以下参数
dimension=1024, # 指定向量维度
output_type="dense", # 指定输出稠密向量(dense)/稀疏向量(sparse)/同时输出两种向量(dense&sparse)
# 仅 text-embedding-v4支持以下参数
instruct="A positive comment from a customer"
)
if resp.status_code == HTTPStatus.OK:
# `resp.output['embeddings']` 是一个列表,每个元素对应一个输入文本的向量结果
print(resp)
else:
print(f"请求失败: {resp}")
print("\n请根据 status_code 前往阿里云帮助中心查询错误详情:")
print("https://help.aliyun.com/zh/model-studio/error-code")
import java.util.Arrays;
import java.util.List;
import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
/**
* 通义千问文本向量模型调用示例
*/
public class Main {
public static void main(String[] args) {
try {
// 输入可以是单个字符串
// String input_texts = "衣服的质量杠杠的,很漂亮,不枉我等了这么久啊,喜欢,以后还来这里买";
// 或字符串列表 (推荐,效率更高)
List<String> input_texts = Arrays.asList("衣服的质量杠杠的","很漂亮,不枉我等了这么久啊","喜欢,以后还来这里买");
// 构建请求参数
TextEmbeddingParam param = TextEmbeddingParam
.builder()
// 使用text-embedding-v3模型
.model("text-embedding-v4")
// 输入文本
.texts(input_texts)
// 设置向量维度
// 仅 text-embedding-v3及 text-embedding-v4支持以下参数
.parameter("dimension", 2048)
// 指定输出稠密向量(dense)/稀疏向量(sparse)/同时输出两种向量(dense&sparse)
.parameter("output_type","dense")
// 仅 text-embedding-v4支持以下参数
// 任务说明参数,引导模型理解任务意图
.parameter("instruct","A positive comment from a customer")
.build();
// 创建模型实例并调用
TextEmbedding textEmbedding = new TextEmbedding();
TextEmbeddingResult result = textEmbedding.call(param);
// 输出结果
System.out.println(result);
} catch (ApiException e) {
// 捕获并处理API调用失败的异常
System.err.println("请求失败,捕获到 ApiException: " + e.getMessage());
System.err.println("错误码 (Code): " + e.getStatus().getCode());
System.err.println("请求 ID (RequestId): " + e.getStatus().getRequestId());
System.err.println("\n建议您根据错误码前往阿里云帮助中心查询错误详情:");
System.err.println("https://help.aliyun.com/zh/model-studio/error-code");
e.printStackTrace();
} catch (NoApiKeyException e) {
// 捕获并处理API Key未设置的异常
System.err.println("调用 API 时发生异常: " + e.getMessage());
System.err.println("请检查您的 API Key 是否已正确配置。");
e.printStackTrace();
}
}
}
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "text-embedding-v4",
"input": {
"texts": [
"衣服的质量杠杠的",
"很漂亮,不枉我等了这么久啊",
"喜欢,以后还来这里买"
]
},
"output_type":"dense",
"parameters": {
"dimension": 1024,
"instruct": "A positive comment from a customer"
}
}'
返回数据
使用建议
以下参数目前仅支持通过DashScope SDK启用。
使用任务指令提升效果 (instruct)
通过为向量化任务提供明确的英文指令(instruct),可以引导模型更好地理解任务意图,在特定检索场景下有效提升精度。此功能仅text-embedding-v4支持。
# 场景:为搜索引擎构建文档向量时,可以添加指令以优化用于检索的向量质量。
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input="机器学习是实现人工智能的一种方法。",
parameters={
"instruction": "Represent the document for retrieval."
}
)
稠密与稀疏向量
text-embedding-v4
和text-embedding-v3
支持输出三种类型的向量,以适应不同检索策略的需求。
向量类型 (output_type) | 核心优势 | 主要不足 | 典型应用场景 |
dense | 深度语义理解,能识别同义词和上下文,与召回结果更相关。 | 计算和存储成本较高;无法保证关键词的精确匹配。 | 语义搜索、智能问答、内容推荐。 |
sparse | 高计算效率,专注于关键词的精确匹配和快速过滤。 | 牺牲了语义理解能力,无法处理同义词或上下文。 | 日志检索、商品SKU搜索、精确信息过滤。 |
dense&sparse | 结合语义与关键词,搜索效果最好。生成成本不变,API调用开销与单向量模式相同。 | 存储需求大,系统架构和检索逻辑更复杂。 | 高质量、生产级的混合搜索引擎。 |
选型指南
模型选择
输入类型 | 推荐模型 | 说明 |
纯文本或代码片段内容 | text-embedding-v4 | 性能最强,支持指令、稀疏向量等高级功能,适用于绝大多数文本处理场景。 |
图/文/视频 混合的多模态内容 | multimodal-embedding-v1 | 专为多模态内容设计,支持图文混合输入。 |
大规模文本内容 | text-embedding-v4Batch接口调用 | 针对大规模、非实时场景优化,成本更低。 |
向量维度选择
text-embedding-v4
和text-embedding-v3
支持多种向量维度的选择,更高的维度能保留更多语义信息,但也会增加存储和计算成本。(例如,一个 1024 维度的向量包含 1024 个数值)。
维度大小 | 推荐场景 | 成本与性能平衡性 |
1024 | 通用场景(推荐) | 性能与成本的平衡点。适用于绝大多数语义检索。 |
1536/2048 | 追求极致精度 | 精度略有提升,但存储和计算开销显著增加,适用于金融、科研等高精度要求领域。 |
768及以下 | 资源受限或边缘计算 | 显著降低成本,但会损失部分语义信息,适用于边缘计算或对成本极其敏感的场景。 |
OpenAI兼容接口调用
import os
from openai import OpenAI
# 输入可以是单个字符串
# input_texts = "衣服的质量杠杠的,很漂亮,不枉我等了这么久啊,喜欢,以后还来这里买"
# 或字符串列表 (推荐,效率更高)
input_texts = ['衣服的质量杠杠的', '很漂亮,不枉我等了这么久啊', '喜欢,以后还来这里买']
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量,请在此处用您的API Key进行替换
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" # 百炼服务的base_url
)
completion = client.embeddings.create(
model="text-embedding-v4",
input=input_texts,
dimensions=1024, # 指定向量维度(仅 text-embedding-v3及 text-embedding-v4支持该参数)
)
print(completion.model_dump_json())
const OpenAI = require("openai");
// 初始化 openai 客户端
const openai = new OpenAI({
// 确保您已经正确设置了环境变量 DASHSCOPE_API_KEY
apiKey: process.env.DASHSCOPE_API_KEY, // 如果您没有配置环境变量,请在此处用您的API Key进行替换
baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
});
async function getEmbedding() {
try {
// 输入可以是单个字符串
// const inputTexts = "衣服的质量杠杠的,很漂亮,不枉我等了这么久啊,喜欢,以后还来这里买";
// 或字符串列表 (推荐,效率更高)
const inputTexts = ['衣服的质量杠杠的', '很漂亮,不枉我等了这么久啊', '喜欢,以后还来这里买'];
const completion = await openai.embeddings.create({
model: "text-embedding-v4",
input: inputTexts,
dimensions: 1024 // 指定向量维度(仅 text-embedding-v3及 text-embedding-v4支持该参数)
});
console.log(JSON.stringify(completion, null, 2));
} catch (error) {
console.error('Error:', error);
}
}
getEmbedding();
curl --location 'https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "text-embedding-v4",
"input": [
"衣服的质量杠杠的",
"很漂亮,不枉我等了这么久啊",
"喜欢,以后还来这里买"
],
"dimension": "1024"
}'
返回数据
多模态向量化
多模态向量化目前仅支持通过DashScope SDK调用multimodal-embedding-v1
模型。
您需要已获取API Key并配置API Key到环境变量。如果通过SDK调用,还需要安装DashScope SDK。
文本输入
import dashscope
import json
from http import HTTPStatus
text = "通用多模态表征模型示例"
input = [{'text': text}]
resp = dashscope.MultiModalEmbedding.call(
model="multimodal-embedding-v1",
input=input
)
if resp.status_code == HTTPStatus.OK:
print(json.dumps(resp.output, ensure_ascii=False, indent=4))
图片输入
import dashscope
import json
from http import HTTPStatus
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
resp = dashscope.MultiModalEmbedding.call(
model="multimodal-embedding-v1",
input=input
)
if resp.status_code == HTTPStatus.OK:
print(json.dumps(resp.output, ensure_ascii=False, indent=4))
视频输入
multimodal-embedding-v1模型仅支持以URL形式输入视频文件,暂不支持直接传入本地视频。
import dashscope
import json
from http import HTTPStatus
# 实际使用中请将url地址替换为您的视频url地址
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
input = [{'video': video}]
# 调用模型接口
resp = dashscope.MultiModalEmbedding.call(
model="multimodal-embedding-v1",
input=input
)
if resp.status_code == HTTPStatus.OK:
print(json.dumps(resp.output, ensure_ascii=False, indent=4))
返回数据
应用示例
语义搜索
import dashscope
import numpy as np
from dashscope import TextEmbedding
def cosine_similarity(a, b):
"""计算余弦相似度"""
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
def semantic_search(query, documents, top_k=5):
"""语义搜索"""
# 生成查询向量
query_resp = TextEmbedding.call(
model="text-embedding-v4",
input=query,
dimension=1024
)
query_embedding = query_resp.output['embeddings'][0]['embedding']
# 生成文档向量
doc_resp = TextEmbedding.call(
model="text-embedding-v4",
input=documents,
dimension=1024
)
# 计算相似度
similarities = []
for i, doc_emb in enumerate(doc_resp.output['embeddings']):
similarity = cosine_similarity(query_embedding, doc_emb['embedding'])
similarities.append((i, similarity))
# 排序并返回top_k结果
similarities.sort(key=lambda x: x[1], reverse=True)
return [(documents[i], sim) for i, sim in similarities[:top_k]]
# 使用示例
documents = [
"人工智能是计算机科学的一个分支",
"机器学习是实现人工智能的重要方法",
"深度学习是机器学习的一个子领域"
]
query = "什么是AI?"
results = semantic_search(query, documents, top_k=2)
for doc, sim in results:
print(f"相似度: {sim:.3f}, 文档: {doc}")
推荐系统
import dashscope
import numpy as np
from dashscope import TextEmbedding
def cosine_similarity(a, b):
"""计算余弦相似度"""
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
def build_recommendation_system(user_history, all_items, top_k=10):
"""构建推荐系统"""
# 生成用户历史向量
history_resp = TextEmbedding.call(
model="text-embedding-v4",
input=user_history,
dimension=1024
)
# 计算用户偏好向量(取平均)
user_embedding = np.mean([
emb['embedding'] for emb in history_resp.output['embeddings']
], axis=0)
# 生成所有物品向量
items_resp = TextEmbedding.call(
model="text-embedding-v4",
input=all_items,
dimension=1024
)
# 计算推荐分数
recommendations = []
for i, item_emb in enumerate(items_resp.output['embeddings']):
score = cosine_similarity(user_embedding, item_emb['embedding'])
recommendations.append((all_items[i], score))
# 排序并返回推荐结果
recommendations.sort(key=lambda x: x[1], reverse=True)
return recommendations[:top_k]
# 使用示例
user_history = ["科幻类", "动作类", "悬疑类"]
all_movies = ["未来世界", "太空探险", "古代战争", "浪漫之旅", "超级英雄"]
recommendations = build_recommendation_system(user_history, all_movies)
for movie, score in recommendations:
print(f"推荐分数: {score:.3f}, 电影: {movie}")
模型列表
下表包含所有可用向量化模型的详细规格、价格和限制。
文本向量
模型名称 | 向量维度 | 批次大小 | 单行最大处理Token数 | 单价(每千输入Token) | 免费额度(注) | 支持语种 |
text-embedding-v4 属于Qwen3-Embedding系列 | 2,048、1,536、1,024(默认)、768、512、256、128、64 | 10 | 8,192 | 0.0005元 Batch接口调用:0.00025元 | 100万Token 有效期:百炼开通后90天内 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种 |
text-embedding-v3 | 1,024(默认)、768、512、256、128或64 | 0.0005元 Batch接口调用:0.00025元 | 各50万Token 有效期:百炼开通后90天内 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等50+主流语种 | ||
text-embedding-v2 | 1,536 | 25 | 2,048 | 0.0007元 Batch接口调用:0.00035元 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语 | |
text-embedding-v1 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语 | |||||
text-embedding-async-v2 | 100,000 | 0.0007元 | 2000万Token 有效期:百炼开通后90天内 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语 | ||
text-embedding-async-v1 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语 |
批次大小指单次API调用中能处理的文本数量上限。例如,text-embedding-v4的批次大小为10,意味着一次请求最多可传入10个文本进行向量化。这个限制适用于:
字符串数组输入:数组最多包含10个元素。
文件输入:文本文件最多包含10行文本。
多模态向量
模型根据用户的输入生成连续向量,这些输入可以是文本、图片或视频。适用于视频分类、图像分类、图文检索等任务场景。
模型名称 | 向量维度 | 单价 |
multimodal-embedding-v1 | 1,024 | 免费试用,无Token额度限制。 |
通用多模态向量API使用过程中存在以下输入类型与格式限制:
输入类型 | 语种/格式限制 | 长度/大小限制 |
文本 | 中/英文 | 512个Token, 超过512Token长度的文本内容将会被截断 |
图片 | JPG、PNG、BMP | 支持以Base64格式或URL形式输入。可接受的图片大小上限为 3MB |
视频 | MP4、MPEG、MPG、WEBM、AVI、FLV、MKV、MOV | 可接受的视频大小上限为 10MB |
接口支持单段文本、单张图片或单个视频文件的上传,也允许不同类型组合(如文本+图片),但每次调用仅限一种组合形式,且每轮对话中每种类型的内容至多包含一项并符合长度/大小要求。
API参考
通用文本向量
多模态向量
错误码
如果模型调用失败并返回报错信息,请参见错误信息进行解决。
限流
关于模型的限流条件,请参见限流。
模型性能(MTEB/CMTEB)
评测基准
MTEB:大规模文本嵌入评测基准,综合评估分类、聚类、检索等任务的通用性。
CMTEB:中文大规模文本嵌入评测基准,专门针对中文文本的评测。
分数范围0-100,数值越高代表效果越优。
模型 | MTEB | MTEB(Retrieval task) | CMTEB | CMTEB (Retrieval task) |
text-embedding-v1 | 58.30 | 45.47 | 59.84 | 56.59 |
text-embedding-v2 | 60.13 | 49.49 | 62.17 | 62.78 |
text-embedding-v3(64维度) | 57.40 | 46.52 | 59.19 | 62.03 |
text-embedding-v3(128维度) | 60.19 | 52.51 | 63.81 | 68.22 |
text-embedding-v3(256维度) | 61.13 | 54.41 | 65.92 | 71.07 |
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 |