Doubao-embedding-vision 是一款由字节跳动研发的图像向量化模型，支持文本、图片及视频混合输入的向量化技术。该模型能够将不同类型的数据（文本、图片、视频）转换成向量表示，适用于文搜图、图搜图、图文混合搜索等场景。
通过 Doubao-embedding-vision 模型，用户可以实现多模态数据的统一向量化，便于处理和分析跨模态数据，以实现更高效的信息检索和数据分析。

您可以在以下场景中使用模型的图文向量化能力。

当前支持图像向量化的模型请参见图像向量化能力。

• 获取 API Key 。
  • 使用 Access Key 鉴权请参考Access Key 签名鉴权。
• 开通模型服务。
• 在模型列表获取所需 Model ID 。
  • 通过 Endpoint ID 调用模型服务请参考获取 Endpoint ID（创建自定义推理接入点）。

图像向量模型支持接受和处理图像输入并转换为向量，这些图像可以通过可访问 URL 或转为 Base64 编码后输入，下面是简单的调用示例代码。
视频、图、文混合输入

仅 doubao-embedding-vision-250615及后续版本支持视频输入。

curl https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ea764f0f-3b60-45b3-****-************" \
  -d '{
    "model": "doubao-embedding-vision-250615",
    "encoding_format": "float",
    "input": [
        {
            "type": "video_url",
            "video_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input.mp4"
            }
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/tower.png"
            }
        },
        {
            "type": "text",
            "text": "视频和图片里有什么"
        }
    ]
}'

图文输入

curl https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal  \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ea764f0f-3b60-45b3-****-************" \
  -d '{
    "model": "doubao-embedding-vision-250328",
    "input": [
        {
            "type":"text",
            "text":"天很蓝，海很深"
        },
        {    
            "type":"image_url",
            "image_url":{
                "url":"https://ark-project.tos-cn-beijing.volces.com/images/view.jpeg"
            }
        }
      ]
}'

模型回复预览：

