OpenAI Embedding接口_模型服务灵积(DashScope)-阿里云帮助中心

DashScope提供了与OpenAI兼容的Embedding使用方式。如果您之前使用OpenAI SDK以及HTTP方式调用OpenAI的Embedding服务，只需在原有框架下调整API-KEY、base_url、model等参数，就可以直接使用DashScope的Embedding服务。

兼容OpenAI需要信息

Base_URL

base_url表示模型服务的网络访问点或地址。通过该地址，您可以访问服务提供的功能或数据。在Web服务或API的使用中，base_url通常对应于服务的具体操作或资源的URL。当您使用OpenAI兼容接口来使用DashScope的Embebbing服务时，需要配置base_url。

当您通过OpenAI SDK或其他OpenAI兼容的SDK调用时，需要配置的base_url如下：
```
https://dashscope.aliyuncs.com/compatible-mode/v1
```
当您通过HTTP请求调用时，需要配置的完整访问endpoint如下：
```
POST https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
```

灵积API-KEY

您需要开通灵积模型服务并获得API-KEY，详情请参考：API-KEY的获取与配置。

支持的模型列表

当前OpenAI兼容接口支持的Embedding模型如下表所示。

模型分类

模型名称

通用文本向量

text-embedding-v1

text-embedding-v2

text-embedding-v3

通过OpenAI SDK调用

前提条件

请确保您的计算机上安装了Python环境。

请安装最新版OpenAI SDK。

# 如果下述命令报错，请将pip替换为pip3
pip install -U openai

已开通灵积模型服务并获得API-KEY：API-KEY的获取与配置。

我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄露风险，配置方法可参考通过环境变量配置API-KEY。您也可以在代码中配置API-KEY，但是泄露风险会提高。

使用方式

您可以参考以下示例来使用OpenAI SDK访问DashScope服务上的Embedding服务。

调用示例

重要

目前仅支持两种输入，分别是字符串、字符串列表

字符串调用示例

from openai import OpenAI
import os

def get_response():
    client = OpenAI(
        api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量，请在此处用您的API Key进行替换
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
    )
    completion = client.embeddings.create(
        model="text-embedding-v1",
        input='衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买',
        encoding_format="float"
        )
    print(completion.model_dump_json())

if __name__ == '__main__':
    get_response()

运行代码可以获得以下结果：

{ 
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... 
        -0.0028842222,
      ],
      "index": 0
    }
  ],
  "model":"text-embedding-v1",
  "object":"list",
  "usage":{"prompt_tokens":23,"total_tokens":23},
  "id":"f62c2ae7-0906-9758-ab34-47c5764f07e2"
}

字符串列表调用示例

from openai import OpenAI
import os

def get_response():
    client = OpenAI(
        api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量，请在此处用您的API Key进行替换
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
    )
    completion = client.embeddings.create(
        model="text-embedding-v1",
        input=['风急天高猿啸哀', '渚清沙白鸟飞回', '无边落木萧萧下', '不尽长江滚滚来'],
        encoding_format="float"
        )
    print(completion.model_dump_json())

if __name__ == '__main__':
    get_response()

运行代码可以获得以下结果：

{ 
  "data": [
    {
      "object": "embedding",
      "embedding": [
        1.4284451007843018,
        -2.7454426288604736,
        .... 
        -2.5092556476593018,
      ],
      "index": 0
    },
    ....
    {
      "object": "embedding",
      "embedding": [
        -0.023244859650731087,
        0.03044375777244568,
        .... 
        -0.012077096849679947,
      ],
      "index": 3
    }
  ],
  "model":"text-embedding-v1",
  "object":"list",
  "usage":{"prompt_tokens":26,"total_tokens":26},
  "id":"c1858f53-e675-93b9-b273-1f6a2809e8cf"
}

输入参数配置

输入参数与OpenAI的接口参数对齐，当前已支持的参数如下：

参数	类型	默认值	说明
model	string	-	用户使用model参数指明对应的模型，可选的模型请见*支持的模型列表。*
input	array	-	用户输入的文本内容，用于计算Embedding的输入；支持字符串或字符数组，支持中英文。重要支持多条文本输入，每次请求最多 25 条；每一条最长支持 2048 tokens。（该说明只适用于V1和V2） text-embedding-v3模型input是字符串列表时最多支持6条，每条最长支持8192tokens
dimensions（可选）	int	-	用于控制返回的embedding的输出向量维度。重要只适用于text-embedding-v3模型, 用户指定的值只能在1024,768, 512三个值之间选取，默认值为1024
encoding_format（可选）	string	-	用于控制返回的embedding格式，当前仅支持float格式。

返回参数说明

返回参数	数据类型	说明	备注
id	string	系统生成的标识本次调用的id。	无
model	string	本次调用的模型名。	无
object	string	本次调用返回的data类型，默认为list。	无
data	list	本次调用返回的embedding数据的内容。	无
data[x].object	string	本次调用返回的object对象类型，默认为embedding。	无
data[x].embedding	list	本次调用返回object对象的value，类型为list float，包含具体embedding向量。	无
data[x].index	int	本次调用返回object对象在数组中的索引编号。	无
usage	object	计量信息，表示本次请求所消耗的token数据。	无
usage.prompt_tokens	integer	用户输入文本转换成token后的长度。	无
usage.total_tokens	integer	等同于usage.prompt_tokens。	无

通过HTTP接口调用

您可以通过HTTP接口来调用Embedding服务，获得与通过HTTP接口调用OpenAI服务相同结构的返回结果。

前提条件

已开通灵积模型服务并获得API-KEY：API-KEY的获取与配置。
我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄露风险，配置方法可参考通过环境变量配置API-KEY。您也可以在代码中配置API-KEY，但是泄露风险会提高。

提交接口调用

POST https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings

请求示例

以下示例展示通过CURL命令来调用API的脚本。

说明

如果您没有配置API-KEY为环境变量，需将$DASHSCOPE_API_KEY更改为您的API-KEY。

字符串调用示例

Shell

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-v1",
    "input": "衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买",
    "encoding_format": "float"
}'

运行代码可以获得以下结果：

{ 
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... 
        -0.0028842222,
      ],
      "index": 0
    }
  ],
  "model":"text-embedding-v1",
  "object":"list",
  "usage":{"prompt_tokens":23,"total_tokens":23},
  "id":"f62c2ae7-0906-9758-ab34-47c5764f07e2"
}

字符串列表调用示例

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-v1",
    "input": [
        "风急天高猿啸哀",
        "渚清沙白鸟飞回", 
        "无边落木萧萧下", 
        "不尽长江滚滚来"
        ],
    "encoding_format": "float"
}'

运行代码可以获得以下结果：

{ 
  "data": [
    {
      "object": "embedding",
      "embedding": [
        1.4284451007843018,
        -2.7454426288604736,
        .... 
        -2.5092556476593018,
      ],
      "index": 0
    },
    ....
    {
      "object": "embedding",
      "embedding": [
        -0.023244859650731087,
        0.03044375777244568,
        .... 
        -0.012077096849679947,
      ],
      "index": 3
    }
  ],
  "model":"text-embedding-v1",
  "object":"list",
  "usage":{"prompt_tokens":26,"total_tokens":26},
  "id":"c1858f53-e675-93b9-b273-1f6a2809e8cf"
}

异常响应示例

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

{
    "error": {
        "message": "Incorrect API key provided. ",
        "type": "invalid_request_error",
        "param": null,
        "code": "invalid_api_key"
    }
}

状态码说明

相关状态错误码信息参考：错误码说明。