OpenViking/benchmark/custom/README.md

OpenViking Server 压测脚本使用指南

本目录包含面向 OpenViking 本地 Server 的自定义压测脚本。当前主要脚本是：

• session_contention_benchmark.py：通用 Server 压测框架，覆盖 SDK、CLI HTTP 封装和真实 ov 子进程三种调用路径。

压测目标

session_contention_benchmark.py 用来请求已经启动的 OpenViking Server，验证多类接口在并发和混合负载下的吞吐、延迟、失败率和后台任务积压情况。

脚本不会启动或停止 Server，只负责：

1. 生成本地 Markdown 测试文档。
2. 每次运行前默认清空上一次压测写入的数据目录。
3. 并发请求资源添加、检索、session 写入、session commit、任务轮询和观测接口。
4. 输出中文压测报告和机器可读明细文件。

前置条件

先在另一个终端启动 OpenViking Server：

openviking-server

如果 Server 启用了 API Key 或多租户，请准备好以下信息：

• Server 地址，例如 http://127.0.0.1:1935
• API Key，默认参数会使用 test-root-api-key
• Account，默认 default
• User，默认 default

真实 CLI 子进程模式还要求当前环境能执行 ov：

ov health

快速开始

在仓库根目录运行 smoke 压测：

.venv/bin/python benchmark/custom/session_contention_benchmark.py \
  --server-url http://127.0.0.1:1935 \
  --profile smoke

只测试 Python SDK 路径：

.venv/bin/python benchmark/custom/session_contention_benchmark.py \
  --server-url http://127.0.0.1:1935 \
  --profile smoke \
  --adapters sdk

同时测试 SDK、CLI HTTP 封装和真实 ov 子进程：

.venv/bin/python benchmark/custom/session_contention_benchmark.py \
  --server-url http://127.0.0.1:1935 \
  --profile standard \
  --adapters sdk,cli-http,cli-subprocess

调用路径说明

脚本支持三种 adapter：

Adapter	含义	适用场景
sdk	通过 openviking.AsyncHTTPClient 请求 Server	评估 Python SDK 的 HTTP 调用表现
cli-http	直接使用 openviking_cli.client.http.AsyncHTTPClient	评估 CLI 共用 HTTP client 层表现
cli-subprocess	每次请求真实执行一次 ov ... --output json	评估真实 CLI 进程启动、配置读取、上传和输出解析成本

默认会同时运行三种路径：

--adapters sdk,cli-http,cli-subprocess

如果只关心 Server 吞吐，建议先跑 sdk 或 cli-http。如果关心用户实际执行 CLI 命令的端到端成本，再加入 cli-subprocess。

压测场景

每个 adapter 会依次执行以下阶段：

阶段	内容
warmup	健康检查预热
add_resources	并发添加多个生成的 Markdown 文档
session_messages	并发向不同 session 写入多轮 user / assistant 消息
retrieval	并发执行 find、search、grep、glob
session_commit	并发 commit 不同 session，并轮询后台任务
mixed	混合资源添加、检索、session 写入、commit、观测接口和任务轮询

这些阶段不是只压单个接口，目的是观察 OpenViking 在真实组合负载下的退化情况。

数据清理策略

默认每次运行前会清理：

• Server 侧资源目录：viking://resources/bench/load_test
• 旧 session：所有 bench-load- 前缀的 session
• 本地生成数据目录：benchmark/results/openviking_server_load/data

默认运行结束后保留本次写入的数据，方便人工复查。下一次运行前会再次清空。

如果不想在运行前清理：

--no-clear-before-run

如果希望运行结束后也清理：

--cleanup-at-end

常用参数

