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

文档中心

立即注册

导航

embedding v2

最近更新时间：2025.07.01 18:13:23首次发布时间：2024.04.17 14:21:07

embedding v2接口

说明

embedding 接口升级为 v2 版本，新增视频、图片embedding模型，长文本窗口模型及稀疏向量产出，支持用量统计。建议迁移到 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张图，如果超出限制请及时联系客服扩大限流。
视频生成向量：
- 视频限制：单视频文件需在 50MB 以内（建议30M以内），支持MP4、AVI、MOV格式，暂不支持对视频文件中的音频信息进行理解。
- 视频支持指定FPS：支持控制从视频中抽取图像的帧率，支持配置0.2-5。

请求接口

说明

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

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

请求参数

参数	子参数	类型	是否必选	可选值	说明
				doubao-embedding-vision	字节自研的图文多模态向量化模型，主要面向图文多模向量检索的使用场景，支持视频、图片输入及中、英双语文本输入。当TPM超过5000时请前往火山方舟平台使用。输出稠密向量维度： 250615、250328版本：2048，支持1024 降维使用 241215版本：3072（待下线）是否返回稀疏向量：否支持的模态：文本、图片、视频（仅250615版本支持）最长上下文长度： 250328、241215版本：8K tokens 250615版本：128K tokens 模型的计费规则可以前往向量库计费查看说明 doubao-embedding-vision 包括 250615、250328 和 241215 三个版本，可通过 `model_version` 参数切换，241215版本只支持输出3072维稠密向量。
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 模型的计费规则可以前往向量库计费查看
				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"版本。doubao-embedding-vision支持"241215"（默认，支持的向量维度：3072）、"250328"（支持的向量维度：2048，1024）、"250615"（支持的向量维度：2048，1024）
data 说明 array[map], 最大 100 个.（若data为full_modal_seq类型，则最多1个）	data_type	string	是	text	文本
				image	图片
				text-image	文本-图片对联合编码
				full_modal_seq	存在video字段时，建议使用。文、图、视频的列表，（仅针对doubao-embedding-vision 250615适用）不能与text、image、text-image共同使用。
	text	string	否	data_type=text时，直接传入文本string	data_type 为 text 或 text-image时，必选。
	image	string	否	按下述的MediaData规范填写。	data_type 为 image 或 text-image时，必选。
	full_modal_seq	list<>	否	列表元素FullModalData的结构见下	data_type 为full_modal_seq时，必选。文、图、视频的列表。当前这种类型仅doubao-embedding-vision（250615）模型支持，最大输入token128k。

MediaData

例如image图片、video视频的字符串格式规范：

三选一

与VikingDB 向量数据库同region的tos资源地址

tos://{bucket}/{object_key}

可公开访问的http/https链接。http://或https://（仅doubao-embedding-vision支持）

base64字符串。base64://{Base64编码}。（占用您的请求带宽，且请求体总大小限制8M，不推荐）

FullModalData结构

字段名	类型	备注
text	string	纯文本
image	string	参考MediaData规范
video	string	参考MediaData规范
fps	float	表示抽帧的频率。对于video类型的数据才有效。不设置则默认为1，范围为0.2-5.0。服务端默认至少抽取16帧。越大，则抽帧更多，同时消耗的token也越多、时延越高。

响应消息

参数	参数说明
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	请求模型服务失败：模型名称不对。输入类型和模型对应不上。

完整示例

示例1-对文本生成稀疏稠密向量

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: token=********************' \
  http://***/api/data/embedding/version/2 \
  -d '{
        "model": {
                "model_name": "bge-large-zh-and-m3",
                "params": {
                    "return_token_usage": true,
                    "return_model_token_usage": true,
                    "return_dense": true,
                    "return_sparse": true,
                }
        },
        "data": [
                {
                        "data_type": "text",
                        "text": "如何使用torchserve部署模型"
                },
                {
                        "data_type": "text",
                        "text": "怎么使用训练机器学习模型"
                }
        ]
}'

执行成功返回：

{
        "message": "success",
        "code": 0,
        "request_id": "02171245661168200000000000000000000ffff0a0060a37b4c01",
        "data": {
                 "model_token_usage": {
                 "bge-large-zh": {
                        "prompt_tokens": 21,  // 请求文本的分词数
                        "completion_tokens": 0,  // 生成文本的分词数, 对话模型才有值, 其他模型都是0
                        "total_tokens": 21 // prompt_tokens + completion_tokens
                },
                 "bge-m3": {
                        "prompt_tokens": 21,  // 请求文本的分词数
                        "completion_tokens": 0,  // 生成文本的分词数, 对话模型才有值, 其他模型都是0
                        "total_tokens": 21 // prompt_tokens + completion_tokens
                },
                }
                "token_usage": {
                        "prompt_tokens": 21,  // 请求文本的分词数
                        "completion_tokens": 0,  // 生成文本的分词数, 对话模型才有值, 其他模型都是0
                        "total_tokens": 21 // prompt_tokens + completion_tokens
                },
                "sentence_sparse_embedding": [ // 稀疏向量, 输出是一个词典<token_id, token_weight>
                    {
                        "71277": 0.258544921875,
                        "6": 0.010589599609375,
                        ...
                    },
                    ...
                ],
                "sentence_dense_embedding": [ // 稠密向量, 输出是个二维数组, [batch_size, model_output_dimension]
                        [0.02059086412191391, -0.014762681908905506, ...],
                        ...
                ]
        }
}

执行失败返回：

{"message":"failed to calcTextEmbedding, ModelNotFoundException: Model not found: bge-large-zh","code":1000025}

示例2-对文和视频生成向量

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: token=********************' \
  http://***/api/data/embedding/version/2 \
  -d '{
        "model": {
            "model_name": "doubao-embedding-vision",
            "params": {
                "embedding_dimension": 2048,
                "model_version": "250615",
                "return_token_usage": true,
            }
        },
        "data": [
            {
                "data_type": "full_modal_seq",
                "full_modal_seq": [
                    {"text": "这是文章的标题"},
                    {"text": "正文内容....."},
                    {"video": "tos://mybucket/movie_1.mp4", "fps": 0.5},
                    {"text": "文章结尾内容....."},
                ]
            }
        ]
}'

响应结果：

{
    "message": "success",
    "code": 0,
    "request_id": "02171245661168200000000000000000000ffff0a0060a37b4c01",
    "data": {
        "token_usage": {
                "prompt_tokens": 21,  // 请求文本的token数
                "image_tokens": 21,  // 请求图片的token数（包括了视频的抽帧结果）
                "completion_tokens": 0,
                "total_tokens": 21
        },
        "sentence_dense_embedding": [ 
                [0.02059086412191391, -0.014762681908905506, ......],
        ]
    }
}