向量化(Embedding)

向量化模型能够将文本、图像和视频数据转化为向量形式,并用于后续的语义检索、推荐等向量相关任务。

快速开始

前提条件

您需要已获取API Key配置API Key到环境变量。如果通过OpenAI SDKDashScope 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"
    }
}'

返回数据

{
  "status_code": 200,
  "request_id": "{Request_ID}",
  "code": "",
  "message": "",
  "output": {
    "embeddings": [
      {
        "embedding": [
          0.00954423751682043,
          -0.11166470497846603,
          ...,
          -0.04273410513997078,
          0.020349575206637383
        ],
        "text_index": 0
      },
      {
        "embedding": [
          0.00954423751682043,
          -0.11166470497846603,
          ...,
          -0.04273410513997078,
          0.020349575206637383
        ],
        "text_index": 1
      },
      {
        "embedding": [
          0.00954423751682043,
          -0.11166470497846603,
          ...,
          -0.04273410513997078,
          0.020349575206637383
        ],
        "text_index": 2
      }
    ]
  },
  "usage": {
    "total_tokens": 23
  }
}

使用建议

以下参数目前仅支持通过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-v4text-embedding-v3支持输出三种类型的向量,以适应不同检索策略的需求。

向量类型 (output_type)

核心优势

主要不足

典型应用场景

dense

深度语义理解,能识别同义词和上下文,与召回结果更相关。

计算和存储成本较高;无法保证关键词的精确匹配。

语义搜索、智能问答、内容推荐。

sparse

高计算效率,专注于关键词的精确匹配和快速过滤。

牺牲了语义理解能力,无法处理同义词或上下文。

日志检索、商品SKU搜索、精确信息过滤。

dense&sparse

结合语义与关键词,搜索效果最好。生成成本不变,API调用开销与单向量模式相同。

存储需求大,系统架构和检索逻辑更复杂。

高质量、生产级的混合搜索引擎。

选型指南

模型选择

输入类型

推荐模型

说明

纯文本或代码片段内容

text-embedding-v4

性能最强,支持指令、稀疏向量等高级功能,适用于绝大多数文本处理场景。

图/文/视频 混合的多模态内容

multimodal-embedding-v1

专为多模态内容设计,支持图文混合输入。

大规模文本内容

text-embedding-v4Batch接口调用

针对大规模、非实时场景优化,成本更低。

向量维度选择

text-embedding-v4text-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"
}'

返回数据

{
  "data": [
    {
      "embedding": [
        0.02258586511015892,
        -0.08700370043516159,
        ...,
        -0.04443585127592087,
        0.01706676371395588
      ],
      "index": 0,
      "object": "embedding"
    },
    {
      "embedding": [
        -0.004948599264025688,
        -0.11116065084934235,
        ...,
        -0.04273410513997078,
        0.020349575206637383
      ],
      "index": 1,
      "object": "embedding"
    },
    {
      "embedding": [
        0.00562852481380105,
        -0.0997127890586853,
        ...,
        -0.04273410513997078,
        0.020349575206637383
      ],
      "index": 2,
      "object": "embedding"
    }
  ],
  "model": "text-embedding-v4",
  "object": "list",
  "usage": {
    "prompt_tokens": 23,
    "total_tokens": 23
  },
  "id": "{Request_ID}"
}

多模态向量化

多模态向量化目前仅支持通过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))
    

返回数据

{
    "status_code": 200,
    "request_id": "23478d14-55c6-98cc-9706-29d23de742fb",
    "code": "",
    "message": "",
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.0396728515625,
                    0.00650787353515625,
                    -0.0223388671875,
                    ...
                ],
                "type": "image"
            }
        ]
    },
    "usage": {
        "input_tokens": 0,
        "image_count": 1,
        "duration": 0
    }
}

应用示例

语义搜索

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

100Token

有效期:百炼开通后90天内

中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种

text-embedding-v3

1,024(默认)、768、512、256、12864

0.0005

Batch接口调用:0.00025

50Token

有效期:百炼开通后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

2000Token

有效期:百炼开通后90天内

中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语

text-embedding-async-v1

中文、英语、西班牙语、法语、葡萄牙语、印尼语

说明

批次大小指单次API调用中能处理的文本数量上限。例如,text-embedding-v4的批次大小为10,意味着一次请求最多可传入10个文本进行向量化。这个限制适用于:

  • 字符串数组输入:数组最多包含10个元素。

  • 文件输入:文本文件最多包含10行文本。

多模态向量

模型根据用户的输入生成连续向量,这些输入可以是文本、图片或视频。适用于视频分类、图像分类、图文检索等任务场景。

模型名称

向量维度

单价

multimodal-embedding-v1

1,024

免费试用,无Token额度限制。

通用多模态向量API使用过程中存在以下输入类型与格式限制:

输入类型

语种/格式限制

长度/大小限制

文本

中/英文

512Token, 超过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