OpenViking Vector Backend 性能 Benchmark

这个 benchmark 用来快速验收新的 VectorDB storage backend 在 OpenViking 场景下的表现。 它不直接调用 CollectionAdapter，而是走 VikingVectorIndexBackend：

• 建表使用 CollectionSchemas.context_collection
• 写入使用 VikingVectorIndexBackend.upsert_many(..., ctx=...)
• 查询使用 VikingVectorIndexBackend.search_in_tenant(...)
• 目录范围使用 target_directories，内部会编译成 PathScope("uri", ..., depth=-1)

它仍然不经过 OpenViking Server、AGFS、embedding 服务和 rerank；向量直接来自模拟数据或 dir-vector-dataset 的 .fvecs 文件。

先选模式

默认是 synthetic。

再选规模

--rows、--queries、--batch-size、--concurrency、--top-k 可以覆盖 profile 默认值。 --full 只对 dir-vector 生效；真实数据的向量维度从 .fvecs 读取，--dim 只影响 synthetic。

再选读写阶段

read-only 用于压测一个已经准备好的 collection。它必须和写入阶段使用相同的 --config、 配置里的 vectordb.name、--run-id、--workload、--dataset / --full / 抽样参数和 --distance，否则 runner 可能连到不同 collection，或用不同 query/ground truth 口径算报告。

read-only 不允许 --drop-at-end。如果想先准备数据再反复测读性能，先固定 --run-id 跑一次 write-only，后续用同一个 --run-id 跑 read-only。

快速开始

先准备一个 ov.conf，最小本地配置如下：

{
  "storage": {
    "workspace": "./benchmark/results/vectordb_perf/local_data",
    "vectordb": {
      "backend": "local",
      "name": "vectordb_perf",
      "project": "default",
      "index_name": "default",
      "distance_metric": "cosine"
    }
  }
}

模拟数据少量 smoke：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload synthetic \
  --profile smoke

模拟数据常规 benchmark：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload synthetic \
  --profile standard

真实数据必须先下载。--workload dir-vector 默认会跑 wiki 和 arxiv 两个真实数据集， runner 不会自动下载数据，也不会从 GitHub clone 后直接生成 .fvecs。先到 dir-vector-dataset 仓库 README 的 File Download 链接下载这两组数据文件：

https://github.com/KurtPatrickHere/dir-vector-dataset

下载后把文件解压或移动到同一个本地目录，例如：

mkdir -p benchmark/data/dir-vector-dataset-files
# 把下载得到的 corpus/query/vector/ground-truth 文件放进这个目录

--dataset-root 必须指向“直接包含数据文件”的目录，不是 GitHub repo 目录，也不是一个空目录。 runner 会先校验 wiki 和 arxiv 所需文件；缺文件时会直接列出 missing files 和下载地址。 调试时可以用 --dataset wiki 或 --dataset arxiv 只跑单个数据集。各 dataset 对应文件见下方“真实数据文件”。

真实数据少量抽样（Wiki 公开文件）：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload dir-vector \
  --dataset wiki \
  --dataset-root benchmark/data/dir-vector-dataset-files \
  --dir-vector-query-scope derived_gt_lca_v1 \
  --profile smoke

WIKI-Dir 的 corpus 目录来自单独发布的 dbpedia_dir_2m_corpus_paths.json，runner 会按 id 将它与 corpus metadata 和 fvecs 逐行对齐，并在错位或缺行时直接报错。这个文件约 600 MB，runner 使用流式解析，不会把全部 mapping 一次性加载到内存。

当前公开的 Wiki query metadata 没有包含目录 constraint，因此默认的 dataset 口径会拒绝 把所有 query 静默当成根目录查询。若要对公开文件做目录过滤的诊断性测试，可以显式使用 derived_gt_lca_v1：对每个 query 的最高 relevance ground-truth 文档取目录最长公共前缀， 并跳过只能得到根目录的 query。这个口径使用了 ground truth，不代表发布数据集的官方 query 分布，也不能用来声明官方 Directory recall。该选项只改变 Wiki；在 --dataset all 中， 其他 dataset 保持现有 loader 行为。

真实数据全量（公开 Wiki 文件的诊断性目录口径）：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload dir-vector \
  --dataset wiki \
  --dataset-root ./benchmark/data/dir-vector-dataset-files \
  --dir-vector-query-scope derived_gt_lca_v1 \
  --full

默认保留测试 collection，方便复查。需要运行后清理：

--drop-at-end

runner 会把配置里的 name 改成 <name>_bench_<run-id>，避免覆盖正式 collection。

分离写入和读取时要固定 --run-id。例如先写入：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload dir-vector \
  --dataset wiki \
  --dataset-root ./benchmark/data/dir-vector-dataset-files \
  --dir-vector-query-scope derived_gt_lca_v1 \
  --full \
  --run-id ovbench_full_001 \
  --mode write-only

