0738f6ed创建于 24 天前历史提交

LoCoMo Eval Kit 测试文档

本文档用于说明如何在本地测试 locomo-eval-kit，重点覆盖 scripts/run_eval_small.sh 的运行方式、参数含义、结果产物和常见排障。

适用对象：

第一次接手这个仓库，需要快速把评测跑通的人
想验证 OpenClaw / OpenViking 服务联通性的人
想重跑 QA、Judge 或统计阶段的人

1. 测试目标

这个仓库的评测流程，本质上是在做 4 件事：

把 LoCoMo 对话数据导入记忆系统
对数据集中的 QA 问题发起查询
用 Judge 模型判断回答是否正确
汇总准确率和 token 消耗
生成错误分析报告，标注失败模式并给出改进建议

其中：

run_eval_case0.sh 用于最小规模验证，适合首次联调
run_eval_small.sh 用于精简数据集的完整测试
run_eval_full.sh 用于完整数据集的全量评测

如果你的目标是“确认环境可用，并且结果基本可信”，建议顺序是：

先跑 run_eval_case0.sh
再跑 run_eval_small.sh
最后再决定是否跑 run_eval_full.sh

2. 脚本选择建议

脚本	数据集	用途	预计耗时
`scripts/run_eval_case0.sh`	`data/locomo10.json` 的 sample 0	首次联调、快速验证	约 5-7 分钟
`scripts/run_eval_small.sh`	`data/locomo10_small.json` 全部 samples	推荐日常测试	约 10-15 分钟
`scripts/run_eval_full.sh`	`data/locomo10.json` 全部 10 samples	完整回归评测	约 40-60 分钟

推荐原则：

想先确认服务和参数没问题：跑 case0
想做一轮比较完整、但成本还可接受的测试：跑 small
想做最终准确率统计或提交前回归：跑 full

3. `run_eval_small.sh` 在做什么

scripts/run_eval_small.sh 是一个“编排脚本”，它不是单独做某一个算法动作，而是把完整测试流程串起来。

它使用的数据集是：

data/locomo10_small.json

它的标准执行流程如下：

Step 1. 导入数据

由 --import-mode 决定导入方式：

ov 调用 scripts/import_to_ov.py 直接将数据导入 OpenViking
claw 调用 scripts/eval.py ingest 通过 OpenClaw 的会话写入流程导入数据
both 同时跑 OV 直入和 OpenClaw 会话导入
skip 跳过导入阶段，直接进入 QA

Step 2. QA 测试

调用：

python scripts/eval.py qa ...

作用：

遍历 small 数据集里的 QA 问题
调用 OpenClaw Gateway 获取回答
将结果写入 qa_results.csv

Step 3. Judge 评分

调用：

python scripts/judge.py ...

作用：

使用 LLM 对“标准答案”和“模型回答”做一致性判断
将结果写回 qa_results.csv
主要结果列通常包括 result 和 reasoning

Step 4. 结果统计

调用：

python scripts/stat_judge_result.py ...

作用：

统计正确数、错误数、准确率
汇总 QA 阶段 token 消耗
如果存在 OV 导入统计，还会统计导入 token
在结果目录下生成 summary.txt

Step 5. 错误分析报告（report.py）

调用：

python scripts/report.py --input result/small_xxx/qa_results.csv --api-key "$ARK_API_KEY"

作用：

对所有错误样本计算辅助信号（Jaccard overlap、证据定位三分位、拒绝词检测等）
标注失败模式 A–G（过度拒绝/时间偏移/过度泛化/幻觉/近命中/计数偏差/推理回避）
生成分析报告 locomo_error_analysis.md 和结构化数据 locomo_findings.json

前置条件：

Judge 已完成（qa_results.csv 中 result 和 reasoning 列已填充）
LLM 模式需要 API Key（同 judge.py）

两种模式：

模式	命令	说明
LLM 增强	`python report.py --input ... --api-key $KEY`	生成完整 13 节分析报告（推荐）
纯计算	`python report.py --input ... --no-llm`	仅输出 Pattern 标注和统计，不需 API Key

report.py 参数说明：

参数	说明	默认值
`--input`	必填，qa_results.csv 路径	—
`--output-dir`	输出目录	与 input 同目录
`--api-key`	LLM API Key	读 `ARK_API_KEY` / `OPENAI_API_KEY`
`--base-url`	LLM API 地址	`https://ark.cn-beijing.volces.com/api/coding/v3`
`--model`	LLM 模型名	`doubao-seed-2.0-code`
`--no-llm`	跳过 LLM，仅输出计算统计	关闭
`--lang`	报告语言	`zh`（中文）

4. 运行前准备

4.1 Python 依赖

至少需要安装：

pip install requests openai python-dotenv

如果你要使用 --import-mode ov 或 --import-mode both，还需要：

pip install openviking

4.2 服务准备

默认需要以下服务可用：

服务	默认地址	用途
OpenClaw Gateway	`http://127.0.0.1:19789`	QA 测试、OpenClaw 导入
OpenViking HTTP	`http://127.0.0.1:2934`	OV 直入导入、QA token 查询

说明：

run_eval_small.sh 默认会同时依赖 Gateway
当导入模式为 ov / both 时，还依赖 OpenViking
即使 import-mode=skip，QA 阶段仍然需要 Gateway

4.3 环境变量

OpenClaw Gateway Token

可以通过环境变量设置：

export OPENCLAW_GATEWAY_TOKEN="your_token_here"

也可以在运行脚本时直接传：

--gateway-token YOUR_TOKEN

Judge API Key

scripts/judge.py 默认从以下环境变量读取：

ARK_API_KEY
OPENAI_API_KEY

例如：

export ARK_API_KEY="your_ark_api_key"

如果没有设置 Judge API Key：

QA 阶段可以跑
Judge 阶段会失败
可以先加 --skip-judge 跳过评分

4.4 Shell 环境说明

这些脚本是 .sh，推荐在以下环境运行：

Linux
macOS
WSL
Git Bash

如果你在 Windows PowerShell 里工作，不建议直接把 .sh 当作 PowerShell 脚本执行。更稳妥的做法是：

进入 Git Bash 或 WSL 后运行
或者显式使用 bash 执行脚本

例如：

bash ./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

5. 标准测试流程

5.1 首次联调

首次测试建议先跑最小样本：

cd locomo-eval-kit/scripts
chmod +x run_eval_*.sh
./run_eval_case0.sh --import-mode ov --gateway-token YOUR_TOKEN

确认以下几点都正常后，再跑 small：

能成功连接 Gateway
能成功连接 OV
能生成 qa_results.csv
Judge 和统计阶段不报错

5.2 推荐的 `small` 测试命令

方案 A：最常用，OV 直入

适用场景：

想验证记忆召回效果
不需要完整模拟 OpenClaw 会话导入链路

命令：

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

方案 B：测试 OpenClaw 会话导入流程

适用场景：

想覆盖完整 agent 导入链路
关注注入、compact、commit、archive 这类行为

命令：

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode claw --gateway-token YOUR_TOKEN

方案 C：同时比较两种导入方式

适用场景：

想对比 OV 与 OpenClaw 导入路径的差异

命令：

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode both --gateway-token YOUR_TOKEN

方案 D：跳过导入，只重跑 QA / Judge

适用场景：

数据已经导入过
只想重跑问答和评分

命令：

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode skip --gateway-token YOUR_TOKEN

6. 常用测试命令

6.1 只验证 QA 能不能跑通

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN --skip-judge --skip-stat

适合：

快速验证导入和 QA
还没准备 Judge 模型 key

6.2 跳过 Judge，只看原始回答

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN --skip-judge

6.3 降低并发，便于稳定调试

cd locomo-eval-kit/scripts
./run_eval_small.sh \
  --import-mode ov \
  --gateway-token YOUR_TOKEN \
  --qa-parallel 2 \
  --judge-parallel 2

适合：

本地机器资源有限
服务端限流明显
需要更稳定地看日志

6.4 强制重新导入

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN --force-ingest

适合：

之前导入过旧数据
修改了导入逻辑，想完整重跑

6.5 指定结果目录后缀

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN --run-id debug_20260422

作用：

结果目录会变成类似 result/small_debug_20260422/
方便区分不同测试轮次

6.6 修改服务地址

如果你的服务不是默认端口：

cd locomo-eval-kit/scripts
./run_eval_small.sh \
  --import-mode ov \
  --gateway-url http://127.0.0.1:18789 \
  --ov-url http://127.0.0.1:2935 \
  --gateway-token YOUR_TOKEN

7. `run_eval_small.sh` 参数说明

