Skip to content

USAGE.md

Latest commit

 

History

History
232 lines (153 loc) · 13.7 KB

USAGE.md

File metadata and controls

232 lines (153 loc) · 13.7 KB
Raw

kimi-cli-benchmarker 使用说明

本仓库在 Kimi Code CLI 基础上增加了 benchmark harness：在独立沙箱中复制工程模板、合并配置、以计划模式启动 Kimi，并可选使用 driver 模型 做结构化编排（见 DOCUMENTS/benchmark-spec.md）。

环境准备

  • Python：3.12+（与上游 Kimi CLI 一致）。
  • uv：用于依赖同步与 uv run kimi …。
  • 在仓库根执行一次依赖安装（与 AGENTS.md 中 make prepare / uv sync 一致）：
uv sync --all-extras --all-packages

配置与优先级

合并顺序（后者覆盖前者）：

  1. Kimi 基础配置：~/.kimi/config.toml，或通过 kimi benchmark run --config-file 指定的 TOML。
  2. 沙箱工作目录下的 .env / .env.local（python-dotenv 自 cwd 向上查找）。
  3. BENCHMARK_SUBJECT_*：写入合并后的 merged-config.toml，覆盖被测模型提供方。
  4. CLI 标志（如 --max-steps）优先级最高。

完整说明、driver JSON 契约、JSONL 恢复算法见 DOCUMENTS/benchmark-spec.md。

环境变量模板见 .env.example（复制为沙箱或仓库根下的 .env 再填写密钥）。常用项：

前缀 作用
BENCHMARK_SUBJECT_* 被测模型（注入 Kimi Config）
BENCHMARK_DRIVER_* 仅 orchestration 的 driver HTTP（不计 subject 步数）；含超时、重试、BENCHMARK_DRIVER_USER_AGENT（User-Agent 请求头）
BENCHMARK_MAX_SUBJECT_STEPS / KIMI_BENCHMARK_MAX_SUBJECT_STEPS 被测 HTTP 步数上限（CLI --max-steps 可再覆盖）

子进程内还会设置：KIMI_BENCHMARK_MODE、KIMI_BENCHMARK_MAX_SUBJECT_STEPS、KIMI_BENCHMARK_CONTEXT_JSONL（上下文 JSONL 路径）。另见 KIMI_BENCHMARK_USE_GLOBAL_MCP（见下节「MCP 与报错」）。

根命令 kimi（非子命令）也可用 CLI 设置同一语义，无需先 export 环境变量：

选项 对应环境变量
--benchmark KIMI_BENCHMARK_MODE=1
--benchmark-max-subject-steps N KIMI_BENCHMARK_MAX_SUBJECT_STEPS
--benchmark-context-jsonl PATH KIMI_BENCHMARK_CONTEXT_JSONL

示例（在沙箱根续跑会话）：

uv run kimi --work-dir . --config-file ./.kimi-benchmark/merged-config.toml \
  --mcp-config-file ./.kimi-benchmark/mcp-empty.json --yolo \
  --benchmark --benchmark-max-subject-steps 100 \
  --benchmark-context-jsonl ./.kimi-benchmark/subject-context.jsonl \
  -r <session-uuid>

MCP 与报错：Failed to connect MCP servers

原因：普通 kimi 在未指定 --mcp-config-file 时，会自动读取 ~/.kimi/mcp.json 并尝试连接其中列出的所有 MCP（例如 windows-camera）。若某个服务进程起不来或立刻断开，启动会失败；与 benchmark 本身无关，是全局 MCP 配置导致的。

本仓库默认行为：kimi benchmark run 在重入 Kimi 时会在沙箱 .kimi-benchmark/mcp-empty.json 写入空的 mcpServers，并加上 --mcp-config-file，从而不再加载你本机的 mcp.json，benchmark 可在无 MCP 下跑。

若你确实要在 benchmark 沙箱里使用全局 MCP，可在运行 benchmark 之前在环境里设置：

set KIMI_BENCHMARK_USE_GLOBAL_MCP=1

（Linux/macOS：export KIMI_BENCHMARK_USE_GLOBAL_MCP=1）。此时请保证 ~/.kimi/mcp.json 里所列服务均可连接，或删掉/禁用失败项。

日常只用 uv run kimi（非 benchmark）时行为不变，仍会读全局 mcp.json。

kimi benchmark run（核心命令）

在已 uv sync 的前提下：

uv run kimi benchmark run \
  --template path/to/template-dir \
  --project-name MyProj \
  --model-slug gpt-4.1 \
  --reasoning-effort high \
  --requirements path/to/requirement-document.md

常用可选参数：

