向量化模型能够将文本、图像和视频数据转化为数值向量,并用于后续的语义搜索、推荐、聚类、分类、异常检测等任务。
准备工作
您需要已获取API Key并配置API Key到环境变量。如果通过OpenAI SDK或DashScope SDK进行调用,还需要安装SDK。
如何获取Embedding
文本信息向量化
将需要向量化的文本信息连同文本向量模型名称(例如text-embedding-v4)的请求一并发送到相应的 API 接口。
OpenAI兼容接口
import os
from openai import OpenAI
input_texts = "衣服的质量杠杠的"
client = OpenAI(
# 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key="sk-xxx",
# 新加坡和北京地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base-url,如果使用新加坡地域的模型,需要将base_url替换为:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" # 百炼服务的base_url
)
completion = client.embeddings.create(
model="text-embedding-v4",
input=input_texts
)
print(completion.model_dump_json())
const OpenAI = require("openai");
const openai = new OpenAI({
// 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:apikey:'sk-xxx',
// 新加坡和北京地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get
apiKey: process.env.DASHSCOPE_API_KEY,
// 以下是北京地域base-url,如果使用新加坡地域的模型,需要将baseURL替换为:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
});
async function getEmbedding() {
try {
const inputTexts = "衣服的质量杠杠的";
const completion = await openai.embeddings.create({
model: "text-embedding-v4",
input: inputTexts
});
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": "衣服的质量杠杠的"
}'
DashScope
import dashscope
from http import HTTPStatus
# 若使用新加坡地域的模型,请释放下列注释并选择v3模型
# dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"
input_texts = "衣服的质量杠杠的"
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=input_texts,
)
if resp.status_code == HTTPStatus.OK:
print(resp)
import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import java.util.Collections;
public class Main {
/** 若使用新加坡地域的模型,请释放下列注释并选择v3模型
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
} */
public static void main(String[] args) {
String inputTexts = "衣服的质量杠杠的";
try {
// 构建请求参数
TextEmbeddingParam param = TextEmbeddingParam
.builder()
.model("text-embedding-v4")
// 输入文本
.texts(Collections.singleton(inputTexts))
.build();
// 创建模型实例并调用
TextEmbedding textEmbedding = new TextEmbedding();
TextEmbeddingResult result = textEmbedding.call(param);
// 输出结果
System.out.println(result);
} catch (NoApiKeyException e) {
// 捕获并处理API Key未设置的异常
System.err.println("调用 API 时发生异常: " + e.getMessage());
System.err.println("请检查您的 API Key 是否已正确配置。");
e.printStackTrace();
}
}
}
# ======= 重要提示 =======
# 新加坡和北京地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
# 以下为北京地域url,若使用新加坡地域的模型,需将url替换为:https://dashscopep-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation 并选择v3模型
# === 执行时请删除该注释 ===
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": [
"衣服的质量杠杠的"
]
}
}'
多模态向量化
多模态向量化目前仅支持通过DashScope SDK及API调用模型。
import dashscope
import json
from http import HTTPStatus
# 输入可以是视频
# video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
# input = [{'video': video}]
# 或图片
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
resp = dashscope.MultiModalEmbedding.call(
model="tongyi-embedding-vision-plus",
input=input
)
print(json.dumps(resp.output, indent=4))
模型选择
选择合适的模型取决于您的输入数据类型和应用场景。
处理纯文本或代码:推荐使用
text-embedding-v4
。它是当前性能最强的模型,支持任务指令(instruct)、稀疏向量等高级功能,能覆盖绝大多数文本处理场景。处理多模态内容:对于包含图像、文本或视频的混合内容,可以选择针对视觉能力进行优化提升的
tongyi-embedding-vision-plus
与tongyi-embedding-vision-flash
或通用多模态模型multimodal-embedding-v1
。处理大规模数据:若您需要处理大规模、非实时的文本数据,建议使用
text-embedding-v4
并结合 OpenAI兼容-Batch调用,以显著降低成本。
下表包含所有可用向量化模型的详细规格。
文本向量
北京
模型名称 | 向量维度 | 批次大小 | 单次最大处理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 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语 |
新加坡
模型名称 | 向量维度 | 批次大小 | 单次最大处理Token数 | 单价(每千输入Token) | 免费额度(注) | 支持语种 |
text-embedding-v4 属于Qwen3-Embedding系列 | 2,048、1,536、1,024(默认)、768、512、256、128、64 | 10 | 8,192 | 0.000514元 | 无免费额度 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种 |
text-embedding-v3 | 1,024(默认)、768、512、256、128或64 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等50+主流语种 |
批次大小指单次API调用中能处理的文本数量上限。例如,text-embedding-v4的批次大小为10,意味着一次请求最多可传入10个文本进行向量化。这个限制适用于:
字符串数组输入:数组最多包含10个元素。
文件输入:文本文件最多包含10行文本。
多模态向量
模型根据用户的输入生成连续向量,这些输入可以是文本、图片或视频。适用于视频分类、图像分类、图文检索,以文/图搜图,以文/图搜视频等任务场景。
模型名称 | 向量维度 | 文本长度限制 | 图片/视频大小限制 | 单价(每千输入Token) |
tongyi-embedding-vision-plus | 1,152 | 1,024 Token | 图片大小: ≤3MB, 数量≤8张 | 0.0005元 |
tongyi-embedding-vision-flash | 768 | 1,024 Token | 图片大小: ≤3MB, 数量≤8张 | 图片/视频:0.0002元 文本:0.0005元 |
multimodal-embedding-v1 | 1,024 | 512 Token | 图片大小: ≤3MB, 数量1张 | 免费试用,无Token额度限制。 |
通用多模态向量API使用过程中存在以下输入语言与格式限制:
输入类型 | 语种/格式限制 |
文本 | 中/英文 |
图片 | JPG、PNG、BMP,支持以Base64格式或URL形式输入。 |
多图片 | |
视频 | MP4、MPEG、MPG、WEBM、AVI、FLV、MKV、MOV |
接口支持单段文本、单张图片或单个视频文件的上传,也允许不同类型组合(如文本+图片),但每次调用仅限一种组合形式,且请求中每种类型的内容至多包含一项并符合长度/大小要求。
核心功能
切换向量维度
text-embedding-v4
和 text-embedding-v3
支持自定义向量维度。更高的维度能保留更丰富的语义信息,但也会相应增加存储和计算成本。
通用场景(推荐):1024 维度是性能与成本的最佳平衡点,适用于绝大多数语义检索任务。
追求精度:对于高精度要求领域,可选择 1536 或 2048 维度。这会带来一定的精度提升,但存储和计算开销会显著增加。
资源受限:在对成本极其敏感的场景下,可选择 768 及以下维度。这能显著降低资源消耗,但会损失部分语义信息。
OpenAI兼容接口
import os
from openai import OpenAI
client = OpenAI(
# 新加坡和北京地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base-url,如果使用新加坡地域的模型,需要将base_url替换为:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
resp = client.embeddings.create(
model="text-embedding-v4",
input=["喜欢,以后还来这里买"],
# 将向量维度设置为 256
dimensions=256
)
print(f"向量维度: {len(resp.data[0].embedding)}")
DashScope
import dashscope
# 若使用新加坡地域的模型,请释放下列注释
# dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=["喜欢,以后还来这里买"],
# 将向量维度设置为 256
dimension=256
)
print(f"向量维度: {len(resp.output['embeddings'][0]['embedding'])}")
区分查询与文档文本 (text_type)
该参数目前仅支持通过DashScope SDK及API启用。
为了在搜索类任务中取得最佳效果,应根据任务目标对不同的内容进行有针对性的向量化处理,以充分发挥各自的作用。text_type
参数正是为此设计:
text_type: 'query'
:用于用户输入的查询文本。模型将生成一个类似“标题”的向量,更具方向性,专为“提问”和“查找”进行优化。text_type: 'document'
(默认值):用于存入底库的文档文本。模型将生成一个类似“正文”的向量,包含更全面的信息,专为“被匹配”进行优化。
当使用短文本去匹配长文本时,应区分 query
和 document
。而在聚类、分类等所有文本处于相同角色的任务中,则无需设置此参数。
使用任务指令提升效果 (instruct)
该参数目前仅支持通过DashScope SDK及API启用。
通过提供明确的英文任务指令(instruct),可以引导 text-embedding-v4
模型针对特定检索场景优化向量质量,有效提升精度。使用此功能时,必须将 text_type
参数设置为 query
。
# 场景:为搜索引擎构建文档向量时,可以添加指令以优化用于检索的向量质量。
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input="机器学习的相关论文",
text_type="query",
instruct="Given a research paper query, retrieve relevant research paper"
)
稠密与稀疏向量
该参数目前仅支持通过DashScope SDK及API启用。
text-embedding-v4
和text-embedding-v3
支持输出三种类型的向量,以适应不同检索策略的需求。
向量类型 (output_type) | 核心优势 | 主要不足 | 典型应用场景 |
dense | 深度语义理解,能识别同义词和上下文,与召回结果更相关。 | 计算和存储成本较高;无法保证关键词的精确匹配。 | 语义搜索、智能问答、内容推荐。 |
sparse | 高计算效率,专注于关键词的精确匹配和快速过滤。 | 牺牲了语义理解能力,无法处理同义词或上下文。 | 日志检索、商品SKU搜索、精确信息过滤。 |
dense&sparse | 结合语义与关键词,搜索效果最好。生成成本不变,API调用开销与单向量模式相同。 | 存储需求大,系统架构和检索逻辑更复杂。 | 高质量、生产级的混合搜索引擎。 |
应用示例
以下为功能演示代码。在生产环境中,请预先计算向量并持久化存储在向量数据库中,检索时仅需计算查询向量。
语义搜索
通过计算查询与文档之间的向量相似度,实现精准的语义匹配。
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}")
文本聚类
通过分析向量间的距离,将相似的文本自动分组。
# 需要安装 scikit-learn: pip install scikit-learn
import dashscope
import numpy as np
from sklearn.cluster import KMeans
def cluster_texts(texts, n_clusters=2):
"""将一组文本进行聚类"""
# 1. 获取所有文本的向量
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=texts,
dimension=1024
)
embeddings = np.array([item['embedding'] for item in resp.output['embeddings']])
# 2. 使用KMeans算法进行聚类
kmeans = KMeans(n_clusters=n_clusters, random_state=0, n_init='auto').fit(embeddings)
# 3. 整理并返回结果
clusters = {i: [] for i in range(n_clusters)}
for i, label in enumerate(kmeans.labels_):
clusters[label].append(texts[i])
return clusters
# 使用示例
documents_to_cluster = [
"手机公司A发售新款手机",
"搜索引擎公司B推出新款系统",
"世界杯决赛阿根廷对阵法国",
"奥运会中国队再添一金",
"某公司发布最新AI芯片",
"欧洲杯赛事报道"
]
clusters = cluster_texts(documents_to_cluster, n_clusters=2)
for cluster_id, docs in clusters.items():
print(f"--- 类别 {cluster_id} ---")
for doc in docs:
print(f"- {doc}")
文本分类
通过计算输入文本与预定义标签的向量相似度,实现在没有预先标记的示例的情况下,对新类别进行识别和分类。
import dashscope
import numpy as np
def cosine_similarity(a, b):
"""计算余弦相似度"""
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
def classify_text_zero_shot(text, labels):
"""零样本文本分类"""
# 1. 获取输入文本和所有标签的向量
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=[text] + labels,
dimension=1024
)
embeddings = resp.output['embeddings']
text_embedding = embeddings[0]['embedding']
label_embeddings = [emb['embedding'] for emb in embeddings[1:]]
# 2. 计算与每个标签的相似度
scores = [cosine_similarity(text_embedding, label_emb) for label_emb in label_embeddings]
# 3. 返回相似度最高的标签
best_match_index = np.argmax(scores)
return labels[best_match_index], scores[best_match_index]
# 使用示例
text_to_classify = "这件衣服的料子很舒服,款式也好看"
possible_labels = ["数码产品", "服装配饰", "食品饮料", "家居生活"]
label, score = classify_text_zero_shot(text_to_classify, possible_labels)
print(f"输入文本: '{text_to_classify}'")
print(f"最匹配的分类是: '{label}' (相似度: {score:.3f})")
异常检测
通过计算文本向量与正常样本中心的向量相似度,识别出与常规模式显著不同的异常数据。
import dashscope
import numpy as np
def cosine_similarity(a, b):
"""计算余弦相似度"""
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
def detect_anomaly(new_comment, normal_comments, threshold=0.6):
# 1. 向量化所有正常评论和新评论
all_texts = normal_comments + [new_comment]
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=all_texts,
dimension=1024
)
embeddings = [item['embedding'] for item in resp.output['embeddings']]
# 2. 计算正常评论的中心向量(平均值)
normal_embeddings = np.array(embeddings[:-1])
normal_center_vector = np.mean(normal_embeddings, axis=0)
# 3. 计算新评论与中心向量的相似度
new_comment_embedding = np.array(embeddings[-1])
similarity = cosine_similarity(new_comment_embedding, normal_center_vector)
# 4. 判断是否为异常
is_anomaly = similarity < threshold
return is_anomaly, similarity
# 使用示例
normal_user_comments = [
"今天的会议很有成效",
"项目进展顺利",
"下周发布新版本",
"用户反馈良好"
]
test_comments = {
"正常评论": "功能符合预期",
"异常-无意义乱码": "asdfghjkl zxcvbnm"
}
print("--- 异常检测示例 ---")
for desc, comment in test_comments.items():
is_anomaly, score = detect_anomaly(comment, normal_user_comments)
result = "是" if is_anomaly else "否"
print(f"评论: '{comment}'")
print(f"是否为异常: {result} (与正常样本相似度: {score:.3f})\n")
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 |