{
    "id": "021718067849899d92fcbe0865fdffdde********************",
    "created": 171806****,
    "object": "list",
    "model": "doubao-embedding-***-******",
    "data": [
        {
            "object": "embedding",
            "embedding": [[0.62109375,-0.69140625,...,0.38671875]
        }
    ],
    "usage": {
        "prompt_tokens": 1340,
        "total_tokens": 1340,
        "prompt_tokens_details": {
            "text_tokens": 1312,
            "image_tokens": 28
        }
    }
}

图片输入

图片传入方式

图片 URL 或图片 Base64 编码。用图片 URL 方式时，需确保图片 URL 可被访问。

图片像素说明

模型能够支持尺寸更加灵活的图片，传入图片满足下面条件：

• 图片宽高长度（单位 px）：大于 14。

图片像素（宽＊高，单位 px）：小于 3600w。

图片数量说明

单次请求最多传入图片数量为1张。

token 用量说明

模型理解图片，会将图片转化为 token ，再进行推理计算。token 用量，根据图片宽高像素计算可得。图片转化 token 的公式为：

min(图片宽 * 图片高/784, 单图 token 限制)

图片尺寸为 1280 px ＊ 720 px，即宽为 1280 px，高为 720 px，传入模型图片 token 限制为 1312，则理解这张图消耗的 token 为1280＊720/784=1176，因为小于 1312，消耗 token 数为 1176 。
图片尺寸为 1920 px ＊ 1080 px，即宽为 1920 px，高为 1080 px，传入模型图片 token 限制为 1312，则理解这张图消耗的 token 为1920＊1080/784=2645，因为大于 1312，消耗 token 数为 1312 。这时会压缩 token，即图片的细节会丢失部分，譬如字体很小的图片，模型可能就无法准确识别文字内容。

图片格式说明

支持的图片格式如下表，需注意文件后缀和图片格式需要匹配，即图片文件扩展名（URL 传入）、编码中图片格式声明（Base64 编码传入）需要与图片实际信息一致。

视频输入

对视频按固定间隔抽取画面后，交由模型进行理解。

视频格式说明

视频文件容量

单视频文件需在 50MB 以内。

不支持音频理解

暂不支持对视频文件中的音频信息进行理解。

用量说明

单视频 token 用量范围在[10k, 80k] ，单次请求视频最大 token 量还受模型的最大上下文窗口以及最大输入长度（当启用深度推理模式）限制，超出则请调整传入视频数量或视频长度。
方舟根据帧图像（某个时刻的视频画面，此处特指输入给模型的帧图像）张数（视频时长 * fps ），对帧图像进行压缩，以平衡对于视频的理解精度和 token 用量。帧图像会被等比例压缩至 [128 token, 640 token] ，对应像素范围在 [10万 像素, 50万像素]。
如fps过高或视频长度过长，需要处理的帧图像数量超出 640 帧（80×1024 token ÷ 128 token / 帧 = 640 帧），则按帧图像 128 token 视频时长/640 时间间隔均匀抽取 640帧。此时与请求中的配置不符，建议评估输出效果，按需调整视频时长或 fps 字段配置。
如fps过小或视频长度过短，需要处理的帧图像数量不足16帧（10×1024 token ÷ 640 token / 帧 = 16 帧），则按帧图像 640 token 视频时长/16 时间间隔均匀抽取 16帧。

相似度计算

• Doubao-embedding向量间相似度得分可以使用余弦相似度作为计算方式，余弦相似度计算拆分为下面两步：
  • 第一步: 请求doubao-embedding接口得到embedding，将embedding向量L2_norm处理;
  • 第二步: 对norm处理后的向量进行点积计算得到余弦相似度;

向量降维

向量化是通过向量来表征文本、图像等非结构化数据的过程，让计算机能理解语言、图像等的含义。其中，向量维度是描述向量化后向量中元素的个数（标注词义/图像特征的维度）。在图文向量化场景，每个维度对应文本的一个特征或者是对应图像的像素、色彩等视觉特征。

• 维度更多：以更多独立特征标注内容（文本的语义细节、图像的纹理特征），提升表征精度。但会导致数据量膨胀，带来更高的存储成本（内存/磁盘占用）和计算开销（相似度计算、模型推理耗时）。
• 维度更低：以更少特征标注内容，可能损失部分细节（文本的细微语义差异、图像的边缘像素信息）。但数据量缩减，存储效率与计算速度会提升，资源消耗及成本更低。

向量降维功能的核心目标是减轻用户存储向量和检索向量的压力，通过压缩向量维度降低存储成本与计算开销。您可通过向量降维，选择合适的维度来向量化文本/图像，平衡“语义/视觉精度”“计算速度”与“资源成本”三者关系。

示例代码

• doubao-embedding-vision-241215向量维度3072维，不支持降维使用
• doubao-embedding-vision-250328模型支持最高维度2048可以压缩到1024维度存储检索，维度越高越接近最高维度效果。
  • 如何降维度&计算相似度？
    1. 降维度: 将embedding接口获取的向量直接截取前dim维度;
    2. 计算相似度: 对截取后的embedding做余弦相似度计算;

# 降维+ L2_norm
def sliced_norm_l2(vec: List[float], dim=2048) -> List[float]:
    # dim 为1024
    norm = float(np.linalg.norm(vec[ :dim]))
    return [v / norm for v in vec[ :dim]]
    
# 余弦相似度计算
query_doc_relevance_score_2048d = np.matmul(
    sliced_norm_l2(embeddings[0], 2048), #查询向量
    sliced_norm_l2(embeddings[1], 2048)  #文档向量
)

Base64 编码输入

如果你要传入的视频/图片在本地，你可以将这个视频/图片转化为 Base64 编码，然后提交给大模型。下面是一个简单的转换示例代码。

# 定义方法将指定路径图片转为Base64编码
def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode('utf-8')

# 需要传给大模型的图片
image_path = "path_to_your_image.jpg"
# 将图片转为Base64编码
base64_image = encode_image(image_path)

转换后，图片的url格式参考如下：

{
        "type": "image_url",
        "image_url": {
            "url":  f"data:image/<IMAGE_FORMAT>;base64,{base64_image}"
        }
    },

场景概述

下述程序展示如何通过文本描述检索图片库中的相关素材。
程序读取包含 5 张水果图片 URL 的列表，调用 Doubao-embedding-vision 模型为每张图片生成向量表示。当用户输入查询文本 "香蕉" 时，程序将其转换为向量，并通过余弦相似度与图片向量库匹配，并输出最相似图片和相似度分数。该流程实现了基于语义的 "以文搜图" 功能，辅助用户从图片库中快速定位目标内容，适用于电商商品检索、媒体素材管理等场景。

第一步：导入库包

导入所需的库包，并设置 API Key，为后续的数据处理和分析做准备。

import os
import numpy as np
from volcenginesdkarkruntime import Ark
from sklearn.metrics.pairwise import cosine_similarity

第二步：获取向量

定义一个函数将单个文本或图片转换为向量表示。支持两种输入类型：文本和图片 URL。调用doubao-embedding-vision-241215模型获取float格式向量，再转换为numpy数组并展平为一维向量。

def get_embedding(input_data, input_type="text"):
    """调用火山引擎API获取单个文本或图片的向量表示"""
    client = Ark(api_key=os.environ.get("ARK_API_KEY"))
    if input_type == "text":
        input_item = {"type": "text", "text": input_data}
    elif input_type == "image_url":
        input_item = {"type": "image_url", "image_url": {"url": input_data}}
    else:
        raise ValueError("输入类型仅支持'text'或'image_url'")
    
    try:
        resp = client.multimodal_embeddings.create(
            model="doubao-embedding-vision-241215",
            encoding_format="float",
            input=[input_item]
        )
        if hasattr(resp, 'data') and isinstance(resp.data, dict) and 'embedding' in resp.data:
            embedding = resp.data['embedding']
            # 确保向量是numpy数组并展平为一维
            embedding = np.array(embedding).flatten()
            return embedding
        else:
            raise ValueError("API响应格式不符合预期，无法获取嵌入向量")
    except Exception as e:
        print(f" 获取向量失败，输入类型: {input_type}, 错误: {str(e)}")
        raise

第三步：生成向量库

批量处理图片 URL 列表，生成对应的向量表示，并构建向量库。

def generate_image_embeddings(image_urls):
    """批量生成图片向量并构建向量库"""
    print(f"[1/3] 开始生成 {len(image_urls)} 张图片的向量...")
    embeddings = []
    for i, url in enumerate(image_urls):
        try:
            embedding = get_embedding(url, "image_url")
            embeddings.append({
                "image_url": url,
                "embedding": embedding
            })
            print(f" [{i+1}/{len(image_urls)}] 成功: {url}")
        except Exception as e:
            print(f" [{i+1}/{len(image_urls)}] 失败: {url} - {str(e)}")
            continue
    if not embeddings:
        raise ValueError("所有图片向量生成失败")    
    print(f"[2/3] 完成: {len(embeddings)} 个有效向量")
    return embeddings

第四步：图片相似度计算

利用余弦相似度来度量文本与图片之间的相似性，实现了一个基于内容的图片搜索功能。用户可以通过输入文本描述，检索与该描述最相关的图片。

def search_similar_images(query_embedding, embeddings, top_n=1, query_type="文本"):
    """搜索与查询向量最相似的图片"""
    print(f"\n[3/3] 开始搜索与{query_type}最相似的图片...")
    results = []
    # 确保查询向量是numpy数组且维度正确
    query_vec = np.array(query_embedding).reshape(1, -1)
    for item in embeddings:
        # 确保向量是numpy数组并调整为二维数组用于相似度计算
        item_vec = np.array(item["embedding"]).reshape(1, -1)
        
        similarity = cosine_similarity(query_vec, item_vec)[0][0]
        results.append({
            "image_url": item["image_url"],
            "similarity": similarity
        })
    
    results.sort(key=lambda x: x["similarity"], reverse=True)
    print(f" - 相似度计算完成，共 {len(results)} 个结果")
    return results[:top_n]

第五步：示例用法

测试搜索功能，调用generate_image_embeddings函数生成图片向量库，使用文本查询搜索相似图片，并返回最相似的结果。示例代码如下：

if __name__ == "__main__":
    image_urls = [
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit1.jpg",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit2.jpg",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit3.jpg",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit4.jpg",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit5.jpg"
    ]
    query_text = "香蕉"
  
    try:
        # 生成图片向量
        image_embs = generate_image_embeddings(image_urls)        
        # 生成文本向量
        text_emb = get_embedding(query_text, "text")
        print(f"文本向量维度: {len(text_emb)}")        
        # 搜索相似图片
        similar_images = search_similar_images(text_emb, image_embs)
        print(f"最相似图片: {similar_images[0]['image_url']}")
        print(f"相似度分数: {similar_images[0]['similarity']:.4f}")
        
    except Exception as e:
        print(f"程序失败: {e}")

运行结果示例

• 开始生成 5 张图片的向量，依次对 5 个图片 URL发起请求，均返回 “成功”，表明 API 调用正常且图片链接可访问、格式合规。
• 完成处理，生成 5 个有效向量，文本向量维度为 3072，与模型输出维度一致，向量数量与输入图片数量匹配，无数据丢失。
• 开始相似度匹配，对文本向量与 5 个图片向量进行相似度计算，最终返回最相似图片为 Fruit2.jpg，表明两者在特征空间中具有较强相关性。

[1/3] 开始生成 5 张图片的向量...
 (1/5)成功: https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit1.jpg
 (2/5)成功: https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit2.jpg
 (3/5)成功: https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit3.jpg
 (4/5)成功: https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit4.jpg
 (5/5)成功: https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit5.jpg
[2/3] 完成: 5 个有效向量
文本向量维度: 3072

[3/3] 开始搜索与文本最相似的图片...
 - 相似度计算完成，共 5 个结果
最相似图片: https://ark-project.tos-cn-beijing.volces.com/doc_image/Fruit2.jpg
相似度分数: 0.6462

以下代码针对API仅支持单次传入一张图片的限制，通过异步并发与批量分组策略实现图片向量化的高效批量处理：利用asyncio创建异步任务，将图片按指定批次分组后并发调用API，采用“全组失败回滚”模式确保每组任务一致性，支持失败重试并隔离保存成功与失败结果（含向量详情、错误信息及输入URL）。

import asyncio
from volcenginesdkarkruntime import AsyncArk
from pathlib import Path
import os

class MultimodalEmbedder:
    """多模态向量化批量处理工具（全组失败模式）"""
    def __init__(self, api_key: str, model: str = "doubao-embedding-vision-241215", 
                 batch_size: int = 10, retries: int = 2):
        self.api_key = api_key
        self.model = model
        self.batch_size = batch_size
        self.retries = retries
        
    async def process(self, items_list):
        """异步处理图文数据列表"""
        async with AsyncArk(max_retries=self.retries) as client:
            # 创建并启动所有任务
            tasks = [
                asyncio.create_task(client.multimodal_embeddings.create(model=self.model, input=items))
                for items in items_list
            ]         
            try:
                # 等待所有任务完成，任一失败则立即抛出异常
                return await asyncio.gather(*tasks)
            except Exception:
                # 取消所有未完成的任务
                for task in tasks:
                    if not task.done():
                        task.cancel()
                # 重新抛出原始异常
                raise
    
    def save_results(self, results, output_dir: str = "embedding_results"):
        """保存向量化结果到文本文件"""
        Path(output_dir).mkdir(exist_ok=True)
        
        with open(f"{output_dir}/success.txt", "w", encoding="utf-8") as f:
            f.write("===== 向量化结果 =====\n")
            for idx, result in enumerate(results, 1):
                f.write(f"结果 #{idx}\nID: {result.id}\n")
                f.write(f"创建时间: {result.created}\n")
                f.write(f"模型: {self.model}\n")
                embedding = result.data.get("embedding", [])
                f.write(f"向量长度: {len(embedding)}\n")
                f.write(f"部分向量值: {embedding[:20]}...\n\n")
                
        print(f"结果已保存到 {output_dir}/success.txt")

if __name__ == "__main__":
    ARK_API_KEY = os.environ.get("ARK_API_KEY")
    if not ARK_API_KEY:
        print("未找到环境变量 ARK_API_KEY，请手动输入")
        ARK_API_KEY = input("API密钥: ").strip()
        if not ARK_API_KEY:
            raise ValueError("API密钥不能为空")
    
    embedder = MultimodalEmbedder(
        api_key=ARK_API_KEY,
        batch_size=10,
        retries=2
    )
    
    sample_data = [
        [
            {"type": "text", "text": "天很蓝，海很深"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}}
        ],
        [
            {"type": "text", "text": "阳光明媚的沙滩"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}}
        ]
    ]
    
    try:
        # 执行向量化处理
        results = asyncio.run(embedder.process(sample_data))
        # 保存结果（仅在全部成功时）
        embedder.save_results(results)
        print(f"全部成功: {len(results)}")
    except Exception as e:
        print(f"处理失败: {str(e)}")