选项 说明
--dest-parent / -d 沙箱父目录；其下会新建 benchmark-<project>-<model>-<effort>-<utc-time>/（末尾为 UTC ISO 时间，空格与冒号改为 -）并整棵复制模板。默认当前工作目录。
-p / -m / -e 可省略：在加载 cwd 与 --dest-parent 链上的 .env 之后，分别默认自 BENCHMARK_RUN_PROJECT_NAME、BENCHMARK_SUBJECT_MODEL（再 BENCHMARK_RUN_MODEL_SLUG）、BENCHMARK_RUN_REASONING_EFFORT。不会读取 .env.example。
--max-steps 被测模型 HTTP generate 次数上限。
--config-file 合并前的 Kimi 基础 TOML。

首次用户消息来自 --requirements 指向的 Markdown（通常即模板内 DOCUMENTS/requirement-document.md）。

沙箱内会生成 .kimi-benchmark/：merged-config.toml、state.json、subject-context.jsonl 等；运行结束后写入 report.json / report.md（含原始 metrics、api_efficiency 派生指标、以及沙箱带 .git 时的 diff_summary：git diff --numstat HEAD 等）。模板建议在 .gitignore 中加入 .kimi-benchmark/（见 benchmark-project-template/hello-world/.gitignore）。

查看全部选项：

uv run kimi benchmark run --help

kimi benchmark reports（仅评估阶段）

对已跑完 kimi benchmark run 的沙箱，不再启动被测 Kimi 子进程，只重新执行与 write_benchmark_reports 相同的评估链路：

  • 按 .kimi-benchmark/state.json 中的 validate bundle 重跑 blackbox / performance（若模板带 validate 包）；
  • 刷新 git diff_summary；
  • 若已配置 BENCHMARK_DRIVER_API_KEY，重跑 checklist driver review；
  • 从已有 report.json 读取 metrics（若存在），再计算 api_efficiency，并覆盖写入 report.json / report.md。

Checklist driver 逐文件评审时会 跳过 diff 中的 .md 路径（完成度不按 Markdown 文档改动聚合）；diff_summary 仍照常汇总工作区路径（含 .md），便于人工对照。

uv run kimi benchmark reports ./benchmarks/benchmark-bench-kimi-k2.6-high-2026-04-28T20-58-58+00-00

运行过程中会在 stderr 持续输出 [benchmark] … 行（例如 reports: starting、validate:blackbox: subprocess running、validate 各阶段结束、reports: running checklist driver review）。SillyTavern 等黑盒含 npm install / webpack 时可能 数分钟无新输出，属正常耗时，并非卡死。

在 交互式终端（stderr 为 TTY、且未设置 NO_COLOR）下，write_benchmark_reports 还会用 Rich 在 stderr 上显示总进度（validate → api_efficiency → git diff → checklist）与子任务：validate 子进程无流式输出时为 spinner + 已运行时长；checklist 为 M/N 文件进度（report.json 里 per_file 仍按候选路径稳定排序输出，与旧版一致）。checklist 的 driver HTTP 可用 kimi benchmark reports --max-concurrency N（1–32）或 KIMI_BENCHMARK_REPORTS_MAX_CONCURRENCY 做限流并行；blackbox / performance 与 git diff 仍串行。默认并发为 1（与仅串行 HTTP 时一致）。kimi benchmark run 子进程结束时触发的 write_benchmark_reports 没有该 CLI 参数，仅读环境变量。结束时额外一行 [benchmark] reports: total wall time …（含各阶段累计秒数摘要）。非 TTY（如重定向到文件/CI）或设置 NO_COLOR 时仍只输出上述 [benchmark] 文本行。可用 kimi benchmark reports --plain 或环境变量 KIMI_BENCHMARK_REPORTS_PLAIN=1 强制关闭 Rich，便于脚本解析 stderr。

# 可选：checklist 阶段最多 4 路并行 driver HTTP（validate 仍串行）
uv run kimi benchmark reports ./benchmarks/benchmark-bench-kimi-k2.6-high-2026-04-28T20-58-58+00-00 --max-concurrency 4

若要同时对多个沙箱做评估，请自行在多个终端或用脚本启动多个 kimi benchmark reports <各自沙箱路径> 进程（注意磁盘、CPU 与 BENCHMARK_DRIVER_API_KEY 的并发配额）。

若沙箱内尚无 report.json，metrics 按空对象处理（api_efficiency 可能多为零）。仅想更新 checklist 与 diff、不重跑 validate 子进程时，仍可用 kimi benchmark checklist-review <sandbox>（见该子命令 --help）。

一键脚本：scripts/run_benchmark.py

新开 benchmark

自动 uv sync → uv run kimi benchmark run；模板与沙箱父目录必填。

uv run python scripts/run_benchmark.py -t benchmark-project-template/SillyTavern-1.17.0 -d ./benchmarks  --post-reports # 运行并生成报告
uv run python scripts/run_benchmark.py -t hello-world -d /path/to/sandbox-parent
uv run python scripts/run_benchmark.py -t benchmark-project-template/hello-world -d ./runs
uv run python scripts/run_benchmark.py -t hello-world -d ./runs --dry-run

