文本向量化 API--火山方舟大模型服务平台-火山引擎

文档中心

导航

文本向量化 API

最近更新时间：2025.03.19 20:48:55首次发布时间：2024.07.10 20:23:07

POST https://ark.cn-beijing.volces.com/api/v3/embeddings

Doubao-embedding 模型是一款字节跳动研发的语义向量化模型，主要面向向量检索场景，支持中英文输入，可以将文本转化为向量，以方便后续的语义分析。您可以调用服务向模型输入待向量化的文本，服务会将模型处理后的向量信息返回给您。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

鉴权方式

本接口支持 API Key 鉴权方式，详见鉴权认证方式。

请求参数

请求体

参数名称	类型	是否必填	描述	示例值	默认值
model	String	是	本次请求使用模型的 Model ID，或者使用已配置的向量化模型的推理接入点 (Endpoint ID)。	doubao-embedding-text-240515 或 ep-202406040***-***	-
input	String or Array of String	是	需要向量化的内容列表，支持中文、英文。输入字符需要满足：不得超过模型的最大输入 token 数。说明对于 doubao-embdding 模型，每个列表元素（并非单次请求总数）最大输入token 数为 4096。不能为空列表，列表的每个成员不能为空字符串。单条文本以 utf-8 编码，长度不超过 100,000 字节。文本数量不超过 256 条。	["天很蓝", "海很深"]	-
encoding_format	String	否	embedding 返回的格式，可为 `float`或`base64`。	float	float

参数名称

类型

是否必填

描述

示例值

默认值

model

String

是

本次请求使用模型的 Model ID，或者使用已配置的向量化模型的推理接入点 (Endpoint ID)。

doubao-embedding-text-240515
或
ep-202406040*****-*****

input

String or Array of String

是

需要向量化的内容列表，支持中文、英文。输入字符需要满足：

不得超过模型的最大输入 token 数。

说明

对于 doubao-embdding 模型，每个列表元素（并非单次请求总数）最大输入token 数为 4096。

不能为空列表，列表的每个成员不能为空字符串。
单条文本以 utf-8 编码，长度不超过 100,000 字节。
文本数量不超过 256 条。

["天很蓝", "海很深"]

encoding_format

String

否

embedding 返回的格式，可为 float或base64。

float

响应参数

请求响应

参数名称	类型	描述	示例值
id	String	本次请求的唯一标识	021718049470528d92fcbe0865fdffdde********************
model	String	本次请求实际使用的模型名称和版本	doubao-embedding-text-240515
created	Integer	本次请求创建时间的 Unix 时间戳（秒）	1718049470
object	String	固定为 `list`	list
data	Array of Embedding	本次请求的算法输出内容	-
usage	Usage	本次请求的 tokens 用量	-

数据结构

Embedding

参数名称	类型	描述	示例值
index	Integer	向量的序号，与请求参数 `input` 列表中的内容顺序对应	0
embedding	Array	对应内容的向量化结果	[0.01131823007017374, 0.009313009679317474, -0.03317729011178017, 0.00028884236235171556, -0.022333964705467224]
object	String	固定为 `embedding`	embedding

Usage

参数名称	类型	描述	示例值
prompt_tokens	Integer	输入的 prompt token 数量	130
total_tokens	Integer	本次请求消耗的总 token 数量（输入 + 输出）	130

请求示例

curl https://ark.cn-beijing.volces.com/api/v3/embeddings
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ea764f0f-3b60-45b3-****-************" \
  -d '{
    "model": "doubao-embedding-text-240515",
    "input": ["天很蓝", "海很深"]
}'

响应示例

{
    "created": 174****,
    "id": "0217****",
    "data": [
        {
            "embedding": [...],
            "index": 0,
            "object": "embedding"
        },
        {
            "embedding": [...],
            "index": 1,
            "object": "embedding"
        }
    ],
    "model": "doubao-embedding-text-240515",
    "object": "list",
    "usage": {
        "prompt_tokens": 7,
        "total_tokens": 7
    }
}

错误处理

错误响应

本接口调用失败的返回结构和参数释义请参见返回结构文档。

错误码

本接口错误码请参见公共错误码文档。