LoCoMo Eval Kit

LoCoMo 记忆系统评测工具包。包含三种规模的评测脚本，支持 OV 直入和 OpenClaw 会话两种导入模式。

详细测试说明见 TESTING.md。 oG-Memory + OpenClaw 联调说明见 OGMEMORY_OPENCLAW_TESTING.md。

目录结构

locomo-eval-kit/
├── README.md               ← 本文件
├── scripts/
│   ├── run_eval_case0.sh   ← 标准 case0 评测（locomo10.json sample 0）
│   ├── run_eval_small.sh   ← small 全量评测（locomo10_small.json）
│   ├── run_eval_full.sh    ← 完整评测（locomo10.json 全部 10 samples）
│   ├── eval.py             ← 核心：会话注入 + QA 评测
│   ├── import_to_ov.py     ← 核心：OV 直接导入
│   ├── judge.py            ← 核心：LLM 评分
│   ├── stat_judge_result.py← 核心：结果统计
│   ├── report.py           ← 核心：错误分析报告生成
│   └── config.toml.example ← run_benchmark.py 用的配置模板（参考）
├── data/
│   ├── locomo10.json       ← 完整数据集（2.8MB，10 samples）
│   └── locomo10_small.json ← 精简数据集（27KB）
├── tools/
│   └── clean_openclaw.py   ← 清理 OpenClaw sessions 工具
└── result/                 ← 评测结果输出目录

数据集对照

脚本	数据文件	规模	预估时间
run_eval_case0.sh	locomo10.json --sample 0	1 sample / ~35 QA	~5-7 分钟
run_eval_small.sh	locomo10_small.json（全部 samples）	多 samples / 精简	~10-15 分钟
run_eval_full.sh	locomo10.json（全部 10 samples）	10 samples / ~350 QA	~40-60 分钟

前置依赖

Python 环境

pip install requests openai python-dotenv
pip install openviking   # OV 直入模式需要

服务

服务	用途	默认地址
OpenClaw Gateway	QA 评测 + OpenClaw 会话导入	http://127.0.0.1:19789
OpenViking HTTP	OV 直入导入	http://127.0.0.1:2934

环境变量

# Gateway Token（也可通过 --gateway-token 参数传入）
export OPENCLAW_GATEWAY_TOKEN="your_token_here"

# Judge 模型 API Key（judge.py 从环境变量读取）
export ARK_API_KEY="your_ark_api_key"
# 或
export OPENAI_API_KEY="your_api_key"

快速开始

cd scripts
chmod +x run_eval_*.sh

# 1. 标准 case0（推荐首次测试用这个）
./run_eval_case0.sh --import-mode ov --gateway-token YOUR_TOKEN

# 2. small 全量
./run_eval_small.sh --import-mode ov --gateway-token YOUR_TOKEN

# 3. 完整 10 samples
./run_eval_full.sh --import-mode ov --gateway-token YOUR_TOKEN

导入模式说明

每个脚本都通过 --import-mode 指定导入方式：

模式	说明	适用场景
ov	OV 直接导入（import_to_ov.py）	测 recall/记忆质量，跳过 agent 循环
claw	OpenClaw 会话导入（eval.py ingest）	测完整 agent 流程（注入→compact→commit→archive）
both	OV + OpenClaw 并行导入	对比两种路径的记忆差异
skip	跳过导入，直接 QA	已有数据，只想重跑 QA/Judge

全部可选参数

参数	说明	默认值
--import-mode MODE	必填。ov / claw / both / skip	—
--run-id NAME	运行标识（结果目录名后缀）	时间戳
--force-ingest	强制重新导入（忽略已完成记录）	否
--qa-parallel N	QA 并发数	case0=5, small=10, full=15
--judge-parallel N	Judge 评分并发数	case0=10, small=10, full=20
--gateway-url URL	OpenClaw Gateway 地址	http://127.0.0.1:19789
--gateway-token TOKEN	Gateway 认证 Token	环境变量 OPENCLAW_GATEWAY_TOKEN
--ov-url URL	OpenViking 服务地址	http://127.0.0.1:2934
--skip-judge	跳过 Judge 评分	否
--skip-stat	跳过统计	否
--sample N	（仅 full）只跑指定 sample	全部

评测流程

Step 1: 导入（OV 直入 / OpenClaw 会话 / 两者并行）
  ↓
Step 2: QA 评测（eval.py qa → qa_results.csv）
  ↓
Step 3: Judge 评分（judge.py → 更新 csv 中 result/reasoning 列）
  ↓
Step 4: 统计（stat_judge_result.py → summary.txt）
  ↓
Step 5: 错误分析报告（report.py → error_analysis.md + findings.json）

结果目录

每次运行会在 result/ 下创建独立目录：

result/case0_20260420_153000/
├── qa_results.csv        ← QA 回答 + Judge 评分结果
├── import_success.csv    ← 导入成功记录（OV 模式）
├── import_ov.log         ← OV 导入日志
├── import_claw.log       ← OpenClaw 导入日志（claw/both 模式）
├── qa.log                ← QA 运行日志
├── judge.log             ← Judge 评分日志
├── stat.log              ← 统计输出日志
├── summary.txt           ← 最终准确率统计
└── report/               ← 错误分析报告（report.py 生成）
    ├── locomo_error_analysis.md   ← 分析报告
    └── locomo_findings.json       ← 结构化错误数据

清理工具

# 清理 OpenClaw sessions（重新导入前使用）
python tools/clean_openclaw.py

自定义端口

如果部署环境的端口不同于默认值：

./run_eval_case0.sh \
    --import-mode ov \
    --gateway-url http://127.0.0.1:18789 \
    --ov-url http://127.0.0.1:1933 \
    --gateway-token YOUR_TOKEN

错误分析报告（report.py）

评测完成后，可用 report.py 对错误样本进行深度分析，生成失败模式标注（A–G）和分析报告。

前置条件

• qa_results.csv 中 Judge 已完成（result 和 reasoning 列已填充）
• LLM 模式需要 API Key（同 judge.py，使用 ARK_API_KEY 或 OPENAI_API_KEY）

基本用法

# LLM 增强模式（推荐，生成完整 13 节分析报告）
python scripts/report.py \
  --input result/small_xxx/qa_results.csv \
  --api-key "$ARK_API_KEY"

# 纯计算模式（不需要 API Key，输出统计结果和基础报告）
python scripts/report.py \
  --input result/small_xxx/qa_results.csv \
  --no-llm

全部参数

参数	说明	默认值
--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 / en	zh（中文）

输出产物

文件	说明
locomo_error_analysis.md	分析报告（LLM 模式含 13 节完整分析；纯计算模式含 8 节基础统计）
locomo_findings.json	结构化数据，含每条错误的 Pattern 标注、信号值、归因，可跨运行 diff 对比

失败模式（A–G）

模式	名称	信号
A	过度拒绝	预测含拒绝短语 + overlap < 0.3
B	时间偏移	类别为 Temporal 的错误
C	过度泛化	预测用泛化词替代具体实体
D	幻觉/错误事实	无拒绝短语 + overlap < 0.3 + 模型表达自信
E	近命中但否认	含拒绝短语 + overlap ≥ 0.3
F	计数/时长偏差	数量类问题中数值不匹配
G	推理回避	推理类问题 + 拒绝回答

与评测流程集成

# 评测后自动生成报告
./run_eval_small.sh --import-mode claw --gateway-token YOUR_TOKEN
LATEST=$(ls -td result/small_*/ | head -1)
python report.py --input "${LATEST}qa_results.csv" --api-key "$ARK_API_KEY"

渲染 PDF

pandoc locomo_error_analysis.md -o locomo_error_analysis.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Noto Sans CJK SC" \
  -V geometry:margin=20mm -V papersize=a4

常见问题

Q: OV 导入后 QA 结果异常？ A: 确保导入完成后 OV 有足够时间处理（脚本已内置等待时间）。如果仍有问题，重启 OV 再试。

Q: Judge 评分报 API Key 错误？ A: 设置 ARK_API_KEY 环境变量，或在 ~/.openviking_benchmark_env 文件中配置。

Q: 如何只重跑 Judge 不重跑 QA？ A: 直接调用 python scripts/judge.py --input result/xxx/qa_results.csv。

Q: report.py 报 No errors found？ A: 确认 qa_results.csv 中 result 列已由 judge.py 填充（CORRECT/WRONG）。如果 Judge 未运行，所有记录都被视为未评分。

Q: 没有 API Key 能用 report.py 吗？ A: 可以，加 --no-llm 即可输出纯计算的分析结果（Pattern 标注、交叉矩阵、统计表等），只是不含 LLM 生成的定性分析和辩证自查。