文档

同步接口API详情

更新时间:

前言

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

模型概览

模型中文名

模型英文名

数据类型

向量维度

最大输入字符长度

支持语种

通用文本向量

text-embedding-v1

float(32)

1536

2048

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

text-embedding-v2

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

SDK使用

前提条件

调用示例

说明

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

说明

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

设置API-KEY

export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

输入字符

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()
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)


输入文件

  1. 示例文件如下(文件名称:texts_to_embedding.txt,其中每一行对应一个embedding)。

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

    from http import HTTPStatus
    from dashscope import TextEmbedding
    
    
    def embed_with_file_content():
        # 文件中最多支持25条,每条最长支持2048tokens
        with open('tests_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.
    }
}

参数详解

  1. 请求参数

    参数名称

    必选

    示例值

    描述

    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"即可。

  2. 响应参数

    字段

    类型

    描述

    示例值

    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

参数详解

  1. 请求参数

    字段

    类型

    传参方式

    必选

    示例值

    描述

    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"即可。

  2. 响应参数

    字段

    类型

    描述

    示例值

    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"
    }
}'

响应示例

  1. 调用成功示例

    {
        "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"
    }
  2. 调用异常示例

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

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

状态码说明

DashScope灵积模型服务通用状态码请查阅:返回状态码说明

  • 本页导读 (0)