AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 大模型服务平台百炼 API参考（模型） 工具包/框架 OpenAI兼容-Embedding

OpenAI Embedding接口兼容

更新时间：
产品详情
我的收藏

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

兼容OpenAI需要信息

Base_URL

base_url表示模型服务的网络访问点或地址。通过该地址，您可以访问服务提供的功能或数据。在Web服务或API的使用中，base_url通常对应于服务的具体操作或资源的URL。当您使用OpenAI兼容接口来使用阿里云百炼的Embedding服务时，需要配置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模型如下表所示。

模型名称

数据类型

向量维度

最大行数

单行最大处理Token数（注）

支持语种

text-embedding-v4

属于Qwen3-Embedding系列

float(32)

2,048、1,536、1,024（默认）、768、512、256、128、64

10

8,192

中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种及多种编程语言

text-embedding-v3

1,024（默认）、768、512、256、128或64

中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等50+主流语种

text-embedding-v2

1,536

25

2,048

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

text-embedding-v1

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

通过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访问阿里云百炼服务上的Embedding服务。

调用示例

重要

目前仅支持三种输入，分别是字符串、字符串列表、纯文本文件。

字符串调用示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"  # 百炼服务的base_url
)

completion = client.embeddings.create(
    model="text-embedding-v4",
    input='衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买',
    dimensions=1024, # 指定向量维度（仅 text-embedding-v3及 text-embedding-v4支持该参数）
    encoding_format="float"
)

print(completion.model_dump_json())

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

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

字符串列表调用示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"  # 百炼服务的base_url
)

completion = client.embeddings.create(
    model="text-embedding-v4",
    input=['风急天高猿啸哀', '渚清沙白鸟飞回', '无边落木萧萧下', '不尽长江滚滚来'],
    dimensions=1024,# 指定向量维度（仅 text-embedding-v3及 text-embedding-v4支持该参数）
    encoding_format="float"
)

print(completion.model_dump_json())

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

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

纯文本文件调用示例

此处以texts_to_embedding.txt作为示例文件。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"  # 百炼服务的base_url
)
with open('texts_to_embedding.txt', 'r', encoding='utf-8') as f:
    completion = client.embeddings.create(
        model="text-embedding-v4",
        input=f,
        dimensions=1024,  # 指定向量维度（仅 text-embedding-v3及 text-embedding-v4支持该参数）
        encoding_format="float"      
    )
print(completion.model_dump_json())

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

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

输入参数配置

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

参数

类型

默认值

说明

model

string

-

用户使用model参数指明对应的模型，可选的模型请见支持的模型列表。

input

array

-

用户输入的文本内容，用于计算Embedding的输入；支持字符串或字符数组，支持中英文。

重要

  • 支持多条文本输入，每次请求最多 25 条；每一条最长支持 2048 tokens。（该说明只适用于V1和V2）

  • text-embedding-v3与text-embedding-v4模型input是字符串列表时最多支持10条，每条最长支持8192 tokens

dimensions（可选）

int

-

用于控制返回的embedding的输出向量维度。

重要

只适用于text-embedding-v3与text-embedding-v4模型, 用户指定的值只能在2048（仅适用于text-embedding-v4）、1536（仅适用于text-embedding-v4）、1024、768、512、256、128或64八个值之间选取，默认值为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-v4",
    "input": "衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买",
    "encoding_format": "float"
}'

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

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

字符串列表调用示例

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

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

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

纯文本文件调用示例

此处以texts_to_embedding.txt作为示例文件。

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-v4",
    "input": '"$(cat texts_to_embedding.txt | jq -R -s 'split("\n")[:-1]')"'
}'

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

{
  "output": {
    "embeddings": [
      {
        "embedding": [
          0.029524462297558784,
          -0.09290001541376114,
          ...
          -0.02938840538263321
          ],
        "text_index": 0
      },
      {
        "embedding": [
          0.022696716710925102,
         ....
         -0.02938840538263321
         ],
         "text_index": 4
      }
    ]
  },
  "usage": {
    "total_tokens": 151
  },
  "request_id": "948441e9-3658-94a1-87ec-84b6338a29dc"
}

异常响应示例

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

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

状态码说明

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

上一篇：OpenAI兼容-Batch下一篇：LangChain