百炼提供了与OpenAI兼容的Embedding使用方式。如果您之前使用OpenAI SDK以及HTTP方式调用OpenAI的Embedding服务,只需在原有框架下调整API-KEY、base_url、model等参数,就可以直接使用百炼的Embedding服务。
兼容OpenAI需要信息
Base_URL
base_url表示模型服务的网络访问点或地址。通过该地址,您可以访问服务提供的功能或数据。在Web服务或API的使用中,base_url通常对应于服务的具体操作或资源的URL。当您使用OpenAI兼容接口来使用百炼的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访问百炼服务上的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", # 填写百炼服务的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", # 填写百炼服务的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的输入;支持字符串或字符数组,支持中英文。 重要
|
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"
}
}
状态码说明
相关状态错误码信息参考:状态码说明。