参数	默认值	说明
--server-url	http://127.0.0.1:1935	OpenViking Server 地址
--api-key	test-root-api-key	请求使用的 API Key
--account	default	请求使用的 account
--user	default	请求使用的 user
--adapters	sdk,cli-http,cli-subprocess	要测试的调用路径
--profile	standard	压测规模：smoke、standard、stress
--resource-count	跟随 profile	每个 adapter 添加的初始文档数
--session-count	跟随 profile	每个 adapter 使用的 session 数
--phase-seconds	跟随 profile	单类持续压测阶段时长
--mixed-seconds	跟随 profile	混合压测阶段时长
--drain-timeout	60	等待后台任务完成的最大秒数
--data-root-uri	viking://resources/bench/load_test	Server 侧压测资源根目录
--output-dir	自动生成	报告输出目录
--ov-bin	ov	真实 CLI 子进程使用的可执行文件

Profile 说明

Profile	用途	特点
smoke	快速验证脚本、配置和 Server 可用性	时间短、并发低、数据少
standard	常规压测	默认推荐配置
stress	高压力压测	并发和数据量更高，耗时更长

建议先跑 smoke，确认报告正常生成后再跑 standard 或 stress。

报告输出

默认输出目录类似：

benchmark/results/openviking_server_load/20260511T120000Z/

主要文件：

文件	内容
summary_zh.md	中文压测报告，优先阅读
run_summary.json	汇总结果，便于自动分析
request_events.jsonl	每次请求的明细事件
task_events.jsonl	后台任务完成和积压明细
request_summary.csv	按 adapter / 阶段 / 接口聚合的 QPS、成功率、延迟
request_windows.csv	按时间窗口聚合的请求表现
adapter_comparison.csv	SDK / CLI 路径对比
errors.csv	错误 Top 明细

报告会重点展示：

• 总请求量、失败数和成功率。
• 各接口 p50 / p95 / p99 / max 延迟。
• retrieval 阶段到 mixed 阶段的检索延迟变化。
• SDK、CLI HTTP 封装、真实 CLI 子进程之间的差异。
• commit / add_resource 后台任务是否积压。
• Top 错误类型和发生位置。

示例：指定认证信息

.venv/bin/python benchmark/custom/session_contention_benchmark.py \
  --server-url http://127.0.0.1:1935 \
  --api-key your-root-api-key \
  --account default \
  --user default \
  --profile standard

也可以通过环境变量传入：

export OPENVIKING_SERVER_URL=http://127.0.0.1:1935
export OPENVIKING_API_KEY=your-root-api-key
export OPENVIKING_ACCOUNT=default
export OPENVIKING_USER=default

.venv/bin/python benchmark/custom/session_contention_benchmark.py --profile smoke

示例：降低真实 CLI 子进程开销

真实 cli-subprocess 会为每个请求启动一次 ov 进程，开销明显高于 SDK 路径。若只想压 Server 本身，可以先排除它：

.venv/bin/python benchmark/custom/session_contention_benchmark.py \
  --profile standard \
  --adapters sdk,cli-http

若必须测试真实 CLI，但本地 ov 不在 PATH 中，可以指定可执行文件：

.venv/bin/python benchmark/custom/session_contention_benchmark.py \
  --profile smoke \
  --adapters cli-subprocess \
  --ov-bin .venv/bin/ov

常见问题

1. Server 连接失败

先确认 Server 已启动：

curl http://127.0.0.1:1935/health

如果端口不同，请设置 --server-url。

2. 认证失败

确认 --api-key、--account、--user 与当前 Server 配置一致。多租户模式下，root key 请求通常还需要 account 和 user。

3. cli-subprocess 失败

确认 ov 可执行：

ov health

如果不可用，使用 --ov-bin .venv/bin/ov 或只运行 sdk,cli-http。

4. 后台任务没有在 drain 内完成

这通常说明资源处理或 session commit 的后台任务积压。可以：

• 增大 --drain-timeout
• 降低并发参数
• 查看 task_events.jsonl
• 查看 Server 日志和 observer queue 状态

5. 多次运行结果差异较大

压测会受本机 CPU、磁盘、模型配置、队列积压和真实 CLI 进程启动开销影响。建议：

1. 先跑 smoke 验证环境。
2. 连续跑多次 standard。
3. 对比 adapter_comparison.csv 和 request_windows.csv。
4. 避免在已有大量后台任务未完成时启动下一轮。