OpenViking Vector Backend 性能 Benchmark

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

• 建表使用 CollectionSchemas.context_collection
• 写入使用 VikingVectorIndexBackend.upsert(..., 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 对应文件见下方“真实数据文件”。

真实数据少量抽样：

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

真实数据全量：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload dir-vector \
  --dataset-root ./benchmark/data/dir-vector-dataset-files \
  --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-root ./benchmark/data/dir-vector-dataset-files \
  --full \
  --run-id ovbench_full_001 \
  --mode write-only

再只跑读取和检索：

.venv/bin/python -m benchmark.vectordb_perf.run \
  --config ./ov.conf \
  --workload dir-vector \
  --dataset-root ./benchmark/data/dir-vector-dataset-files \
  --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，然后执行：

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

--mode write-only 只会出现 setup / ingest / 可选 cleanup 阶段。 --mode read-only 只会出现 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 queries=456 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 命中率统计。--full 才是官方全量 recall； 非 --full 的真实数据报告会标成 sampled_subset，只用于 smoke sanity，不代表官方全量 recall。

资源限制口径

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

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