通用文本向量同步接口API详情_模型服务灵积(DashScope)-阿里云帮助中心

前言

通用文本向量，是通义实验室基于LLM底座的多语言文本统一向量模型，面向全球多个主流语种，提供高水准的向量服务，帮助开发者将文本数据快速转换为高质量的向量数据。

模型概览

模型中文名	模型英文名	数据类型	向量维度	最大输入字符长度	支持语种
通用文本向量	text-embedding-v1	float(32)	1536	2048	中文、英语、西班牙语、法语、葡萄牙语、印尼语。
通用文本向量	text-embedding-v2	float(32)	1536	2048	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语。

SDK使用

前提条件

已开通服务并获得API-KEY：API-KEY的获取与配置。
已安装最新版SDK：安装DashScope SDK。

调用示例

说明

SDK支持三种输入，分别是字符串、字符串列表和文件。

说明

需要使用您的API-KEY替换示例中的YOUR_DASHSCOPE_API_KEY，代码才能正常运行。

设置API-KEY

export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

输入字符串

Python

import dashscope
from http import HTTPStatus


def embed_with_str():
    resp = dashscope.TextEmbedding.call(
        model=dashscope.TextEmbedding.Models.text_embedding_v1,
        input='衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买')
    if resp.status_code == HTTPStatus.OK:
        print(resp)
    else:
        print(resp)


if __name__ == '__main__':
    embed_with_str()

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);
  }
}

输入字符串列表

from typing import Generator, List
import dashscope
from http import HTTPStatus


# 最多支持25条，每条最长支持2048tokens
DASHSCOPE_MAX_BATCH_SIZE = 25


def batched(inputs: List,
            batch_size: int = DASHSCOPE_MAX_BATCH_SIZE) -> Generator[List, None, None]:
    for i in range(0, len(inputs), batch_size):
        yield inputs[i:i + batch_size]


def embed_with_list_of_str(inputs: List):
    result = None  # merge the results.
    batch_counter = 0
    for batch in batched(inputs):
        resp = dashscope.TextEmbedding.call(
            model=dashscope.TextEmbedding.Models.text_embedding_v1,
            input=batch)
        if resp.status_code == HTTPStatus.OK:
            if result is None:
                result = resp
            else:
                for emb in resp.output['embeddings']:
                    emb['text_index'] += batch_counter
                    result.output['embeddings'].append(emb)
                result.usage['total_tokens'] += resp.usage['total_tokens']
        else:
            print(resp)
        batch_counter += len(batch)
    print(result)


if __name__ == '__main__':
    inputs = ['风急天高猿啸哀', '渚清沙白鸟飞回', '无边落木萧萧下', '不尽长江滚滚来']
    embed_with_list_of_str(inputs)

输入文件

示例文件如下（文件名称：texts_to_embedding.txt，其中每一行对应一个embedding）。

很不错的一款产品，送人的额，非常喜欢，很不错，好评哦，以后还会多多支持的
已经吃了，感觉不错。第二次购买，这个价格很实惠，卖家还赠送了美容器和尺子，很愉悦的一次购物。
衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买，我一次买了四件不到200块钱，真好
用了一段时间了，感觉比传统的风扇好用，广度大，档数多，静音效果也不错，关键是还很漂亮！
这个热量低，比意面还低，关键是口感还好，挺好吃，多煮一会一级棒，我的减脂早餐就靠它了
整体评价：好 使用效果：好 包装与外观：好 三好商品
电视机很好，我给老爸买的，老人很喜欢，图像清晰，音质很好，老人喜欢我满意。
宝贝很轻巧，打的时候网弹力很足，儿子非常喜欢，五分好评，还送了羽毛球噢！
终于装上，风很大，热的还可以，排风声音不小，安装的师傅说不能直吹，安装的时候非常满意，最后还帮忙把棚顶给擦干净了，非常感谢。
颜色很美。就是别人的盒子都是平整的，唯独我的盒子有很严重的压痕。本来想直接用这个盒子装胶带的..现在这个样子强迫症看着实在很糟心。压成这样要么包装有问题，要么本来产品就有问题。而卖家一直在甩锅快递。由于包裹是被家里人拆开的，所以我也不知道是什么样子的，不好跟卖家掰扯。但我看别的人都是纸盒装的，想来我这个也是纸盒装的。那么排除包装的原因的话，很可能就是寄过来的就是个瑕疵品。比起同样今天到货的另一家，有个小瑕疵立马给我补寄了一个，这家的处理方式真的..换货..或者直接道歉说疏忽我都接受的。甩锅真的不能忍。本来还给好几个人推了这家店...就挺失望的 以后应该不会来了。这坚定的甩锅态度我也不点退换了..请不要给我打电话改评，谢谢。

代码如下：

from http import HTTPStatus
from dashscope import TextEmbedding


def embed_with_file_content():
    # 文件中最多支持25条，每条最长支持2048tokens
    with open('texts_to_embedding.txt', 'r', encoding='utf-8') as f:
        resp = TextEmbedding.call(
            model=TextEmbedding.Models.text_embedding_v1,
            input=f)
        if resp.status_code == HTTPStatus.OK:
            print(resp)
        else:
            print(resp)


if __name__ == '__main__':
    embed_with_file_content()

输出示例

