文档

OpenAI Embedding接口兼容

更新时间:

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

字符串调用示例

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

状态码说明

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