再只跑读取和检索：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload dir-vector \
  --dataset wiki \
  --dataset-root ./benchmark/data/dir-vector-dataset-files \
  --dir-vector-query-scope derived_gt_lca_v1 \
  --full \
  --run-id ovbench_full_001 \
  --mode read-only \
  --output-dir benchmark/results/vectordb_perf/ovbench_full_001_read

写入数据结构

两种 workload 最终都会转换成 OV context row，写入字段如下：

所以这个 benchmark 不是“普通向量库 row + filter”，而是 OV 的 context collection row。

测试阶段

每次运行会创建一个带 run id 后缀的测试 collection，然后执行：

功能错误会导致非零退出码；性能慢只记录到报告里。

ingest 会把每个 --batch-size 分组通过一次 backend upsert_many 调用写入， 而不是逐行调用 upsert。对本地后端，这会把每批记录合并到一次 store 持久化操作； store 与 vector index 之间不提供跨组件事务。远端 adapter 还可根据请求上限进一步拆批， 因此一次 upsert_many 也不代表一个远端请求或跨子批事务。批量接口只提供完整记录 upsert；需要保留未提供字段的 partial update 仍使用单条 upsert。runner 会在整个多批 ingest 外层使用 bulk_ingest maintenance scope：native index 和数据持久化仍逐批更新， 但 Auto background cuVS rebuild 会延迟到最外层 scope 退出后再合并触发一次。这个 scope 不是事务或原子性边界，退出时只调度 rebuild，本身不等待 GPU ready。正式计时 search 前， runner 还会显式等待该最终 GPU snapshot ready； readiness wait 单独记录为 prepare/wait_for_auto_derived_index，失败时不会继续产出可能混合 CPU fallback 的 search QPS。当前 runner 是这些批量接口在仓库内的首个调用方；本改动不 自动改变现有 embedding、migration 或 ovpack 写入流程。

--mode write-only 只会出现 setup / ingest / 可选 cleanup 阶段。 --mode read-only 不执行 setup / ingest；Auto background 配置下会先出现 prepare， 随后执行 validate / vector_search / filtered_vector_search。 运行中会向 stderr 输出进度，包括当前 collection、写入条数、查询条数和速率。

进度输出示例：

[vectordb_perf] start run_id=ovbench_full_001 workload=dir-vector:wiki mode=write-only records=1941679 base_queries=456 directory_queries=217 dim=1024
[vectordb_perf] collection=vectordb_perf_bench_ovbench_full_001_wiki
[vectordb_perf] setup: create collection
[vectordb_perf] setup: collection ready
[vectordb_perf] ingest: start batch_size=1000
[vectordb_perf] ingest: 120000/1941679 (6.2%), 3950.4/s
[vectordb_perf] ingest: 240000/1941679 (12.4%), 4021.7/s

真实数据文件

--workload dir-vector 使用 KurtPatrickHere/dir-vector-dataset 发布的数据文件。需要先手动下载；下载入口在该仓库 README 的 File Download / Google Drive 链接里。

默认真实数据 benchmark 会跑 wiki 和 arxiv 两行。arxiv_category 不在默认两数据集里， 需要时显式传 --dataset arxiv_category。

默认两个真实数据集的全量规模如下，行数按 .fvecs 文件统计，也是 runner 的实际读取口径：

--dataset all --full 会依次跑这两组数据，合计 4,705,222 条 corpus 向量和 1,456 个 query。

把这些文件放到同一个目录，然后用 --dataset-root 指向该目录。

其他 ov.conf 示例

Volcengine VikingDB：

{
  "storage": {
    "vectordb": {
      "backend": "volcengine",
      "name": "vectordb_perf",
      "project": "default",
      "index_name": "default",
      "distance_metric": "cosine",
      "volcengine": {
        "region": "cn-beijing",
        "ak": "YOUR_AK",
        "sk": "YOUR_SK"
      }
    }
  }
}

自定义 adapter 类：

{
  "storage": {
    "vectordb": {
      "backend": "my_project.adapters.MyCollectionAdapter",
      "name": "vectordb_perf",
      "project": "default",
      "index_name": "default",
      "custom_params": {
        "endpoint": "http://127.0.0.1:9000",
        "token": "YOUR_TOKEN"
      }
    }
  }
}

常用参数

报告输出

主要输出文件：

summary_zh.md 里重点看两张表：

gt_recall@K 按 query 的 ground truth 命中率统计。全量 Wiki 的无过滤 vector_search 保留 official_full 标记；其 filtered_vector_search 在诊断模式下标为 derived_gt_lca_v1。 非 --full 会标成 sampled_subset。派生目录和抽样口径只用于诊断，不代表官方 Directory recall。

资源限制口径

runner 会记录本机 CPU、内存、平台、GPU 探测和 cgroup 信息，但不主动限制资源。 如果 backend 连接的是远端服务，远端实例规格需要人工记录或用部署系统控制。

本地要控制资源，建议在 Docker、cgroup 或 CI runner 层限制 CPU/内存，然后把报告里的 environment.json 和部署规格一起归档。