默认需求文档为模板内 DOCUMENTS/requirement-document.md，覆盖请用 --requirements（脚本里 -r 保留给续跑会话 id，与 kimi -r 一致）。

完整流程（subject + 报告）说明

子进程里的 kimi benchmark run 在复制模板、重入 Kimi 时会带上 --prompt（需求全文）。Shell 对此走 「单轮用户输入跑完即退出」：被测模型完成多步 tool loop 并 idle 后进程回到 benchmark run 入口，仍在同一进程里继续执行 write_benchmark_reports（validate、diff、checklist、report.json / report.md 等）。因此仅执行本脚本、不加额外标志，即可在 -d 下新生成的 benchmark-<project>-<model>-<effort>-<utc-time>/ 里拿到完整报告；不是模型主动「关掉会话」导致没有报告阶段。

若你希望脚本在 kimi benchmark run 结束后再跑一遍 kimi benchmark reports <沙箱>（例如怀疑内层未写出 report.json、或要强制刷新评估），可加上 --post-reports。脚本会在 -d 下按与 prepare_sandbox 相同的目录前缀 benchmark-<project>-<model>-<effort>-* 查找子目录，并以 .kimi-benchmark/state.json 修改时间最新 的一个作为沙箱路径。注意：这会 整套 validate 再跑一遍（SillyTavern 等可能很慢），适合作为兜底而非每次必开。

uv run python scripts/run_benchmark.py -t benchmark-project-template/SillyTavern-1.17.0 -d ./benchmarks --post-reports

--dry-run：只打印将执行的命令（含 uv sync 时也会打印），不真正运行；若同时指定 --post-reports，会依次打印 kimi benchmark run 与 kimi benchmark reports 两行。

仅补报告、不重跑 subject 时，仍可直接对沙箱目录执行 uv run kimi benchmark reports <沙箱根>（见上一节）。

续跑已有沙箱

不再执行 benchmark run（避免删目录重拷）。在沙箱根执行且 --resume / -r 只接 session uuid 即可（当前目录须含 .kimi-benchmark/merged-config.toml）；或在任意目录加 --sandbox path/to/sandbox。

cd benchmarks/benchmark-bench-gpt-4.1-high
uv run python ../../scripts/run_benchmark.py -r fd462f99-80c8-4d1a-97d0-a58f708c1a5d

# 或在仓库根用 --sandbox（推荐，路径不依赖 cd 深度）
uv run python scripts/run_benchmark.py -r <uuid> --sandbox ./benchmarks/benchmark-bench-gpt-4.1-high

# 覆盖默认续跑提示（默认与下面一致，可不写）
uv run python scripts/run_benchmark.py -r <uuid> --sandbox ./benchmarks/benchmark-bench-gpt-4.1-high \
  --continue-prompt "请继续完成任务"

续跑（-r）时若未传 --continue-prompt，脚本会自动向子进程传入 kimi --prompt "请继续完成任务"，等价于替你输入该句并回车，避免卡在交互式 Shell。--yolo 只自动批准工具，不会单独驱动多轮对话。

如需其它首条用户消息，显式传入 --continue-prompt "…" 即可。

续跑时会带上 --benchmark、--benchmark-max-subject-steps（默认读沙箱 state.json 的 max_subject_steps，可用 --max-steps 覆盖）、--benchmark-context-jsonl 指向同一 subject-context.jsonl。

-p / -m / -e 仅影响新开时的目录名；续跑不需要。.env 加载规则与上文一致。

更细说明：uv run python scripts/run_benchmark.py --help。

工程模板：benchmark-project-template/

目录 说明
hello-world/ 最小 Python 示例 + DOCUMENTS/requirement-document.md（冒烟 / 小任务）。
hello-world-validate/ 对 hello-world 的黑盒验收脚本 validate.py（stdout / 退出码）；含 fixtures/reference_subject 用于自检。见该目录 README.md。
SillyTavern-1.17.0/ 大型嵌入式场景模板；其自有 CLI / harness 说明见模板内 USAGE.md。

新增模板时，建议至少包含可读的 DOCUMENTS/requirement-document.md，以便 -r 默认路径成立。

日常开发（上游 Kimi CLI）

与 benchmark 无关的常规开发流程仍以 AGENTS.md 为准，例如：

make prepare   # 或 uv sync …
make format
make check
make test
uv run kimi --help

相关文档索引

文档 内容
DOCUMENTS/benchmark-spec.md 合并顺序、子进程环境、driver JSON、JSONL、helper 脚本摘要
DOCUMENTS/original-prompt.md benchmark 设计原始说明
.env.example 环境变量字面名与注释
AGENTS.md 仓库架构、质量门禁、发布约定