{
    "status_code": 200, // 200 indicate success otherwise failed.
    "request_id": "fd564688-43f7-9595-b986-737c38874a40", // The request id.
    "code": "", // If failed, the error code.
    "message": "", // If failed, the error message.
    "output": {
        "embeddings": [ // embeddings
            {
                "embedding": [ // one embedding output
                    -3.8450357913970947, ...,
                    3.2640624046325684
                ],
                "text_index": 0 // the input index.
            }
        ]
    },
    "usage": {
        "total_tokens": 3 // the request tokens.
    }
}

参数详解

请求参数

参数名称	必选	示例值	描述
model	是	text-embedding-v2	取值：调用的模型名称，可以选择text-embedding-v1或者text-embedding-v2。说明：代表模型的英文名称
input	是	衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买	取值：input可以是字符串，字符串列表，或者打开的文件（需要embedding的内容，1行一条）。说明： input是字符串时最长支持2048tokens input是字符串列表时最多支持25条，每条最长支持2048tokens input是文件时最多支持25条，每条最长支持2048tokens
text_type	否	query	取值：query或者document，默认值为document 说明：文本转换为向量后可以应用于检索、聚类、分类等下游任务，对检索这类非对称任务为了达到更好的检索效果建议区分查询文本（query）和底库文本（document）类型，聚类、分类等对称任务可以不用特殊指定，采用系统默认值"document"即可。

响应参数

字段	类型	描述	示例值
output.embeddings	Array	本次请求的算法输出内容是一个由结构组成的数组，每一个数组中包含一个对应的输入text的算法输出内容。	`{ "embeddings": [ { "text_index": 0, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] }, { "text_index": 1, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] }, { "text_index": 2, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] }, { "text_index": 3, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] } ] }`
output.embeddings.text_index	Integer	本结构中的算法结果对应的输入文字在输入数组中的索引值。	0,1,2,3...
output.embeddings.embedding	Array	对应字符串的算法输出Embedding，Java SDK统一转换为Double，参考模型输出类型，进行比较的数据转换。	`[ -0.006929283495992422, -0.005336422007530928, ... 省略 ]`
usage.input_tokens	Integer	本次请求输入内容的token数目，算法的计量是根据用户输入字符串被模型tokenizer解析之后对应的token数目来进行。	12
request_id	String	本次请求的系统唯一码。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Java SDK输出字段考虑兼容性为double类型，可以按照模型输出类型转换为对应精度数据。

HTTP调用

说明

本模型还可通过HTTP的方式进行调用，以适用更灵活的业务开发，下方示例提供了CURL命令，其中用POST方式请求了接口：https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding

参数详解

请求参数

字段	类型	传参方式	必选	示例值	描述
Content-Type	String	Header	是	application/json	取值：固定值，无需更改。说明：请求类型。
Authorization	String	Header	是	Bearer d1**2a	取值：需要填入您的API-KEY。说明：API-KEY的获取方式参考上方文档中的调用前准备。
model	String	Body	是	text-embedding-v2	取值：调用模型名称，text-embedding-v1或者text-embedding-v2。说明：指明需要调用的模型。
input.texts	Array	Body	是	["风急天高猿啸哀"， "渚清沙白鸟飞回"， "无边落木萧萧下"， "不尽长江滚滚来"]	取值：文本内容，需要计算的输入字符串，支持中英文。说明：支持多条文本输入，每次请求最多25条；每一条最长支持 2048 tokens。
parameters.text_type	String	Body	否	"text_type": "query"	取值：query或document，默认值为document。说明：文本转换为向量后可以应用于检索、聚类、分类等下游任务，对于检索这类非对称任务，为了达到更好的检索效果，建议区分查询文本（query）和底库文本（document）类型，聚类、分类等对称任务可以不用特殊指定，采用系统默认值"document"即可。

响应参数

字段	类型	描述	示例值
output.embeddings	Array	本次请求的算法输出内容是一个由结构组成的数组，每一个数组中包含一个对应的输入text的算法输出内容。	`{ "embeddings": [ { "text_index": 0, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] }, { "text_index": 1, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] }, { "text_index": 2, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] }, { "text_index": 3, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] } ] }`
output.embeddings.text_index	Integer	本结构中的算法结果对应的输入文字在输入数组中的索引值。	0,1,2,3...
output.embeddings.embedding	Array	对应字符串的算法输出embedding。	`[ -0.006929283495992422, -0.005336422007530928, ... 省略 ]`
usage.total_tokens	Integer	本次请求输入内容的token数目，算法的计量是根据用户输入字符串被模型tokenizer解析之后对应的token数目来进行。	12
request_id	String	本次请求的系统唯一码。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Curl示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header 'Authorization: Bearer <your-dashscope-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "text-embedding-v1",
    "input": {
        "texts": [
        "风急天高猿啸哀",
        "渚清沙白鸟飞回", 
        "无边落木萧萧下", 
        "不尽长江滚滚来"
        ]
    },
    "parameters": {
    		"text_type": "query"
    }
}'

响应示例

调用成功示例

{
    "output":{
        "embeddings": [
          {
             "text_index": 0,
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
          }, 
          {
             "text_index": 1,
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
          },
          {
             "text_index": 2,
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
          },
          {
             "text_index": 3,
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
          }
        ]
    },
    "usage":{
        "total_tokens":12
    },
    "request_id":"d89c06fb-46a1-47b6-acb9-bfb17f814969"
}

调用异常示例

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

说明

在访问请求出错的情况下，输出的结果中会通过code和message指明出错原因。

状态码说明

DashScope通用状态码请查阅：返回状态码说明