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

文档中心

立即注册

导航

embedding v2

最近更新时间：2025.05.20 15:26:11首次发布时间：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	字节跳动研发的语义向量化模型，支持中英双语。当TPM超过5000时请前往火山方舟平台使用。输出稠密向量维度：2048，支持 512, 1024 降维使用是否返回稀疏向量：否支持的模态：文本最长上下文长度：4K 模型的计费规则可以前往向量库计费查看说明 doubao-embedding 包括 240515 和 240715 两个版本，可通过 `model_version` 参数切换。 240715 版本中英文 Retrieval 效果较 240515 版本有较大提升。
				doubao-embedding-and-m3	输出稠密向量维度： 2048，支持 512, 1024 降维使用是否返回稀疏向量：是支持的模态：文本最长上下文长度：4K 模型的计费规则可以前往向量库计费查看
				doubao-embedding-large	字节跳动语义向量化模型的最新升级版，采用能力更强的豆包语言模型为基座，支持中、英双语，当TPM超过5000时请前往火山方舟平台使用输出稠密向量维度： 4096 ，支持2048, 1024, 512降维使用是否返回稀疏向量：否支持的模态：文本最长上下文长度：4K 模型的计费规则可以前往向量库计费查看
				doubao-embedding-large-and-m3	输出稠密向量维度： 4096 ，支持2048, 1024, 512降维使用是否返回稀疏向量：是支持的模态：文本最长上下文长度：4K 模型的计费规则可以前往向量库计费查看
				doubao-embedding-vision	字节自研的图文多模态向量化模型，主要面向图文多模向量检索的使用场景，支持图片输入及中、英双语文本输入，最长 8K 上下文长度。当TPM超过5000时请前往火山方舟平台使用。输出稠密向量维度：2048，支持1024 降维使用是否返回稀疏向量：否支持的模态：文本、图片最长上下文长度：8K 模型的计费规则可以前往向量库计费查看说明 doubao-embedding-vision 包括 250328 和 241215 两个版本，可通过 `model_version` 参数切换，241215版本只支持输出3072维稠密向量。
				bge-large-zh	输出稠密向量维度：1024 是否返回稀疏向量：否支持的模态：文本最长上下文长度：最多处理 512 个 token，数量超长时会截断，数量不足时会做 padding。模型的计费规则可以前往向量库计费查看
				bge-m3	输出稠密向量维度：1024 是否返回稀疏向量：是支持的模态：文本最长上下文长度：最多能处理 8192 个 token，数量超长时会截断，数量不足时会做 padding。模型的计费规则可以前往向量库计费查看
				bge-large-zh-and-m3	基于 bge v1.5 和m3 模型，使用混合检索模式。稠密向量由 bge v1.5 抽取，稀疏向量由 bge m3 抽取。输出稠密向量维度：1024 是否返回稀疏向量：是，输出稀疏向量为字典类型，k 为 Tokenizer 输出的token，v 为这个 token 的权重（类型是 float）支持的模态：文本最长上下文长度：最多能处理 512 个 token，数量超长时会截断，数量不足时会做 padding。模型的计费规则可以前往向量库计费查看
				bge-visualized-m3	基于Visualized-BGE和m3 模型，可对文本或图片进行单独编码，或者对文本图片对联合编码。输出稠密向量维度：1024 是否返回稀疏向量：否支持的模态：文本、图片最长上下文长度：文本token限制为8192，数量超长时会截断，数量不足时会做 padding。模型的计费规则可以前往向量库计费查看
	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-and-m3",
                "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,
        "data": {
                "sentence_dense_embedding": [[0.005996500349661112, 0.01326021542580391, -0.00757963274399552, -0.022116572232986055, ...], [0.013724524677071628, 0.013717792739791143, 0.005816815453880527, -0.014414478409530515, ...]],
                "sentence_sparse_embedding": [{
                        "ch": 0.13818359375,
                        "serve": 0.3193359375,
                        "tor": 0.1937255859375,
                        "使用": 0.1217041015625,
                        "如何": 0.1177978515625,
                        "模型": 0.258544921875,
                        "部署": 0.2318115234375
                },
                {
                        "使用": 0.168212890625,
                        "学习": 0.1473388671875,
                        "怎么": 0.1380615234375,
                        "机器": 0.1451416015625,
                        "模型": 0.2425537109375,
                        "训练": 0.275390625
                }],
                "token_usage": {
                        "prompt_tokens": 32,
                        "completion_tokens": 0,
                        "image_tokens": 0,
                        "total_tokens": 32
                }
        },
        "message": "success",
        "request_id": "02174159237407500000000000000000000ffff0a005875459994"
}

执行失败返回：

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