参数	是否必填	说明	默认值
`--import-mode`	是	导入模式，`ov` / `claw` / `both` / `skip`	无
`--run-id`	否	结果目录后缀	当前时间戳
`--force-ingest`	否	强制重新导入	关闭
`--qa-parallel`	否	QA 并发数	`10`
`--judge-parallel`	否	Judge 并发数	`10`
`--gateway-url`	否	OpenClaw Gateway 地址	`http://127.0.0.1:19789`
`--gateway-token`	否	Gateway Token	默认读取 `OPENCLAW_GATEWAY_TOKEN`
`--ov-url`	否	OpenViking 服务地址	`http://127.0.0.1:2934`
`--skip-judge`	否	跳过 Judge 评分	关闭
`--skip-stat`	否	跳过统计汇总	关闭

注意：

--import-mode 是唯一必填参数
即使使用 --import-mode ov，QA 阶段依然需要 Gateway Token

8. 结果目录说明

每次运行都会生成一个独立目录，例如：

locomo-eval-kit/scripts/result/small_20260422_153000/

常见文件如下：

文件	说明
`qa_results.csv`	QA 回答结果，也是 Judge 回写结果的主文件
`import_success.csv`	OV 导入成功记录和 token 统计
`import_errors.log`	OV 导入错误日志
`import_ov.log`	OV 导入日志
`import_claw.log`	OpenClaw 导入日志
`qa.log`	QA 阶段日志
`judge.log`	Judge 阶段日志
`stat.log`	统计阶段日志
`summary.txt`	最终摘要，包括准确率和 token 统计
`report/`	错误分析报告目录（report.py 生成）
`report/locomo_error_analysis.md`	分析报告
`report/locomo_findings.json`	结构化错误数据（可 diff 对比不同运行）

9. 如何判断测试成功

一轮 small 测试成功，通常至少满足下面几点：

脚本退出码为 0
结果目录成功生成
qa_results.csv 存在且有数据
如果没有跳过 Judge，则 qa_results.csv 中应包含 result 列
如果没有跳过统计，则 summary.txt 存在
如果运行了 report.py，则 report/ 目录存在且有分析报告

建议重点查看：

summary.txt
qa_results.csv
qa.log
judge.log

10. 常见测试场景

场景 1：第一次把环境跑通

建议：

跑 case0
确认服务联通
再跑 small

推荐命令：

cd locomo-eval-kit/scripts
./run_eval_case0.sh --import-mode ov --gateway-token YOUR_TOKEN
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

场景 2：只想看 QA 原始回答质量

推荐命令：

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode skip --gateway-token YOUR_TOKEN --skip-judge

说明：

前提是数据已经导入过
适合排查回答内容本身是否合理

场景 3：只想重跑 Judge

run_eval_small.sh 本身不提供“只跑 Judge”开关，但可以单独调用：

cd locomo-eval-kit/scripts
python judge.py --input result/small_xxx/qa_results.csv --parallel 10

跑完后，如需重新生成统计：

python stat_judge_result.py \
  --input result/small_xxx/qa_results.csv \
  --import-csv result/small_xxx/import_success.csv

场景 4：评测后生成错误分析报告

评测完成后，用 report.py 分析错误模式：

cd locomo-eval-kit/scripts
# LLM 增强模式（推荐）
python report.py --input result/small_xxx/qa_results.csv --api-key "$ARK_API_KEY"

# 或者纯计算模式
python report.py --input result/small_xxx/qa_results.csv --no-llm

报告包含：

摘要（准确率、证据定位三分位、最差类别、最大失败模式）
A–G 七类失败模式标注与示例
模式×类别、模式×模式交叉矩阵
改进优先级与天花板估计

场景 5：数据导入脏了，想重来

如果是 OpenClaw 会话数据需要清理，可先运行：

cd locomo-eval-kit
python tools/clean_openclaw.py

然后再重跑：

cd scripts
./run_eval_small.sh --import-mode claw --gateway-token YOUR_TOKEN --force-ingest

11. 常见问题排查

11.1 报错：必须指定 `--import-mode`

原因：

该参数是必填项

解决：

./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

11.2 报错：`--token or OPENCLAW_GATEWAY_TOKEN env var is required`

原因：

QA 阶段调用 Gateway 时缺少 token

解决：

设置环境变量 OPENCLAW_GATEWAY_TOKEN
或运行时传 --gateway-token

