• 对应的旧接口为：https://www.volcengine.com/docs/84313/1254554
• 使用区别：

• 注：限流是以token用量计算，V1与V2接口的限流行为完全相同。

其中，Data结构：

• MediaData（例如image图片、video视频可以为字符串）的格式规范：

• FullModalData结构：

模型列表

公共响应体参数部分见
数据面API调用流程

其中，EmbeddingResult结构：

1.文本稠密+稀疏

• 请求参数

req_path = "/api/vikingdb/embedding"
req_body = {
    "dense_model": {
        "name": "doubao-embedding-large",
        "version": "240915",
        "dim": 1024,
    },
    "sparse_model": {
        "name": "bge-m3",
        "version": "default",
    },
    "data": [
        {
            "text": "天很蓝。"
        },
        {
            "text": "海很深。"
        }
    ]
}

• 响应参数

{
    "code": "Success",
    "message": "The API call was executed successfully.",
    "request_id": "02175438839168500000000000000000000ffff0a003ee4fc3499",
    "result": {
        "data": [
            {
                "dense": [0.05149054509186956,0.034275332726816786, ......],
                "sparse": {
                    "天": 0.263671875,
                    "很": 0.18603515625,
                    "蓝": 0.3046875
                }
            },
            {
                "dense": [0.0076801463728645375,0.034275332726816786, ......],
                "sparse": {
                    "很": 0.2010498046875,
                    "海": 0.32958984375,
                    "深": 0.32373046875
                }
            }
        ],
        "token_usage": {
            "bge-m3__default": {
                "prompt_tokens": 14,
                "completion_tokens": 0,
                "image_tokens": 0,
                "total_tokens": 14
            },
            "doubao-embedding-large__240915": {
                "prompt_tokens": 9,
                "completion_tokens": 0,
                "image_tokens": 0,
                "total_tokens": 9
            }
        }
    }
}

2.文+图多模态

• 请求参数

req_path = "/api/vikingdb/embedding"
req_body = {
    "dense_model": {
        "name": "bge-visualized-m3",
        "version": "default",
        "dim": 1024
    },
    "data": [
        {"text": "天很蓝"},
        {"text": "tos://my_bucket/sky_1.jpeg"}
    ]
}

• 响应参数

{
    "code": "Success",
    "message": "The API call was executed successfully.",
    "request_id": "02175438839168500000000000000000000ffff0a003ee4fc3499",
    "result": {
        "data": [
            {
                "dense": [0.013657506555318832,0.034275332726816786, ......]
            }
        ],
        "token_usage": {
            "bge-visualized-m3__default": {
                "prompt_tokens": 926,
                "completion_tokens": 0,
                "image_tokens": 926,
                "total_tokens": 926
            }
        }
    }
}

3.文+图+视频多模态

• 请求参数

req_path = "/api/vikingdb/embedding"
req_body = {
    "dense_model": {
        "name": "doubao-embedding-vision",
        "version": "250615",
        "dim": 1024,
    },
    "data": [
        {
            "full_modal_seq":[
                {
                    "text": "haha haha"
                },
                {
                    "image": "tos://my_bucket/images/dogs/5.jpeg"
                },
                {
                    "video": "tos://my_bucket/videos/1.mp4"
                },
                {
                    "video":
                    //如果需要对视频有自定义处理，可将video值定义为json，以设置高级参数：
                    //value表示视频内容；
                    //fps表示抽帧的频率。不设置则默认为1，范围为0.2-5.0。不过，服务端默认至少抽取16帧。越大，则抽帧更多，同时消耗的token也越多、时延越高。
                        {
                            "value": "tos://my_bucket/videos/2.mp4",
                            "fps": 0.4, 
                        }
                }
            ]
        }
    ]
}

• 响应参数

{
    "code": "Success",
    "message": "The API call was executed successfully.",
    "request_id": "02175438839168500000000000000000000ffff0a003ee4fc3499",
    "result": {
        "data": [
            {
                "dense": [0.05149054509186956,0.034275332726816786, ......]
            }
        ],
        "token_usage": {
            "doubao-embedding-vision__250615": {
                "prompt_tokens": 1325,
                "completion_tokens": 0,
                "image_tokens": 1312,
                "total_tokens": 1325
            }
        }
    }
}

