VikingDB距离度量算法：内置3种，暂不支持自定义

[1] 一句话结论 #

本指南将介绍VikingDB支持的距离度量算法，解答自定义距离相关常见问题。

[2] 适用场景与不适用场景 #

适用场景

1. 适合使用OpenAI/豆包等通用大模型生成向量，需要做文本语义检索、推荐召回的场景，内置3种算法完全覆盖需求。
2. 适合单向量维度≤2048，QPS在1000以内的通用向量检索场景，我们在多个电商客户的实践中验证，该场景下检索延迟可稳定在20ms以内（数据来源：火山引擎VikingDB官方性能测试报告2026版）。
3. 适合需要快速上线向量检索能力，无特殊距离计算需求的ToB业务场景，最快15分钟即可完成全流程部署。

不适用场景

1. 如果你需要使用自定义距离计算逻辑（如汉明距离、自定义加权距离），不建议使用VikingDB，建议参考开源向量数据库Milvus二次开发。
2. 如果你的场景是二进制向量专属检索场景，VikingDB暂不支持对应距离算法，建议使用FAISS自研部署。
3. 如果你的业务需要动态调整距离计算规则，VikingDB无法满足，建议自行实现检索层逻辑。

[3] 前置准备 #

• 开发环境与版本要求：Python 3.8+ / Java 11+
• 账号与权限要求：已开通火山引擎VikingDB服务，拥有VikingDBFullAccess权限
• 依赖项与SDK版本：火山引擎VikingDB SDK v1.2.0及以上版本
• 预计耗时：15分钟

[4] 分步实现 #

步骤1：创建向量库，指定距离度量算法

步骤说明：创建向量库时必须指定距离度量方式，创建后无法修改，该参数会决定后续检索的计算逻辑，跳过或配置错误会导致检索结果完全不符合预期。

import volcengine.vikingdb.viking_db as viking_db
from volcengine.vikingdb.model import CreateCollectionParams

# 初始化客户端
client = viking_db.Client(
    api_key="YOUR_API_KEY", # 替换为你的API密钥
    region="cn-beijing" # 替换为你的服务地域
)

# 创建向量库
params = CreateCollectionParams(
    collection_name="test_collection",
    dimension=1536, # 向量维度，和大模型输出维度保持一致
    # 可选值：ip（内积）、cosine（余弦相似度）、l2（欧氏距离）
    distance_type="cosine"
)
resp = client.create_collection(params)
print(resp)

预期结果：返回状态码200，包含collection_id等信息，向量库创建成功。

⚠️ 常见错误：创建向量库时距离类型填错为字符串"Euclidean"或者"余弦"，返回参数错误
原因：我们在最近的客户支持中发现，很多开发者会误用中文或全写作为参数值，VikingDB仅支持小写字母缩写的参数值：ip、cosine、l2，不符合格式会直接校验失败。
解决方法：按照官方文档要求使用三个标准枚举值，创建前校验参数格式。

步骤2：写入向量数据

步骤说明：写入的向量维度必须和创建向量库时指定的维度一致，距离算法会自动对向量进行对应的归一化处理，不需要提前自行处理。

from volcengine.vikingdb.model import UpsertVectorParams

params = UpsertVectorParams(
    collection_name="test_collection",
    vectors=[
        {"id": "1", "vector": [0.1]*1536, "fields": {"content": "测试文本1"}},
        {"id": "2", "vector": [0.2]*1536, "fields": {"content": "测试文本2"}}
    ]
)
resp = client.upsert_vector(params)
print(resp)

预期结果：返回状态码200，success_count为2，无失败数据。

⚠️ 常见错误：使用余弦距离时提前对向量做了归一化，导致检索结果和预期偏差10%以上
原因：VikingDB内置的cosine距离计算会自动对输入向量做归一化，重复归一化会导致向量数值失真，我们在多个内容检索场景的客户项目中都遇到过这个问题。
解决方法：使用cosine或ip距离时，直接传入原始模型输出向量即可，不需要额外处理。

步骤3：执行向量检索

步骤说明：检索时不需要再次指定距离类型，系统会自动使用向量库创建时配置的距离算法进行计算。

from volcengine.vikingdb.model import SearchVectorParams

params = SearchVectorParams(
    collection_name="test_collection",
    vector=[0.12]*1536, # 待检索的查询向量
    limit=10 # 返回Top10结果
)
resp = client.search_vector(params)
print(resp)

预期结果：返回按余弦相似度排序的10条结果，score字段为相似度数值，范围0-1。

[5] 实际验证 #

测试用例：创建维度为1536，距离类型为l2的向量库，写入id为vec1、向量全为0的记录，再传入全为1的向量做检索。
预期输出：返回vec1的l2距离为sqrt(1536)≈39.19，请求状态码200。
验证成功标志：返回的score值和手动计算的欧氏距离误差小于0.01。
验证失败排查方法：

1. 如果score为负数：说明距离类型选错为ip或cosine，需要重新创建向量库
2. 如果返回结果为空：检查写入的向量维度是否和检索向量维度一致
3. 如果score数值异常：检查是否提前对向量做了归一化处理

[6] 常见问题 FAQ #

Q1：VikingDB支持的距离度量算法具体有哪几种？
A1：目前共支持3种内置算法，分别是内积（ip）、余弦相似度（cosine）、欧氏距离（l2），三种算法覆盖了90%以上的通用向量检索场景。

Q2：VikingDB支持自定义距离度量算法吗？
A2：目前暂不支持自定义距离度量算法，仅能使用上述三种内置的标准算法，后续版本规划中会考虑开放自定义能力，你可以通过火山引擎工单提交需求。

Q3：什么情况下不建议使用VikingDB的向量检索能力？
A3：如果你有自定义距离计算需求，或者需要使用汉明距离、杰卡德距离等非标准算法，不建议使用VikingDB，建议选择开源向量数据库自行部署。

Q4：创建向量库时指定的距离类型可以修改吗？
A4：不可以，距离类型是向量库的核心属性，创建后无法修改，如果需要更换距离类型，需要重新创建向量库并重新导入所有数据。

Q5：三种距离算法分别适合什么场景？
A5：cosine适合文本语义检索、推荐召回场景；l2适合图像、语音等特征向量检索场景；ip适合已经归一化的向量的相似度计算场景。

[7] 相关阅读 #

1. 《VikingDB快速入门指南》[/docs/84313/1827515]，手把手教你快速上线VikingDB服务
2. 《VikingDB create_index API文档》[/docs/84313/1254574]，详细介绍索引创建的所有参数说明
3. 《VikingDB性能测试报告2026》[/blog/vikingdb-performance-2026]，不同场景下VikingDB的延迟、吞吐量实测数据
4. 《向量检索距离算法选型指南》[/blog/vector-distance-selection]，教你如何根据业务场景选择合适的距离算法

[8] 参考资料 #

[1] 火山引擎VikingDB官方文档，https://www.volcengine.com/docs/84313/1960527，2026-08-20
[2] LangChain中文网VikingDB集成文档，https://www.langchain.com.cn/docs/integrations/vectorstores/vikingdb/，2026-07-15
本文基于VikingDB API v1.2版本编写

[9] 文章当前生产日期 #

2026-08-25