embedding v2--向量数据库VikingDB-火山引擎

文档中心

立即注册

导航

embedding v2

最近更新时间：2025.02.19 21:15:05首次发布时间：2024.04.17 14:21:07

embedding v2接口

说明

embedding 接口升级为 v2 版本，新增长文本窗口模型及稀疏向量产出，支持用量统计。建议迁移到 v2 接口使用 embedding 功能。

data/embedding/version/2 接口用于请求 Embedding 服务，通过深度学习神经网络提取文本、图片、音视频等非结构化数据里的内容和语义，把文本、图片、音视频等变成特征向量。

说明

当前 Embedding 服务支持将文本/图片生成向量。
当前对 Embedding 模型设置了 TPM（Tokens Per Minute，每分钟 tokens 数量）的调用限制，每个账号（含主账号下的所有子账号，合并计算）的 TPM 不超过 120000/模型。
图片大小：建议图片大小不要超过1MB，因embedding v2接口的请求限制为4M，当图片超过1MB时，我们建议用户压缩图片后再次请求，防止接口截断；
图片压缩尺寸推荐：经过我们的实验，将图片的长和宽分别缩放到自身的0.30-0.35倍，可以得到与原图embedding较为相近的结果。其中，0.30-0.35倍是缩放的拐点，比例再低的话精度劣化会比较明显，缩放比例可以在拐点以上。
当前图片 embedding 限制每秒上传15张图，如果超出限制请及时联系客服扩大限流。

请求接口

说明

请求 Embedding 服务的 OpenAPI 接口时，需要构造签名进行鉴权，详细的 OpenAPI 签名调用方法请参见 API签名调用指南。

URI	/api/data/embedding/version/2	统一资源标识符
方法	POST/GET	客户端对Embedding服务请求的操作类型
请求头	Content-Type: application/json	请求消息类型
请求头	Authorization: HMAC-SHA256 ***	鉴权

请求参数

参数	子参数	类型	是否必选	说明
model	model_name	string	是	指定模型名称，当前支持的模型有： doubao-embedding：字节跳动研发的语义向量化模型，支持中英双语，最长 4K 上下文长度。输出最高维度 2048 的稠密向量，支持 512, 1024 降维使用。当TPM超过5000时请前往火山方舟平台使用。说明 doubao-embedding 包括 240515 和 240715 两个版本，可通过 `model_version` 参数切换。 240715 版本中英文 Retrieval 效果较 240515 版本有较大提升。 doubao-embedding-large：字节跳动语义向量化模型的最新升级版，采用能力更强的豆包语言模型为基座，支持中、英双语，最长 4K 上下文长度。输出最高维度 4096 的稠密向量，支持2048, 1024, 512降维使用。当TPM超过5000时请前往火山方舟平台使用。 doubao-embedding-vision：字节自研的图文多模态向量化模型，主要面向图文多模向量检索的使用场景，支持图片输入及中、英双语文本输入，最长 8K 上下文长度。输出 3072 维的稠密向量。当TPM超过5000时请前往火山方舟平台使用。 bge-large-zh：最多能处理 512 个 token，数量超长时会截断，数量不足时会做 padding。输出 embedding 维度是 1024，类型是 float。 bge-m3：基于 m3 模型，默认返回稠密向量和稀疏向量。最多能处理 8192 个 token，数量超长时会截断，数量不足时会做 padding。输出稠密向量维度是 1024，类型是 float。输出稀疏向量为字典类型，k 为 Tokenizer 输出的 token，v 为这个 token 的权重。 bge-large-zh-and-m3：基于 bge v1.5 和m3 模型，使用混合检索模式。稠密向量由 bge v1.5 抽取，稀疏向量由 bge m3 抽取。最多能处理 512 个 token，数量超长时会截断，数量不足时会做 padding。输出稠密向量维度是 1024，类型是 float。输出稀疏向量为字典类型，k 为 Tokenizer 输出的 token，v 为这个 token 的权重。 bge-visualized-m3：基于Visualized-BGE和m3 模型，可对文本或图片进行单独编码，或者对文本图片对联合编码，输出1024维的稠密向量。文本token限制为3702，数量超长时会截断，数量不足时会做 padding。
model	params	map	否	模型参数: return_token_usage - 返回请求消耗的token数，默认关闭。 return_dense - 返回稠密向量，默认打开。 return_sparse - 返回稀疏向量，支持提取稀疏向量的模型默认打开, 其他模型开启了会报错。 embedding_dimension - 用于对向量化结果降维。 model_version - 用于切换模型版本。若模型有多版本，可以指定，不填则使用默认版本。当前doubao-embedding 模型支持"240515"（默认）和"240715"版本
data 说明最大 100 个。	data_type	string	是	支持如下类型： text：文本 image：图片 text-image：文本-图片对联合编码
	text	string	data_type 为 text 或 text-image时，必选	data_type=text时，直接传入文本string
	image	string	data_type 为 image 或 text-image时，必选	data_type=image时，传入图片内容的base64编码

响应消息

参数	参数说明
code	状态码
message	返回信息
request_id	标识每个请求的唯一标识符
data	字典类型，现在包含 { "sentence_dense_embedding":[ [0.23, 0.54, 0.76], ... ], "sentence_sparse_embedding":[ {'De': 0.05005, 'fin': 0.1368, 'ation': 0.04498, 'of': 0.0633, 'BM': 0.2515, '25': 0.3335}, ... ], "token_usage": { "prompt_tokens": 8, "completion_tokens": 0, "total_tokens": 8 // 消耗的token数 } } sentence_dense_embedding 的值为二维向量，形状为[batch_size, embedding_size] sentence_sparse_embedding 的值为列表，形状为[batch_size]，列表内的元素为字典 {"token": value} 下标一致的稠密向量和稀疏向量对应同一文本 token_usage 请求的消耗的 token 数

状态码说明

状态码	http状态码	返回信息	状态码说明
0	200	success	请求 Embedding 服务成功。
1000003	400	invalid request：%s	非法参数：缺失必选参数, 如 model_name。字段值与字段类型不匹配。
1000001	401	unauthorized	请求头中缺乏鉴权信息。
1000025	404	failed to calcTextEmbedding	请求模型服务失败：模型名称不对。输入类型和模型对应不上。

完整示例

embedding v2请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/data/embedding/version/2 \
  -d '{
        "model": {
                "model_name": "doubao-embedding"，
                "params":{
                    "return_dense":true,
                    "return_sparse":true,
                    "return_token_usage":true，
                }
        },
        "data": [
                {
                        "data_type": "text",
                        "text": "如何使用torchserve部署模型"
                },
                {
                        "data_type": "text",
                        "text": "怎么使用训练机器学习模型"
                }
        ]
}'

embedding v2响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "message":"success",
    "request_id":"021695029736548fd001de66666000000000000000000029aa917",
    "sentence_dense_embedding":[
        [0.23, 0.54, 0.76],
        [0.57, 0.93, 0.21]，
        ],
        "sentence_sparse_embedding":[
        {'如何': 0.05005, '使用': 0.1368, 'torchserve': 0.04498, '部署': 0.0633, '模型': 0.251},
        {'怎么': 0.0352, '使用': 0.5238, '训练': 0.2356, '机器学习': 0.2456, '模型': 0.42},
        ...
        ],
}

执行失败返回：

HTTP/1.1 404 OK
Content-Length: 43
Content-Type: application/json
 
{"message":"failed to calcTextEmbedding, ModelNotFoundException: Model not found: bge-large-zh","code":1000025, "request_id":"021695029736548fd001de66666000000000000000000029aa917"}