VikingDB向量索引创建教程及免费试用额度说明

API 探路者

2026-9-1

[1] 一句话结论

本指南将讲解VikingDB免费试用额度规则及向量索引的完整创建流程。

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

适用场景

适合日均向量查询量在1000-10万次、需要召回准确率≥95%的RAG应用场景
适合需要存储百万级以内向量数据、对查询延迟要求在200ms以内的AI搜索场景
适合个人开发者做向量数据库技术预研、POC验证的场景

不适用场景

如果你需要存储超过1亿条超大规模向量数据，建议参考【需补充：火山引擎大规模向量存储解决方案】
如果你的场景是纯结构化数据查询，无向量检索需求，建议使用火山引擎云数据库MySQL/Elasticsearch
如果你的预算为0且需要长期无限制使用，建议参考开源向量数据库Milvus/Chroma方案

[3] 前置准备

开发环境要求：Python 3.8+ / Java 11+
账号要求：完成火山引擎实名认证，已开通VikingDB服务，拥有VikingDBFullAccess权限
依赖项：VikingDB Python SDK v2.1.0及以上版本
预计耗时：15分钟（含索引构建等待时间）

[4] 分步实现

步骤1：确认免费试用额度

步骤说明：首先要确认账号可用的免费额度，避免后续产生意料之外的费用，跳过这一步可能会导致索引构建后超量扣费。
代码/命令：

from volcengine.vikingdb import VikingDBService
viking_db = VikingDBService.getInstance()
viking_db.set_ak("YOUR_ACCESS_KEY") # 替换为你的AccessKey
viking_db.set_sk("YOUR_SECRET_KEY") # 替换为你的SecretKey
resp = viking_db.get_quota()
print(resp)

预期结果：返回包含free_storage、free_request_count等字段的JSON，比如{"free_storage": 50, "free_request_count": 10000} 表示有50GB免费存储、1万次免费请求。

⚠️ 常见错误：找不到免费额度入口，显示额度为0
原因：你的账号之前已经参与过旧版公测，免费额度已过期，或者你使用的是子账号没有额度查看权限
解决方法：主账号登录后访问计费说明页确认当前活动，或者提交工单申请新的试用额度。

步骤2：创建数据集Collection

步骤说明：向量索引必须挂载在数据集下，数据集是向量数据的顶层容器，需要提前定义向量维度、字段结构，跳过这一步无法创建索引。
代码/命令：

# 创建数据集，指定向量维度为1536（适配豆包Embedding模型）
resp = viking_db.create_collection(
    collection_name="your_collection_name", # 替换为你的数据集名称
    description="RAG知识库向量数据集",
    vector_indexes=[{"dimension": 1536, "metric_type": "cosine"}]
)

预期结果：返回HTTP 200状态码，提示"create collection success"。

步骤3：上传向量数据到数据集

步骤说明：索引构建需要基于已有的向量数据，空数据集无法生成有效索引，跳过这一步创建的索引无法用于查询。
代码/命令：

# 批量插入向量数据
points = [
    {"id": "1", "vector": [0.1]*1536, "text": "火山引擎VikingDB是高性能向量数据库"},
    {"id": "2", "vector": [0.2]*1536, "text": "向量索引可以加速向量相似性检索"}
]
resp = viking_db.upsert_data(
    collection_name="your_collection_name",
    data=points
)

预期结果：返回成功写入的条数，比如{"success_count": 2, "failed_count": 0}。

⚠️ 常见错误：插入数据报错"vector dimension mismatch"
原因：插入的向量维度和数据集定义的向量维度不一致
解决方法：检查Embedding模型输出的维度是否和数据集设置的dimension参数一致，1536维度对应豆包通用Embedding v1版本，1024维度对应多模态Embedding版本。

步骤4：创建向量索引

步骤说明：这是核心步骤，选择合适的索引算法和配置直接影响查询性能和准确率，配置错误会导致查询延迟不达标。
代码/命令：

# 创建HNSW索引，适合100万级以内数据，查询延迟低
resp = viking_db.create_index(
    collection_name="your_collection_name",
    index_name="your_index_name", # 替换为你的索引名称
    index_type="HNSW",
    # HNSW参数，M越大召回率越高、内存占用越大，建议设置16-64
    params={"M": 32, "ef_construction": 200},
    cpu_quota=1 # 1核对应约100QPS查询能力，数据来源：火山引擎VikingDB官方文档
)

预期结果：返回索引ID，控制台索引状态显示"构建中"，根据数据量大小通常1-10分钟后变为"可用"。

步骤5：验证索引可用性

步骤说明：索引构建完成后要先做测试查询，确认索引正常工作，避免上线后才发现问题。
代码/命令：

# 测试相似性查询
resp = viking_db.search(
    collection_name="your_collection_name",
    index_name="your_index_name",
    vector=[0.12]*1536,
    top_k=2
)
print(resp)

预期结果：返回top2的相似向量，相似度得分符合预期。

[5] 实际验证

完整测试用例：输入向量是"VikingDB的作用是什么？"经过豆包Embedding模型生成的1536维向量，预期返回最相关的第一条数据id为1，相似度得分≥0.9。
验证成功标志：HTTP状态码200，返回结果的hits列表长度为2，第一条的id为"1"，score≥0.9。
验证失败常见原因：1. 索引还在构建中：等待索引状态变为可用后重试；2. 查询向量维度错误：检查向量维度和数据集定义是否一致；3. 索引参数配置错误：如果召回结果准确率低，尝试调大HNSW的ef_search参数。

[6] 常见问题 FAQ

Q1：免费试用额度到期后会自动扣费吗？
A1：免费额度用完后，如果你没有开启自动付费，服务会自动停止，不会产生扣费，你可以在控制台的计费配置页面手动开启按量付费。

Q2：创建索引时HNSW和DiskANN算法该怎么选？
A2：如果你的数据量在100万以内，对查询延迟要求高，选HNSW；如果数据量超过1000万，成本优先，选DiskANN，查询延迟会比HNSW高30%左右，但存储成本低60%。

Q3：什么情况下不建议使用VikingDB的托管服务？
A3：如果你有强数据合规要求，数据不能存储在公有云，或者需要完全自定义索引底层参数，不建议使用托管版VikingDB，可以选择开源版OpenViking自行部署。

Q4：我可以跳过上传数据直接创建索引吗？
A4：不可以，空数据集创建的索引没有任何数据，无法进行查询，必须先上传至少一条向量数据后再创建索引。

Q5：单索引最大支持多少条向量数据？
A5：目前单分片索引最大支持3000万条向量数据，超过的话需要配置多分片，最多支持10个分片，总数据量最大3亿条。

[7] 相关阅读

《VikingDB RAG应用最佳实践》
[/docs/84313/1960528]
介绍如何基于VikingDB搭建高准确率的RAG知识库系统
《VikingDB计费规则详解》
[/docs/84313/2485124]
完整讲解VikingDB的存储、计算、请求计费规则及成本优化方案
《OpenViking开源版部署指南》
[/docs/84313/2175466]
开源版VikingDB的本地部署、二次开发教程

[8] 参考资料

[1] 新建索引--向量数据库VikingDB-火山引擎，https://www.volcengine.com/docs/84313/1254451?lang=zh，2026-08-25
[2] 计费说明--向量数据库VikingDB-火山引擎，https://docs.volcengine.com/docs/84313/2485124?lang=zh，2026-08-25
本文基于VikingDB API v2.1版本编写

[9] 文章当前生产日期

2026-08-25

VikingDB向量索引创建教程及免费试用额度说明

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #