通用文本向量快速开始_模型服务灵积(DashScope)-阿里云帮助中心

使用通用文本向量模型可以免去您在本地部署嵌入模型与向量数据库的步骤，且按token进行计费，帮助您降低项目初期的投入成本。

场景示例

推荐：根据输入数据推荐相关条目。例如，根据用户购买历史和浏览记录推荐相关商品。

聚类：按相关性对输入数据进行分组。例如，将海量新闻按主题归类为科技、体育、娱乐等。

搜索：将搜索结果按照与输入数据的相关性进行排序。例如，文本向量模型可以根据用户搜索词语返回相关网页，多模态向量模型可以实现以文搜图。

异常检测：识别出相关性较小的异常值。例如，从大量交易记录中识别出异常交易模式。

支持的模型

模型	向量维度	单行最大处理token长度	单次请求文本最大行数	支持语种
text-embedding-v1	1536	2048	25	中文、英语、西班牙语、法语、葡萄牙语、印尼语
text-embedding-async-v1			100000	中文、英语、西班牙语、法语、葡萄牙语、印尼语
text-embedding-v2			25	在v1基础上：增加日语、韩语、德语、俄罗斯语
text-embedding-async-v2			100000	在v1基础上：增加日语、韩语、德语、俄罗斯语
text-embedding-v3	1024（默认）/768/512	8192	6	在v2基础上：增加到50+语种（含意大利语、波兰语、越南语、泰语等）

模型升级概述

text-embedding-v2
- 语种扩充：新增对日语、韩语、德语、俄罗斯语的文本向量化能力。
- 效果提升：优化了预训练模型和SFT策略，提升了整体效果，公开数据评测结果显示了显著改进。
text-embedding-v3
- 语种扩充：支持意大利语、波兰语、越南语、泰语等，语种数量增加至50+。
- 输入长度扩展：支持最大输入长度从2048 tokens扩展至8192 tokens。
- 连续向量维度自定义：允许用户选择512、768或1024维度，默认最大维度降低至1024，以节省下游任务的使用成本。
- 不再区分Query/Document类型：简化输入，text_type参数不再需要指定文本类型。
- Sparse向量支持：支持输出连续向量和离散向量，用户可在接口中指定。
- 效果提升：进一步优化预训练模型和SFT策略，提升整体效果，公开数据评测结果显示改善。

v1、v2、v3模型的效果数据

模型	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	63.39	55.41	68.92	73.23

text-embedding-v3模型不同维度效果对比

模型	模型维度	MTEB	MTEB（Retrieval task）	CMTEB	CMTEB (Retrieval task)
text-embedding-v3	1024	63.39	55.41	68.92	73.23
text-embedding-v3	768	62.43	54.74	67.90	72.29
text-embedding-v3	512	62.11	54.30	66.81	71.88

归一化处理：text-embedding-v2/v3对输出向量结果默认归一化处理。
向量检索需保持离线与在线使用的向量化模型一致，使用text-embedding-v1构建离线索引数据的场景请勿使用text-embedding-v2作为query请求的向量化模型，反之亦然。

快速调用

调用前准备

您需要已获取API Key并配置API Key到环境变量。如果通过SDK调用，还需要安装DashScope SDK。

代码示例

同步调用示例

同步调用支持输入单条文本，对单条文本进行处理并返回结果。

Python

import dashscope
from http import HTTPStatus

resp = dashscope.TextEmbedding.call(
    model=dashscope.TextEmbedding.Models.text_embedding_v3,
    input='风急天高猿啸哀，渚清沙白鸟飞回，无边落木萧萧下，不尽长江滚滚来',
    dimension=1024
)

print(resp) if resp.status_code == HTTPStatus.OK else print(resp)

Java