4.传入待tos处理参数的图像

• 请求参数

req_path = "/api/vikingdb/embedding"
req_body = {
    "dense_model": {
        "name": "doubao-embedding-vision",
        "version": "250615",
        "dim": 2048,
     },
    "data": [
        {
            "image": {"value":"tos://yuan-tos/cat.jpeg","x-tos-process": "image/resize,l_600|image/indexcrop,x_600,i_0"},
        } 
    ]
}

• 响应参数

{
    "code":"Success",
    "message":"The API call was executed successfully.",
    "request_id":"xxx",
    "result":
        {
            "data":[
                {
                    "dense":[...],
                }
            ],
            "token_usage":{"doubao-embedding-vision__250615":{"prompt_tokens":472,"completion_tokens":0,"image_tokens":459,"total_tokens":472}}
        }
}   

5.doubao-embedding-vision 0615支持稀疏向量编码

doubao-embedding-vision 0615模型稀疏向量输出结构为多个{index:value}
index：类型为string，代表token对应的行号
value：token对应的embedding值

• 请求参数

req_path = "/api/vikingdb/embedding"
req_body = {
    "dense_model": {
        "name": "doubao-embedding-vision",
        "version": "250615",
        "dim": 2048,
     },
    "sparse_model": {
        "name": "doubao-embedding-vision",
        "version": "250615",
     },
    "data": [
        {
            "text": "从前有座山,山里有座庙", 
        } 
    ]
}

• 响应参数

{
    "code":"Success",
    "message":"The API call was executed successfully.",
    "request_id":"02175739508084500000000000000000000ffff0a005a4847c517",
    "result":
        {
            "data":[
                {
                    "dense":[...],
                    "sparse"::{"139":0.2431640625,"14310":0.375,"1590":0.35546875,"3129":0.47265625,"37460":0.44140625,"514":0.294921875,"95188":0.408203125}
                }
            ],
            "token_usage":{"doubao-embedding-vision__250615":{"prompt_tokens":23,"completion_tokens":0,"image_tokens":0,"total_tokens":23}}
        }
}   

"""
pip3 install volcengine
"""
import os

from volcengine.auth.SignerV4 import SignerV4
from volcengine.Credentials import Credentials
from volcengine.base.Request import Request
import requests, json

class ClientForDataApi:
    def __init__(self, ak, sk, host):
        self.ak = ak
        self.sk = sk
        self.host = host

    def prepare_request(self, method, path, params=None, data=None):
        r = Request()
        r.set_shema("https")
        r.set_method(method)
        r.set_connection_timeout(10)
        r.set_socket_timeout(10)
        mheaders = {
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'Host': self.host,
        }
        r.set_headers(mheaders)
        if params:
            r.set_query(params)
        r.set_host(self.host)
        r.set_path(path)
        if data is not None:
            r.set_body(json.dumps(data))
        credentials = Credentials(self.ak, self.sk, 'vikingdb', 'cn-beijing')
        SignerV4.sign(r, credentials)
        return r
        
    def do_req(self, req_method, req_path, req_params, req_body):
        req = self.prepare_request(method=req_method, path=req_path, params=req_params, data=req_body)
        return requests.request(method=req.method, url="http://{}{}".format(self.host, req.path),
                                  headers=req.headers, data=req.body, timeout=10000)

if __name__ == '__main__':
    client = ClientForDataApi(
        ak = "*",#替换为您的ak
        sk = "*",#替换为您的sk
        host = "api-vikingdb.vikingdb.cn-beijing.volces.com",#替换为您所在的域名
    )
    req_method = "POST"
    req_params = None
    req_path = "/api/vikingdb/embedding"
    req_body = {
        "dense_model": {
            "name": "doubao-embedding-vision",
            "version": "250615",
            "dim": 2048,
         },
        "sparse_model": {
            "name": "doubao-embedding-vision",
            "version": "250615",
         },
        "data": [
            {
                "text": "从前有座山,山里有座庙", 
            } 
        ]
    }
    result = client.do_req(req_method=req_method, req_path=req_path, req_params=req_params, req_body=req_body)
    print("req http status code: ", result.status_code)
    print("req result: \n", result.text)