11.3 Judge 报 API Key 错误

原因：

judge.py 未读取到 ARK_API_KEY 或 OPENAI_API_KEY

解决：

export ARK_API_KEY="your_key"

或者先跳过评分：

./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN --skip-judge

11.4 OV 导入成功，但 QA 结果异常

可能原因：

导入完成后记忆还未稳定
服务端状态不一致
旧数据和新数据混在一起

处理建议：

使用 --force-ingest 重跑
先用 case0 复现问题
查看 import_ov.log 和 qa.log
必要时清理 OpenClaw 会话或重置测试环境

11.5 `summary.txt` 没生成

可能原因：

运行时使用了 --skip-stat
前面的阶段失败了

排查：

看 stat.log
检查 qa_results.csv 是否存在

11.6 Windows 下脚本无法直接运行

原因：

.sh 是 Bash 脚本，不是 PowerShell 脚本

解决：

使用 Git Bash / WSL
或显式执行：

bash ./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

11.7 report.py 报 No errors found

原因：

qa_results.csv 中 result 列为空（Judge 未运行）

解决：

python judge.py --input result/small_xxx/qa_results.csv
python report.py --input result/small_xxx/qa_results.csv --api-key "$ARK_API_KEY"

11.8 report.py 没有 API Key

如果没有 LLM API Key，可以使用纯计算模式：

python report.py --input result/small_xxx/qa_results.csv --no-llm

输出基础统计和 Pattern 标注，不含 LLM 生成的定性分析。

12. 推荐的测试策略

如果你需要一套稳定的日常测试节奏，推荐这样用：

日常开发验证

cd locomo-eval-kit/scripts
./run_eval_case0.sh --import-mode ov --gateway-token YOUR_TOKEN

合并前回归

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

重要版本评测

cd locomo-eval-kit/scripts
./run_eval_full.sh --import-mode ov --gateway-token YOUR_TOKEN

13. 最短可复制命令

如果你只想先把 small 跑起来，可以直接用下面这条：

cd locomo-eval-kit/scripts
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

如果你是第一次跑，建议先用这条：

cd locomo-eval-kit/scripts
./run_eval_case0.sh --import-mode ov --gateway-token YOUR_TOKEN

LoCoMo Eval Kit 测试文档

1. 测试目标

2. 脚本选择建议

3. run_eval_small.sh 在做什么

Step 1. 导入数据

Step 2. QA 测试

Step 3. Judge 评分

Step 4. 结果统计

Step 5. 错误分析报告（report.py）

4. 运行前准备

4.1 Python 依赖

4.2 服务准备

4.3 环境变量

OpenClaw Gateway Token

Judge API Key

4.4 Shell 环境说明

5. 标准测试流程

5.1 首次联调

5.2 推荐的 small 测试命令

方案 A：最常用，OV 直入

方案 B：测试 OpenClaw 会话导入流程

方案 C：同时比较两种导入方式

方案 D：跳过导入，只重跑 QA / Judge

6. 常用测试命令

6.1 只验证 QA 能不能跑通

6.2 跳过 Judge，只看原始回答

6.3 降低并发，便于稳定调试

6.4 强制重新导入

6.5 指定结果目录后缀

6.6 修改服务地址

7. run_eval_small.sh 参数说明

8. 结果目录说明

9. 如何判断测试成功

10. 常见测试场景

场景 1：第一次把环境跑通

场景 2：只想看 QA 原始回答质量

场景 3：只想重跑 Judge

场景 4：评测后生成错误分析报告

场景 5：数据导入脏了，想重来

11. 常见问题排查

11.1 报错：必须指定 --import-mode

11.2 报错：--token or OPENCLAW_GATEWAY_TOKEN env var is required

11.3 Judge 报 API Key 错误

11.4 OV 导入成功，但 QA 结果异常

11.5 summary.txt 没生成

11.6 Windows 下脚本无法直接运行

11.7 report.py 报 No errors found

11.8 report.py 没有 API Key

12. 推荐的测试策略

日常开发验证

合并前回归

重要版本评测

13. 最短可复制命令

3. `run_eval_small.sh` 在做什么

5.2 推荐的 `small` 测试命令

7. `run_eval_small.sh` 参数说明

11.1 报错：必须指定 `--import-mode`

11.2 报错：`--token or OPENCLAW_GATEWAY_TOKEN env var is required`

11.5 `summary.txt` 没生成