ground_truth_eval/
├── configs/        # 配置（提示词、参数等）
├── data/           # 数据模型定义
├── inference/      # 模型推理（本地/远程）
├── evaluator/      # LLM 评测、规则检查
├── report/         # 结果汇总与分析
└── run_eval.py     # 主评测入口

考虑CodeAgent的一般是面向用户进行多轮交互，并在每个轮次还往往存在工具的多次调用，故我们会从过程、整体等多个维度来对CodeAgent的模型进行评估。

根据评估的客观性程度，我们构造了三个级别的客主观性评估，从最客观的：1）工具参数定义黄金标准，到 2）参考(Opus)蒸馏数据，以及 3）LLM-as-judger，评估客观性依次降低。

1. 黄金规则使用tool定义的刚性规则进行检查。匹配工具名，以及该工具定义为required属性的参数名，计算EM

2. 待测模型的输出跟Opus的输出进行对比，工具名称+工具的参数名（检验工具调用的合法），以及工具名称+工具参数的key-value（检验蒸馏效果），记算EM指标

3. LLM judger，针对LLM面向单次用户Request的完整回复，以及单轮次message的回复这两个粒度进行打分：

   a) req（Request 级别）：对用户单次请求的整体完成质量进行评测。无论 Agent 响应了多少次（单次回复或多轮工具调用），关注的是"用户的任务是否被完整、正确地完成". 覆盖模型对用户任务的意图对齐、任务达成度以及执行的完整性和效率4个子维度

   b) msg（Message 级别）：对每个 assistant 响应进行细粒度评测。在多步交互场景中，评估"这一步是否正确推进了任务". 覆盖单轮次响应的意图理解以及工具的执行完整性2个维度

我们把前面三个级别的评价归属到规则和LLM两种测评方式，前面两个具备真值的，我们归属到规则检查， 第三个LLM-as_judger 作为LLM测评，规整如下：

方式	类型	说明
LLM 评测	llm_req / llm_msg	由 LLM 作为评委，分别表示对request/message的响应质量进行多维度打分
规则检查	rule_check	基于逻辑规则以及给定的真值，检查工具调用的结构和参数有效性，以及跟Opus真值的匹配度

使用 run_eval.py 完成完整流程：推理 → 评测 → 分析

cd evaluation/agent

# 完整流程：推理 + 评测 + 分析
python -m ground_truth_eval.run_eval \
    --model_path /path/to/model/checkpoint-1000 \
    --data_path testset_v3.jsonl \
    --output_dir /path/to/results \
    --eval_type llm_msg,rule_check \
    --plot

# 使用 model_dir 自动查找最新 checkpoint
python -m ground_truth_eval.run_eval \
    --model_dir /path/to/model \
    --data_path testset_v3.jsonl \
    --output_dir /path/to/results

参数	必填	默认值	说明
--output_dir	是	-	结果保存根目录
--model_path	条件必填	-	待测模型路径（具体 checkpoint）
--model_dir	条件必填	-	模型目录（自动查找最新 checkpoint）
--data_path	推理时必填	-	测试数据路径
--output_length	否	1024	推理输出长度
--max_model_len	否	65536	vllm 推理的上下文长度
--eval_type	否	rule_check	评测类型
--model	否	-	LLM Judge 模型
--api_key	否	-	LLM API 密钥

参数	说明
--remote_host	远端机器 IP
--remote_user	SSH 用户名
--remote_password	SSH 密码
--conda_env	远端 conda 环境

评测结果按模型名（从 model_path 最后一级目录提取）组织：

$output_dir/
├── infer_out/                    # 推理结果
│   └── checkpoint-1000.jsonl
├── checkpoint-1000/              # 模型评测结果（以模型名命名）
│   ├── llm_msg_results.jsonl     # LLM 评测详细结果
│   ├── rule_check_results.jsonl  # 规则检查详细结果
│   ├── summary.json              # 汇总报告
│   └── invalid_tools.jsonl       # 不合法工具调用情况
├── model_analysis/               # 模型分析
│   ├── summary.csv
│   └── model_comparison.csv
└── logs/                         # 日志

维度	说明	好的标准
intent_alignment	响应是否与当前任务意图对齐	5 分：完全对齐，精准识别当前步骤需要做什么
action_validity	执行的操作是否有效正确	5 分：操作完全正确，工具/参数选择最优

指标	说明	好的标准
total_tool_calls	工具调用总次数	-
valid_tool_calls	有效调用次数	越接近 total 越好
invalid_tool_calls	无效调用次数	应为 0
tool_validity_rate	工具调用有效率	100% 表示无错误调用

检查内容：

1. 结构检查：id、type、function、name、arguments 字段是否完整
2. 工具名检查：是否在可用工具列表中
3. 参数检查：是否有多余 key，是否缺少 required 参数

指标	说明	好的标准
tool_call_exact_match_rate	工具调用完全匹配率（名称+参数值）	越接近 100% 越好
tool_call_name_param_match_rate	工具名+参数 key 匹配率	越接近 100% 越好