import java.util.Arrays;
import java.util.concurrent.Semaphore;
import com.alibaba.dashscope.common.ResultCallback;
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 final class Main {
    public static void basicCall() throws ApiException, NoApiKeyException{
        TextEmbeddingParam param = TextEmbeddingParam
        .builder()
        .model(TextEmbedding.Models.TEXT_EMBEDDING_V1)
        .texts(Arrays.asList("风急天高猿啸哀", "渚清沙白鸟飞回", "无边落木萧萧下", "不尽长江滚滚来")).build();
        TextEmbedding textEmbedding = new TextEmbedding();
        TextEmbeddingResult result = textEmbedding.call(param);
        System.out.println(result);
    }
  
    public static void callWithCallback() throws ApiException, NoApiKeyException, InterruptedException{
        TextEmbeddingParam param = TextEmbeddingParam
        .builder()
        .model(TextEmbedding.Models.TEXT_EMBEDDING_V1)
        .texts(Arrays.asList("风急天高猿啸哀", "渚清沙白鸟飞回", "无边落木萧萧下", "不尽长江滚滚来")).build();
        TextEmbedding textEmbedding = new TextEmbedding();
        Semaphore sem = new Semaphore(0);
        textEmbedding.call(param, new ResultCallback<TextEmbeddingResult>() {

          @Override
          public void onEvent(TextEmbeddingResult message) {
            System.out.println(message);
          }
          @Override
          public void onComplete(){
            sem.release();
          }

          @Override
          public void onError(Exception err){
            System.out.println(err.getMessage());
            err.printStackTrace();
            sem.release();
          }
          
        });
        sem.acquire();
    }

  public static void main(String[] args){
    try{
      callWithCallback();
    }catch(ApiException|NoApiKeyException|InterruptedException e){
      e.printStackTrace();
      System.out.println(e);

    }
      try {
        basicCall();
    } catch (ApiException | NoApiKeyException e) {
        System.out.println(e.getMessage());
    }
    System.exit(0);
  }
}

同步调用输出

{   "status_code": 200, 
    "request_id": "1ba94ac8-e058-99bc-9cc1-7fdb37940a46", 
    "code": "", 
    "message": "",
    "output":{
        "embeddings": [
          {  
             "sparse_embedding":[
               {"index":7149,"value":0.829,"token":"风"},
               .....
               {"index":111290,"value":0.9004,"token":"哀"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 0
          }, 
          {
             "sparse_embedding":[
               {"index":246351,"value":1.0483,"token":"渚"},
               .....
               {"index":2490,"value":0.8579,"token":"回"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 1
          },
          {
             "sparse_embedding":[
               {"index":3759,"value":0.7065,"token":"无"},
               .....
               {"index":1130,"value":0.815,"token":"下"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 2
          },
          {
             "sparse_embedding":[
               {"index":562,"value":0.6752,"token":"不"},
               .....
               {"index":1589,"value":0.7097,"token":"来"}],
             "embedding": [-0.001945948973298072,-0.005336422007530928, ...],
             "text_index": 3
          }
        ]
    },
    "usage":{
        "total_tokens":27
    },
    "request_id":"xxxxxxxx"
}

批处理接口调用

如果您有大批量数据需要处理，可以使用批处理接口。

Python

from dashscope import BatchTextEmbedding

result = BatchTextEmbedding.call(BatchTextEmbedding.Models.text_embedding_async_v1,
                                     url="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241016/nigwvr/text_embedding_file.txt",
                                     text_type="document")
print(result)

Java

import com.alibaba.dashscope.embeddings.BatchTextEmbedding;
import com.alibaba.dashscope.embeddings.BatchTextEmbeddingParam;
import com.alibaba.dashscope.embeddings.BatchTextEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.task.AsyncTaskListResult;
import com.alibaba.dashscope.utils.JsonUtils;


public class Main {
    public static void basicCall() throws ApiException, NoApiKeyException {
        BatchTextEmbeddingParam param = BatchTextEmbeddingParam.builder()
                .model(BatchTextEmbedding.Models.TEXT_EMBEDDING_ASYNC_V1)
                .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241016/nigwvr/text_embedding_file.txt")
                .build();
        BatchTextEmbedding textEmbedding = new BatchTextEmbedding();
        BatchTextEmbeddingResult result = textEmbedding.call(param);
        System.out.println(result);
    }

    public static void main(String[] args) {
        try {
            basicCall();
        } catch (ApiException | NoApiKeyException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Python示例输出

{
    "status_code": 200,
    "request_id": "766b7431-22c9-9a64-9ed3-32b5049c2757",
    "code": null,
    "message": "",
    "output": {
        "task_id": "35a1b2d1-e7b6-4749-90c1-4169e2953508",
        "task_status": "SUCCEEDED",
        "url": "xxx",
        "submit_time": "2024-06-12 11:16:22.096",
        "scheduled_time": "2024-06-12 11:16:22.114",
        "end_time": "2024-06-12 11:16:24.235"
    },
    "usage": {
        "total_tokens": 28
    }
}

了解更多

通用文本向量同步调用代码示例如上，有关通用文本向量模型API的详细调用文档可前往同步接口API详情页面进行了解。批量数据异步接口代码示例详见批处理接口API详情。