范围：第四部分「通信、训练与评估」｜Hello-Agents 第十至十二章

---

全局知识地图：三章在讲什么

章	回答的核心问题	与前后章的关系
第十章	智能体如何接工具（MCP）、接同伴（A2A）、接网络（ANP）	把第七章的工具注册升级为标准化协议，工具可跨进程、跨语言、跨客户端复用
第十一章	当提示词工程到顶之后，如何用强化学习直接训练智能体的策略	全书唯一触及"训练侧"的章节；前承第 3 章 LLM 训练原理
第十二章	怎么证明你的智能体真的变好了	为第 13/14 章项目和你的简历提供可量化数字

一句话串联：先用协议把能力接进来（第十章）→ 再决定是调提示词还是直接训练模型（第十一章）→ 无论走哪条路，都要用评测数据说话（第十二章）。

贯穿三章的暗线：三者都是工程化手段而非"更聪明的提示词"——协议解决复用，训练解决能力上限，评估解决可信度。三者缺一，项目就停在 demo 阶段。

---

前置主线回顾（衔接第 1–9 章）

进入十至十二章前需要带上的主线（第 1–9 章，本三章不再重复，但处处在用）：

1. Agent Loop：感知 → 思考（规划 + 工具选择）→ 行动 → 观察，对外表现为 Thought / Action / Observation；三大范式 ReAct / Plan-and-Solve / Reflection（第十章 A2A 案例正是把 ReAct Agent 跨进程拆分）。
2. LLM 能力边界：自回归"预测下一个词" → 无事实核查（幻觉）、无状态、知识有截止、注意力稀缺（Context Rot）；第十一章的答案是改模型本身的策略而非再补上下文。
3. Prompt 工程原则：角色 → 任务 → 格式规约 → 动态上下文 → 终止条件，追求"最小必要信息集"。⚠️ 第十章 MCP 与第十二章 GAIA 都印证同一条：工具描述质量 / 答案格式约束直接决定成败（GAIA_SYSTEM_PROMPT 连"不写单位符号、列表按字母序排"都写了）。

---

第十章 智能体通信协议（重点）

10.1 通信协议基础

10.1.1 为什么需要协议 ⭐

单体 Agent 的三个根本性限制：

1. 工具集成困境：每个外部服务（GitHub API、数据库、文件系统）都要手写 BaseTool 子类。
2. 能力扩展瓶颈：能力被预定义工具集锁死，无法在运行时动态发现。
3. 协作缺失：研究员、撰写员、编辑这类多专家组合只能手动编排。

手写适配器的四类问题：代码重复、难维护、无法复用、扩展性差。

协议的价值：像 TCP/IP 统一设备互联一样统一 Agent 与外部世界的访问，带来标准化接口、互操作性、动态发现、可扩展性四点改变。
协议化后的写法：MCPTool(server_command=["npx","-y","@modelcontextprotocol/server-github"]) 等，统一 agent.add_tool(...)，无需手写适配器。

10.1.2 三种协议的理念比较 ⭐⭐

一句话区分：MCP 回答"如何访问工具"，A2A 回答"如何与其他智能体对话"，ANP 回答"如何在大规模网络中发现并连接智能体"。

协议	提出方	定位	设计哲学	生态成熟度
MCP	Anthropic 团队	智能体与工具的桥梁	上下文共享：Server 不只给文件内容，还能给代码结构、依赖关系、提交历史等上下文	相对成熟（推荐优先选大厂背书的服务器）
A2A	Google 团队	智能体之间的对话系统	对等通信（P2P）：每个 Agent 既是提供者也是消费者，避免中心协调器瓶颈	有 SDK，但实现多为 Sample Code
ANP	开源社区（技术白皮书）	智能体的"互联网"	去中心化服务发现：提供注册、发现与路由，无需预配置连接关系。构建大规模智能体网络的基础设施	尚无成熟生态

选型规则：

• 访问外部服务（文件、数据库、API）→ MCP
• 多个智能体协作 → A2A
• 大规模智能体生态系统 → ANP
• ⭐ 协议仍处于发展早期，工具时效性取决于维护者，更推荐选择大公司背书的 MCP 工具

10.1.3 HelloAgents 的三层协议架构

层	内容
协议实现层	MCP 基于 FastMCP；A2A 基于 Google 官方 a2a-sdk（可选依赖）；ANP 是自研轻量级概念模拟
工具封装层	MCPTool / A2ATool / ANPTool 均继承 BaseTool，提供一致的 run()
智能体集成层	ReActAgent / SimpleAgent 等全部通过工具系统使用协议工具，不感知底层协议

protocols/
├── mcp/{client.py(5种传输), server.py(FastMCP封装), utils.py}
├── a2a/implementation.py        # 基于 a2a-sdk
└── anp/implementation.py        # 服务发现/注册
tools/builtin/protocol_tools.py  # MCPTool / A2ATool / ANPTool

环境与快速体验：安装 pip install "hello-agents[protocol]==0.2.2" + NodeJS（很多社区服务器走 npx）。三种协议统一用 JSON action 调用——MCP {"action":"call_tool","tool_name":"add","arguments":{"a":10,"b":20}} → 30.0；ANP register_service / discover_services；A2A A2ATool("http://localhost:5000")。

10.2 MCP 协议实战（重点）

10.2.1 核心概念

MCP（Model Context Protocol） = 智能体的"USB-C"：把所有外部工具交互收敛到一个接口，同一份工具可被 Claude、GPT 或任何支持 MCP 的模型复用。解决的痛点：不同 LLM 平台的 function calling 实现差异巨大，换模型就要重写代码。

三层架构 Host / Client / Server（以 Claude Desktop 回答"我桌面上有哪些文档"为例）：

• Host：管理对话与 UI（如 Claude Desktop）；
• Client：模型判定需要外部信息后激活，与对应 Server 建立连接；
• Server：执行真实操作（如文件系统 MCP Server 扫描目录）。

完整链路：用户问题 → Host → 模型分析 → 判定需要工具 → Client 连接 → Server 执行 → 结果返回 → 模型生成回答 → 显示。优势是关注点分离。

三大核心能力：

能力	一句话	性质
Tools	可被模型调用的函数	主动：执行操作
Resources	可被读取的数据源（文件、数据库记录）	被动：提供数据
Prompts	预定义的提示词模板	指导性：提供模板

10.2.2 五步工作流 ⭐

1. 工具发现：连上 Server 后 list_tools()，拿到名称、说明、参数定义。
2. 上下文构建：Client 转成 LLM 可读格式注入系统提示词（如 read_file(path: str)）。
3. 模型推理：LLM 决定是否调用、调用哪个。
4. 工具执行：Client 通过 Server 执行。
5. 结果整合：结果回灌 LLM 生成最终回答。

⭐ 关键结论：过程全自动，工具描述质量直接决定工具是否被正确使用——清晰准确的 description 是 MCP 工程第一要务（与第七章"get_tools_description() 进系统提示词"同一件事）。

10.2.3 MCP vs Function Calling

原文用同一个"访问 GitHub 仓库 + 本地文件系统"任务对比两种实现：

	Function Calling	MCP
本质	模型的内在能力	工程层基础设施协议
解决什么	知道何时调用、如何生成参数	工具与模型如何连接、如何标准化描述与调用
与模型关系	强绑定，各家 schema 不同（OpenAI 用 parameters，Claude 用 input_schema）	与模型无关，OpenAI/Claude/Llama 共用同一客户端

⭐ 类比：Function Calling = 学会"如何打电话"；MCP = 全球统一的"电话通信标准"，二者互补而非竞争。MCP 底层是 JSON-RPC 2.0，进程间走 stdio。

10.2.4 MCPClient 用法（基于 FastMCP 2.0）

from hello_agents.protocols import MCPClient
client = MCPClient(["python", "my_mcp_server.py"])        # stdio 方式连接本地脚本
async with client:                                         # 推荐写法，保证连接正确关闭
    tools  = await client.list_tools()                     # 每项含 name / description / inputSchema
    result = await client.call_tool("read_file", {"path": "my_README.md"})
    res    = await client.list_resources(); await client.read_resource(res[0]['uri'])
    ps     = await client.list_prompts();  await client.get_prompt("code_review", {"language": "python"})

• ⭐ 注意字段名是驼峰 inputSchema（不是 input_schema）。
• 安全调用范式：call_tool 一律用 try/except 包裹，失败后可重试 / 用默认值 / 向用户报告。
• GitHub 服务器示例：先设环境变量 GITHUB_PERSONAL_ACCESS_TOKEN，再传参 {"query":"AI agents language:python","page":1,"perPage":3}（perPage 驼峰）。

10.2.5 五种传输方式

特性：传输层无关（Transport Agnostic），MCPClient 支持五种。

方式	写法要点	适用场景
Memory	不传参数即内置演示服务器	单元测试、快速原型
Stdio	server_command=[...]	本地开发、调试、Python 脚本服务器
Stdio + Args	命令后追加参数（如 --debug）	需要开关的本地服务
Stdio（npx 社区服务器）	["npx","-y","@modelcontextprotocol/server-filesystem","."]	直接用社区现成服务器
HTTP / SSE / StreamableHTTP	MCPClient("http://...") 或指定 transport_type	生产环境、远程服务；SSE 用于实时流式；StreamableHTTP 用于双向流式

⭐ 重要限制：MCPTool 主要用于 Stdio 和 Memory；HTTP/SSE 等远程传输建议直接用底层 MCPClient。

10.2.6 在 Agent 中使用：自动展开机制 ⭐⭐

• 一个 MCPTool 加入 Agent，会自动把该 Server 的所有工具展开成独立注册的工具：内置 name="calculator" 展开为 6 个工具（calculator_add/subtract/multiply/divide/greet/get_system_info），Agent 侧调用格式 [TOOL_CALL:calculator_multiply:a=25,b=16]；文件系统 name="fs" 发现 14 个工具（fs_read_text_file / fs_write_file 等）。
• ⭐ 多 server 必须指定不同 name——name 会作为前缀拼在展开工具名上，防止冲突。
• 类型自动转换：Agent 生成字符串 "25"，系统转成 25.0 再发给 Server。
• 实战：多 Agent 智能文档助手：SimpleAgent("GitHub搜索专家") + MCPTool(name="gh", ...) → 结果交给 SimpleAgent("文档生成专家") + MCPTool(name="fs", ...) 生成报告，最后用 Python 原生 open() 落盘（刻意不用 MCP 写文件，用 os.path.getsize 校验字节数）。

10.2.7 生态与组合案例

三个资源库：Awesome MCP Servers（社区精选，按功能分类）、mcpservers.org（目录站，带搜索筛选）、modelcontextprotocol/servers（Anthropic 官方，质量最高）。

四个组合案例：① playwright MCP 自动化网页测试（开浏览器/填表/截图/报告）；② Obsidian + Perplexity 智能笔记；③ Jira + GitHub 项目管理自动化；④ YouTube + Notion + Spotify 内容创作流。

10.3 A2A 协议实战

10.3.1 动机与核心抽象

• MCP 解决 Agent↔工具，A2A 解决 Agent↔Agent（通信、委托、协商、状态同步）。
• ⭐ 传统中央协调器（星型拓扑）的三大问题：单点故障、性能瓶颈（所有通信过中心节点）、扩展困难（增删 Agent 要改中心逻辑）→ A2A 改用 P2P 网状拓扑。
• ⭐ 两个核心抽象：任务（Task）与工件（Artifact）——“这是它与 MCP 最大的区别”。
• 任务生命周期：创建 → 协商 → 代理 → 执行中 → 完成 / 失败。

• 请求生命周期四步：代理发现 → 身份验证 → send message API → send message streaming API。

注意：正文未展开 AgentCard 字段与 /.well-known/agent.json 路由（那是 ANP 的）。

10.3.2 HelloAgents 的实现

实现策略：现有 A2A 实现多为 Sample Code，故本章继承 A2A-SDK 部分功能、模拟协议思想；依赖是否可用用常量 A2A_AVAILABLE 探测，缺失提示 pip install a2a-sdk。

from hello_agents.protocols.a2a.implementation import A2AServer, A2A_AVAILABLE
calculator = A2AServer(name="calculator-agent", description="专业的数学计算智能体",
                       version="1.0.0",
                       capabilities={"math": ["addition", "..."], "advanced": ["power","sqrt","factorial"]})
@calculator.skill("add")          # 技能注册装饰器，技能存在 calculator.skills 字典
def add(query: str) -> str: ...
list(calculator.skills.keys())    # 查看所有技能

• ⭐ 安全计算范例：calculate 技能先用白名单 allowed_chars = set('0123456789+-*/(). ') 过滤再 eval（对照第七章的 AST 白名单，目的一致）。
• 起服务：threading.Thread(..., daemon=True) 后台跑 researcher.run(host="localhost", port=5000)；客户端 A2AClient("http://localhost:5000") → client.execute_skill("research", "...")，结果取 response.get('result')。
• 三 Agent 网络：researcher / writer / editor 分别在 5000 / 5001 / 5002，create_content(topic) 串行三步，每步用前缀 + 正则解析参数（f"research {topic}" 等）——这是本章 A2A 的简易消息约定。
• 封装成 Tool：A2ATool(name="researcher", agent_url="http://localhost:5000") 加进 SimpleAgent("协调者") 即可自然语言调度。
• 智能客服系统：tech_expert（6000）、sales_advisor（6001），接待员 SimpleAgent 负责"分析类型 → 转发专家 → 整理回答"。
• Agent 间协商：agent1（7000）的 propose 技能**deadline >= 7 天才接受**，否则返回反提案 {"counter_proposal":{"deadline":7}}；agent2（7001）的 negotiate 解析 negotiate task:... deadline:<数字>。

10.4 ANP 协议实战

10.4.1 目标与三大挑战

定位：解决大规模、开放网络环境下的智能体管理。三大挑战：服务发现（新任务如何找到能处理的 Agent）、智能路由（多候选时按负载/成本选最优）、动态扩展（新加入者如何被发现）。

10.4.2 三步架构 ⭐

1. 服务发现与匹配：发现服务预先爬取各 Agent 暴露的标准端点 .well-known/agent-descriptions 建立索引，按语义/功能描述动态匹配。
2. 基于 DID 的身份验证：Agent A 用私钥对含自身 DID 的请求签名，Agent B 解析该 DID 取回公钥验证签名。（DID = 去中心化身份标识符，即"自己掌握密钥、不依赖中心机构颁发的身份证"。）
3. 标准化服务执行：验证通过后按预定义接口与数据格式调用。

总结句：用 DID 构建去中心化的信任根基，借标准化描述协议实现服务动态发现，无需中央协调即可形成协作网络。

10.4.3 HelloAgents 的实现

register_service(discovery=discovery, service_id="nlp_agent_1", service_name="NLP处理专家A",
                 service_type="nlp", capabilities=["text_analysis","sentiment_analysis","ner"],
                 endpoint="http://localhost:8001",
                 metadata={"load": 0.3, "price": 0.01, "version": "1.0.0"})
services     = discover_service(discovery, service_type="nlp")
best_service = min(services, key=lambda s: s.metadata.get("load", 1.0))  # 按负载选最低，默认值 1.0 是防御写法
# ANPNetwork(network_id="ai_cluster") 还可组网：add_node / connect_nodes / get_network_stats

• 分布式任务调度：注册 10 个 compute_node_{i}（metadata 含 load / cpu_cores / memory_gb / gpu），调度器 = SimpleAgent + ANPTool(name="service_discovery", ...)。
• 负载均衡：注册 5 个 api_server_{i}，get_best_server() 用 min(..., key=load) 选点，每次请求后 metadata["load"] += 0.1 更新负载。

10.5 构建自定义 MCP 服务器 ⭐⭐⭐（本章重头戏）

10.5.1 为什么自建 Server

四点动机：封装业务逻辑（内部流程标准化为 MCP 工具）、访问私有数据（安全代理内部数据库/API，不暴露公网）、性能专项优化（高频/低延迟）、功能定制扩展（专有算法、特定硬件）。

10.5.2 天气查询 Server 完整骨架

from hello_agents.protocols import MCPServer
weather_server = MCPServer(name="weather-server", description="真实天气查询服务")
weather_server.add_tool(get_weather)          # ⭐ 用 add_tool 注册，官方 SDK 才用装饰器
weather_server.add_tool(list_supported_cities)
weather_server.add_tool(get_server_info)
if __name__ == "__main__":
    weather_server.run()

五个实现要点 ⭐：

1. 工具就是普通带类型注解的函数：def get_weather(city: str) -> str，schema 由框架依据函数签名 + docstring 自动生成（呼应第七章 @tool 装饰器机制）。
2. 统一返回 JSON 字符串：json.dumps(..., ensure_ascii=False, indent=2)（ensure_ascii=False 保住中文可读性）。
3. ⭐ 错误要"返回"而不是"抛出"：except Exception as e: return json.dumps({"error": str(e), "city": city}, ensure_ascii=False)——本章事实上的错误处理最佳实践（呼应第七章"错误以字符串回灌 LLM"）。
4. 外部依赖必须有超时：requests.get(f"https://wttr.in/{city_en}?format=j1", timeout=10) + raise_for_status()。
5. 单位与格式归一：风速 windspeedKmph 除以 3.6 并 round(...,1) 转成 m/s；中文城市经 CITY_MAP 映射为英文名；时间戳统一格式。

本章不使用 @app.call_tool() / @app.list_tools() 装饰器（属于官方 SDK / Smithery 场景），也没有 MCP Inspector 调试章节。

测试与接入：

• 测试脚本：MCPClient(["python", server_script]) → call_tool("get_server_info", {})，用 json.loads 取 name/version；其余以 "error" not in weather 判定成功。
• 接入 Agent：MCPTool(server_command=["python", server_script]) → SimpleAgent("天气助手")，展开为 3 个工具（默认前缀 mcp_）。
• ⭐ 每次调用都是一次短连接：日志固定走完"🔗 连接 → ✅ 成功 → 执行 → 🔌 断开"（长期任务应考虑底层长连接客户端）。

10.5.3 发布到 Smithery

Smithery = MCP 服务器的官方发布平台（类比 PyPI / npm）：发现搜索、一键安装、统计评价、自动更新。

标准目录：README.md、LICENSE、Dockerfile（推荐）、pyproject.toml（必需）、requirements.txt、smithery.yaml（必需）、server.py。

文件	关键字段/要点
smithery.yaml	name: weather-mcp-server（唯一标识，小写连字符）、displayName、description、version、author、license: MIT、categories、runtime: container、build: {dockerfile, dockerBuildPath}、startCommand: {type: http}、tools: 列表逐条列 name + description
pyproject.toml	[build-system] requires = ["setuptools>=61.0","wheel"]；requires-python = ">=3.10"；dependencies = ["hello-agents>=0.2.1","requests>=2.31.0"]；[tool.setuptools] py-modules = ["server"]
Dockerfile	基础镜像 python:3.12-slim-bookworm；WORKDIR /app；apt 安装后 rm -rf /var/lib/apt/lists/* 清缓存；pip install --no-cache-dir；ENV PORT=8081；EXPOSE 8081（Smithery 标准端口）；HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3；CMD ["python","server.py"]

发布三步：Fork 源码 → 在自己 GitHub 建 weather-mcp-server 仓库 → 到 smithery.ai 用 GitHub 登录、点 Publish Server 填仓库 URL。成功页显示唯一标识符（形如 @jjyaoao/weather-mcp-server）与 Tools / Connect 区（多语言配置片段）。

10.5.4 发布后的三种消费方式

1. Smithery CLI：npm install -g @smithery/cli → smithery install weather-mcp-server
2. Claude Desktop（本章唯一给出的客户端配置示例）：

{ "mcpServers": { "weather": { "command": "smithery", "args": ["run", "weather-mcp-server"] } } }

3. HelloAgents：MCPTool(server_command=["smithery","run","weather-mcp-server"])

⭐ 面试级结论：同一个 Server 能被 HelloAgents 客户端与第三方客户端（Claude Desktop 等）同时调用，这就是协议解耦的直接证据。

第十章小结

本章解决"能力如何被复用"：单体 Agent 受工具集成、能力扩展、协作三重限制；协议像 TCP/IP 一样统一访问接口，换来标准化、互操作、动态发现、可扩展四点改变。

三种协议按规模递进（建议直接背）：MCP（Anthropic，上下文共享，对接工具，生态最成熟）→ A2A（Google，P2P 对等通信，核心抽象 Task 与 Artifact，小规模协作）→ ANP（社区，DID 去中心化身份 + .well-known/agent-descriptions 服务发现，大规模开放网络，尚无成熟生态）。HelloAgents 统一压成三层、继承 BaseTool，三种 Tool 可无缝混用，Agent 不感知协议细节。

实战记住两件事：① MCP 与 Function Calling 互补而非竞争（会不会打电话 vs 全球通话标准），工具描述质量决定调用正确率；② 能自建 MCP Server——MCPServer + add_tool、统一返回 JSON、错误返回而非抛出、外部请求必设超时，Docker 化（EXPOSE 8081）发到 Smithery 后可被多种客户端同时调用。经验：优先用成熟社区服务；小规模用 A2A，大规模用 ANP。

---

第十一章 Agentic-RL

本章定位：全书唯一触及训练侧的章节，只需记住"为什么、怎么做、关键数值"。

11.1 从 LLM 训练到 Agentic RL

11.1.1 为什么需要强化学习

监督学习的三个局限：数据质量决定上限、缺乏探索、难优化长期目标（中间过程无法精确优化）。

训练脉络：预训练（Causal LM / Next Token Prediction，自监督，TB 级文本）→ RLHF 三阶段 → Agentic RL。

RLHF 阶段	做什么	要点
SFT（监督微调）	(prompt, completion) 对	数据量小、需人工标注、见效快，学的是任务格式与基本能力
RM（奖励模型）	偏好对比 chosen/rejected	用 sigmoid 目标让好回答得分更高
PPO（策略优化）	最大化 RM 奖励	⭐ 同时用 **KL 散度惩罚（系数 β）**约束不偏离参考策略——“最大化奖励，但别走太远”（ref 常取 SFT 模型）

RLHF 成本高 → RLAIF：用强 AI 替代人工标注，效果接近甚至超过 RLHF。

11.1.2 Agentic RL 的本质 ⭐

Agentic RL：把 LLM 作为可学习策略嵌入"感知—决策—执行"循环。特点：多步交互、行动改变环境、每步可得反馈、优化长期累积奖励而非单步。

对照表——传统后训练称 PBRFT：

MDP 要素	PBRFT	Agentic RL
状态	s_0 = prompt，T=1 单步不变	s_t = (prompt, o_1..o_t)，T ≫ 1 且随行动演化
行动	仅文本生成	文本 + 工具调用 + 环境操作
转移	无转移，直达终态	`P(s_{t+1}
奖励	仅终局单步	R = Σ γ^t r(s_t, a_t)，γ∈[0,1]，稀疏/密集/混合
目标	单步期望奖励	轨迹 τ 上的累积折扣奖励

• 累积奖励示例：GitHub 仓库分析——取仓库 +0.1、读文件 +0.1、分析 +0.2、出报告 +0.6 = 1.0，说明中间步骤也有部分分，不必等最终答案。
• 思维转变：PBRFT 问"怎样让单个回答更好"；Agentic RL 问"怎样完成任务"，允许走看似"绕路"的中间步骤。
• 六大 trained 能力：推理 / 工具使用 / 记忆 / 规划 / 自我改进 / 感知。

11.1.3 技术栈

• TRL + Qwen3-0.6B（0.6B 适合普通 GPU）；安装 pip install "hello-agents[rl]==0.2.5"。
• 四层：数据集层 → 奖励函数层（MathRewardFunction 基类 + 三种内置奖励）→ Trainer 层（SFTTrainerWrapper / GRPOTrainerWrapper，带 LoRA）→ 统一接口 RLTrainingTool（train / load_dataset / create_reward / evaluate）。
• ⭐ GRPO 的坑：batch_size 必须能被 num_generations 整除（示例 num_generations=8，故 batch 取 2）。

11.2 数据集与奖励函数（核心）

11.2.1 为什么选 GSM8K

选它的三个理由：答案明确可自动评估（不需要奖励模型）、需 2–8 步多步推理、能力可迁移。

• 规模：train 7,473 / test 1,319（小学 2–8 年级应用题）；标记 <<48/2=24>> 表示中间算式，#### 72 表示最终答案。
• 三种格式：原始（question + answer 含过程）；SFT 格式（对话模板 + 完整解题，含 Step 1、Final Answer: 72）；RL 格式（prompt + ground_truth 只给最终答案，不提供解题过程，迫使自主推理）。

11.2.2 三类内置奖励 ⭐

奖励	公式	取值与示例
AccuracyReward	二值：正确 1 / 错误 0	72 → 1.0；72.0 → 1.0（数值精度容错）；73 → 0.0。稀疏，区分不了"接近正确"
LengthPenaltyReward	r_acc − α·max(0, l − l_target)，仅答对才惩罚	α 默认 0.001，max_length=1024；目标 200、实际 500 → 1 − 0.001×300 = 0.700；答错一律 0
StepReward	r_acc + β·s，仅答对才加	每步 +0.1；0 步 → 1.00、2 步 → 1.20、5 步 → 1.50；答错即使有 5 步也是 0

组合方式：三者可叠加，形如 r_acc − α·max(0,l−l_target) + β·s；示例：1.200 = 准确率 1.0 − 长度惩罚 0.100 + 步骤奖励 0.3。

⭐ create_reward 只支持单一类型，组合需在训练配置的 reward_fn / reward_config 里指定。

自定义奖励签名：f(completions: List[str], **kwargs) -> List[float]，kwargs 含 ground_truth 列表，返回值裁剪到 0.0–1.0。示例分级：误差 <0.01 → 1.0，<1.0 → 0.8，<5.0 → 0.5，含步骤再 +0.1。

好奖励 vs 坏奖励的判据：

• 好：能定义成功、提供梯度信号、方差可控、易调整组合。
• 坏：只有终局奖励、可被奖励欺骗（reward hacking）、多目标冲突、方差过大不收敛。

11.3 SFT 训练

11.3.1 为什么必须先 SFT

预训练模型只会"续写"：输出自由文本、无结构化标记 → 抽不出答案 → 算不了奖励。SFT 教四件事：输出格式、推理模式、能力基线、缩小 RL 探索空间。

对比示例：base 模型输出啰嗦无结论；SFT 后输出 Step 1 / Step 2 / Final Answer: 72。

11.3.2 LoRA 原理与超参 ⭐

LoRA（Low-Rank Adaptation）：冻结原权重 W，只训练两个低秩小矩阵 B、A（ΔW = BA），前向变成 h = Wx + BAx。可理解为在原模型旁边挂一个很小的"补丁"，只改补丁不改原版。

• 参数量从 d×k 降到 r(d+k)：以 d=k=4096、r=8 为例，16,777,216 → 65,536，减少 256 倍。
• rank：典型 4–64，默认 8；alpha：缩放因子，实际更新按 α/r 缩放，实践常取 2×rank（rank 8 → alpha 16、rank 16 → alpha 32）。
• target_modules：常用 q/k/v/o_proj，可扩展到 gate/up/down_proj；优势：省显存、快、易部署、防过拟合，代价：通常略逊于全量微调。

11.3.3 配置与调参口径

配置	基础版	完整版
max_samples	100	None（7,473）
epochs / batch / lr	3 / 4 / 5e-5	3 / 8 / 5e-5（LoRA 可稍大至 1e-4）
LoRA	rank 8 / alpha 16	rank 16 / alpha 32；warmup_ratio=0.1、weight_decay=0.01
其他	—	save_steps=500、logging_steps=100、eval_steps=500

调参口径：epoch 从 3 轮起（<1–2 欠拟合、>10 过拟合）；batch_size 按显存选：4GB → 1–2、8GB → 4–8、16GB → 8–16；rank 4–8 小任务、16–32 复杂、64 大规模。

排障：loss 不降 → lr 太小或数据有错；先降后升 → lr 太大或过拟合；⭐ grad norm 合理区间 0.1–10（>100 梯度爆炸降 lr，<0.01 梯度消失查配置）；OOM → 减 batch / max_length / 梯度累积。

11.3.4 结果结论

⭐ Qwen3-0.6B 在 GSM8K 上：SFT 后 40–50% 属正常，RL 后可到 60–70%。这是本章唯一可引用的端到端量化收益。

11.4 GRPO 训练

11.4.1 GRPO 相对 PPO 省掉了什么 ⭐⭐

PPO 的三个痛点：要训练 Value Model（额外显存 + 复杂度）、需同时维护 4 个模型（Policy / Reference / Value / Reward）、易奖励崩塌与策略退化。

GRPO（Group Relative Policy Optimization）的做法：

• ⭐ 去掉 Value / Critic 网络，改用一组采样答案的组内相对优势 r − r̄_group 当基线（同一题采样多个答案，取组内均值）。
• 只保留 Policy + Reference 两个模型，保留 KL 惩罚项 −β·D_KL(π_θ ‖ π_ref)。
• 收益：流程简化、组内相对比较降低方差、KL 防止跑偏、显存更低。

数值示例：某题采样 4 个答案，奖励 [1.0, 1.0, 0.0, 0.8]，均值 0.7，相对奖励 [0.3, 0.3, −0.7, 0.1] → 提升前两个、压制第三个。鼓励的是"优于组内平均"，而不是追求绝对高分。

11.4.2 关键超参

参数	建议值	示例
num_generations	每题采样数，典型 4–8	4
max_new_tokens	256–512	512
temperature	0.7–1.0（保探索）	0.8
learning_rate	比 SFT 小，1e-5–5e-5	1e-5
kl_coef	0.05–0.1（0.01 太松会跑偏，0.5 太紧限制学习）	0.05
clip_range	0.2	0.2
LoRA	—	rank 16 / alpha 32

组合奖励配置示例：accuracy(weight 1.0) + length_penalty(weight 0.5, target_length 200) + step(weight 0.3, step_bonus 0.1)。

11.4.3 监控与排障

• ⭐ KL 合理区间 0.01–0.1：>0.5 偏离太远（增大 kl_coef 或降 lr）；<0.001 几乎没更新（减小 kl_coef 或增大 lr）。
• 工具：wandb（train/reward、train/kl 等）、TensorBoard、离线日志。
• 三类排障：奖励不升 → 升 lr / 降 kl / 查奖励与 SFT 质量；KL 爆炸 → 降 lr / 升 kl / 加梯度裁剪；生成质量下降（准确率升但格式乱）→ 用组合奖励、增大 kl_coef、减 epoch 或加数据。
• 代价：GRPO 显存高于 SFT（多答案生成 + 参考模型输出）。OOM 缓解：降 num_generations / batch_size / max_new_tokens，或梯度检查点 + 混合精度。

11.5 评估与分析

指标体系：

• 准确性：Accuracy、Accuracy@K（采样 K 个有一个对即算对）、MAE（区分"接近正确"）。
• 效率：平均长度（token）、推理步骤数（适当 2–5 步）、推理时间。
• 质量：格式正确率（含 Step 1 / Final Answer）、连贯性、可解释性。

评估调用：action="evaluate"，metrics 可选 accuracy / accuracy_at_k / average_length / average_steps / format_correctness；三模型同条件对比（max_samples=200）。

⭐ 错误分析（200 样本，总错误 76）：
计算错误 42.1% > 理解错误 28.9% > 推理错误 23.7% > 格式错误 5.3%。
结论：主要短板是数值计算能力；格式错误少说明 SFT 效果良好。

⭐ 按难度分层：简单（1–2 步）78.50%（85 题）、中等（3–4 步）58.30%（96 题）、困难（5+ 步）31.60%（19 题）→ 步数越多准确率越低，长程多步推理仍是核心瓶颈。

11.6 完整流程与工程化

• 六阶段流水线：数据准备 → SFT 训练 → SFT 评估 → GRPO 训练 → GRPO 评估 → 保存/部署。实现类 AgenticRLPipeline（stage1_prepare_data … stage6_save_results），由 config.json 驱动。

• config 关键项：base_model=Qwen/Qwen3-0.6B、max_samples=1000、sft {epochs:3, batch:8}、grpo {epochs:3, batch:4}、eval {max_samples:200, sft_accuracy_threshold:0.40}。
• 运行建议：先用 100–1000 样本跑通流程再放大；先做数据质量检查（必备字段、空值、重复）。
• 超参调优：网格搜索（全面但贵）、随机搜索、贝叶斯优化（Optuna）。
• 分布式：单机多卡 → DDP；>7B → DeepSpeed ZeRO-2/3。⭐ accelerate 写好 yaml 后 accelerate launch --config_file 即可，训练脚本无需改动。
• 最佳实践：总 batch = per_device_batch × GPU 数 × 梯度累积；学习率按 lr_new = lr_base × sqrt(new_batch / base_batch) 缩放。
• 部署：LoRA 合并（merge_and_unload）；8-bit 量化推理（load_in_8bit=True）；FastAPI 暴露 POST /generate。

第十一章小结

主线：提示词工程到顶之后，靠强化学习提升策略本身。监督学习有三局限（数据上限、缺乏探索、难优化长期目标）；RLHF 三阶段（SFT 学格式 → RM 学偏好 → PPO 优化 + KL 惩罚防跑偏）之后，Agentic RL 把 LLM 当作可学习策略放进感知—决策—执行循环：状态变历史序列、行动含工具与环境操作、奖励变轨迹累积折扣。

落地最小闭环：GSM8K + Qwen3-0.6B + TRL + LoRA，先 SFT 教会 Step 1 / Final Answer 可解析格式（否则抽不出答案、算不了奖励），再用 GRPO 提升。三个必记点：GRPO 去掉 Value/Critic，用组内相对优势 r − r̄ 当基线，只留 Policy + Reference（省显存、降方差）；三类奖励（准确率二值稀疏、长度惩罚 α=0.001 只罚答对的、步骤奖励每步 +0.1 只奖答对的）可组合；结果 SFT 40–50% → RL 60–70%，短板在数值计算（42.1%），步数越多准确率越低（78.5→58.3→31.6%）。无 GPU 就只读 11.1 + 奖励设计 + 评估指标三块。

---

第十二章 智能体性能评估（重点）

12.1 评估基础

12.1.1 为什么评估

三个必须回答的问题：① 是否具备预期能力；② 在不同任务上表现如何；③ 与其他智能体相比处于什么水平。核心价值：把"优化提示词 / 换 LLM 后是否真的改进""部署前可靠性如何"变成可量化的数字，客观比较方案、发现弱点、向用户证明可靠性。

⭐ 三大挑战：

1. 输出的不确定性：同题可能有多个正确答案，难以简单判对错。
2. 评估标准的多样性：工具调用要检查函数签名，问答任务要评估语义相似度。
3. 评估成本的高昂：需大量 API 调用，成本可能达到数百元甚至更多。

→ 应对：标准化 Benchmark（统一数据集 + 评估指标 + 评分方法）。

12.1.2 主流基准概览

A. 工具调用能力

基准	提出方	规模 / 定位	考察点
BFCL（Berkeley Function Calling Leaderboard）	UC Berkeley	1120+ 样本，simple / multiple / parallel / irrelevance 四类，AST 匹配	函数调用正确性；规模适中、社区活跃
ToolBench	清华大学	16000+ 真实 API 调用场景	真实世界复杂工具使用
API-Bank	Microsoft Research	53 个常用 API 工具	对 API 文档的理解与调用

B. 通用能力

基准	提出方	规模 / 定位	考察点
GAIA（General AI Assistants）	Meta AI + Hugging Face 联合	466 个真实世界问题，分 Level 1/2/3，用准精确匹配	多步推理、工具使用、文件处理、网页浏览
AgentBench	清华大学	8 个不同领域的任务	智能体通用能力
WebArena	CMU	真实网页环境	网页任务完成与交互

C. 多智能体协作：ChatEval（对话系统质量）、SOTOPIA（社交场景互动）、自定义协作场景。

12.1.3 评估指标四分类

• 准确性指标：Accuracy、Exact Match、F1 Score
• 效率指标：Response Time、Token Usage
• 鲁棒性指标：Error Rate、Failure Recovery
• 协作指标：Communication Efficiency、Task Completion

12.1.4 HelloAgents 评估体系与环境准备

本章三大场景：BFCL（工具调用）、GAIA（通用能力，任务真实、难度分级）、数据生成质量（AIME 风格数学题，LLM Judge + Win Rate + 人工验证）。

hello_agents/
├── evaluation/benchmarks/{bfcl, gaia, data_generation}/
│     # 各含 dataset.py + evaluator.py + metrics.py（+ ast_matcher / quasi_exact_match / AIME加载器 / llm_judge / win_rate）
└── tools/builtin/   # bfcl_evaluation_tool / gaia_evaluation_tool / llm_judge_tool / win_rate_tool

环境与坑（硬参数）：

• pip install "hello-agents[evaluation]==0.2.7"
• export HF_TOKEN="your_huggingface_token"（GAIA 是受限数据集，必须申请 Token）
• ⭐ 依赖冲突：官方包 bfcl-eval 强制要求 numpy<=2.0.0，需单独安装：pip install "numpy==1.26.4" bfcl-eval

12.2 BFCL：工具调用能力评估 ⭐

12.2.1 基准概览

BFCL（Berkeley Function Calling Leaderboard）：加州大学伯克利分校推出的工具调用能力榜单，当前走 BFCL v4 数据文件（如 BFCL_v4_simple_python.json）。

四个类别（难度递增）：Simple（单函数调用）→ Multiple（调用多个函数）→ Parallel（并行调用多个）→ Irrelevance（判断是否真需要调用函数）。

工具调用的四件事：理解需求 → 选工具 → 构造调用（函数名 + 参数）→ 处理复杂场景（多函数 / 并行）。

评估流程：加载数据集 → 选类别 → 跑智能体得预测 → 解析为 AST → 匹配判定 → 遍历样本 → 算准确率并生成报告。

样本结构：question（自然语言请求）、function（可用函数列表，含签名与描述）、ground_truth（期望调用）。

12.2.2 AST 匹配 ⭐⭐

AST（抽象语法树）：把代码解析成树形结构；用在工具调用比对上，即不看字面写法、只看结构是否等价，比字符串匹配鲁棒得多。

树等价三条件：① 函数名完全一致（精确匹配）；② 参数键值对集合相等（忽略顺序）；③ 参数值语义等价（如 2+3 ≡ 5）。

容忍规则一览：

情况	判定
参数顺序不同 f(a=1,b=2) vs f(b=2,a=1)	✅ 匹配
等价表达式 calculate(x=2+3) vs calculate(x=5)	✅ 匹配
字符串引号差异 f(s="hello") vs f(s='hello')	✅ 匹配
函数名错误 get_temperature vs get_weather	❌ 不匹配
参数值错误 Shanghai vs Beijing	❌ 不匹配
多函数调用	要求数量相同、每个都匹配、顺序可不同（集合匹配）

12.2.3 五个评估指标

12.2.4 数据获取与加载

• 方法 1（推荐）：git clone https://github.com/ShishirPatil/gorilla.git temp_gorilla，数据目录 temp_gorilla/berkeley-function-call-leaderboard/bfcl_eval/data/，ground truth 在 bfcl_eval/data/possible_answer/。理由：含完整 ground truth、格式与官方一致、支持 BFCL v4。
• 方法 2：BFCLDataset(bfcl_data_dir="...", category="simple_python") → dataset.load()（先加载测试数据 → 再加载 ground truth → 自动合并）。
• 实测输出：✅ 加载了 400 个测试样本、✅ 加载了 400 个 ground truth。

12.2.5 三种使用方式

方式 1：BFCLEvaluationTool（推荐，一行代码）

bfcl_tool = BFCLEvaluationTool()
results = bfcl_tool.run(agent=agent, category="simple_python", max_samples=5)  # max_samples=0 表示全部
print(results['overall_accuracy'], results['correct_samples'], results['total_samples'])

方式 2：命令行脚本（批量 / CI/CD）

python chapter12/04_run_bfcl_evaluation.py --category simple_python --samples 10   # 0 表示全部

参数：--category（默认 simple_python）、--samples（默认 5，0 = 全部）、--model-name（默认 Qwen/Qwen3-8B）。

方式 3：BFCLDataset + BFCLEvaluator（最大灵活度）

evaluator = BFCLEvaluator(dataset=dataset, category="simple_python", evaluation_mode="ast")
results = evaluator.evaluate(agent, max_samples=10)
evaluator.export_to_bfcl_format(results, output_path="./evaluation_results/my_results.json")

12.2.6 官方评估集成与实测数据

四步流程：加载 BFCL v4 数据 → 跑出预测 → 导出官方格式 JSONL → 用官方脚本算分（与排行榜一致）。run_official_eval 默认 True，可指定 model_name。

实测数字（全部可引用）：

• 数据集：样本数 400、Ground truth 数 400
• HelloAgents 评估：总体准确率 100.00%，simple_python: 100.00% (5/5)
• 导出 ./evaluation_results/bfcl_official/BFCL_v4_simple_python_result.json 后用官方脚本 bfcl evaluate --model Qwen/Qwen3-8B --test-category simple_python --partial-eval 算分
• 官方汇总行：Model,Overall Acc,simple_python / Qwen/Qwen3-8B,100.00,100.00；自动生成 Markdown 评估报告

报告模板结构：评估概览（智能体/类别/准确率/正确数）→ 详细指标 → 样本详情表（逐条预测 vs 答案）→ 准确率 ASCII 条（██… 100.00%）→ 建议（≥90%：“✅ 表现优秀”）。

12.2.7 局限性与提升方向

三条局限：① 只是 SimpleAgent 的简单复现；② 自定义格式 [TOOL_CALL:tool_name:parameters] 需 LLM 主动学习，复杂场景下不如原生 Function Calling；③ 只测过 simple_python，multiple / parallel / irrelevance 未针对性优化。

四条提升方向：① 优化工具调用能力（换原生 FC 模型 / 改进提示词）；② 扩展工具库；③ ⭐ 按类别设计策略——multiple 要规划多步调用序列，parallel 要识别可并行调用，irrelevance 要判断是否真的需要调用工具；④ 用官方工具验证对齐排行榜。

三条实践策略：

1. 渐进式评估：5 → 50 → 0(全部)，⭐ 每档以 overall_accuracy > 0.8 为晋级阈值
2. 多类别评估：categories = ["simple_python","multiple","parallel","irrelevance"]，每类 10 样本
3. 对比评估：默认 vs 优化提示词——这就是 Day 13"每次只改一个变量"的方法论来源

提交排行榜三步：准备材料（模型描述文档、所有类别的评估结果、模型访问方式）→ 向 https://github.com/ShishirPatil/gorilla 提 PR → 等待团队审核验证。

12.3 GAIA：通用 AI 助手能力评估 ⭐

12.3.1 基准概览

GAIA（General AI Assistants）：Meta AI 与 Hugging Face 联合推出。与 BFCL 专注工具调用不同，它评估真实世界任务中的综合表现。

五项核心能力：多步推理（拆解子问题）、知识运用（内置 + 外部知识库）、多模态理解（文本/图片/文件）、网页浏览、文件操作。数据集：466 个真实世界问题，按复杂度与推理步数分 Level 1/2/3（从零步到多步复杂推理）。

样本结构：Question、Level(1-3)、Final answer（数字/文本/文件）、file_name/file_path（附件）、Annotator Metadata（推理步骤、Number of steps、所需工具等）。

12.3.2 数据获取（GAIA 是受限数据集）⭐

1. 到 https://huggingface.co/datasets/gaia-benchmark/GAIA 点 Request access（通常几秒内批准，Token 在 HF 设置页申请）。
2. .env 写 HF_TOKEN=hf_your_token_here。
3. 自动下载（推荐）：GAIADataset(dataset_name="gaia-benchmark/GAIA", split="validation", level=1) → 输出 加载了 53 个测试样本 (Level 1)；内部用 snapshot_download（数据集含 114 个文件：题目、图片、PDF 等）。
4. 手动下载：snapshot_download(repo_id="gaia-benchmark/GAIA", repo_type="dataset", local_dir="./data/gaia", token=...)。
5. 目录结构：validation/metadata.jsonl（165 题）+ test/metadata.jsonl（301 题）= 466，与总题数吻合；get_statistics() → validation 级别分布 {1: 53, 2: 62, 3: 50}。

12.3.3 准精确匹配 Quasi Exact Match ⭐⭐

核心思想：先归一化，再精确匹配。 定义：Quasi_Exact_Match(A_pred, A_true) = 1 if N(A_pred) = N(A_true) else 0，N(·) 按答案类型施加不同规则。

答案类型	归一化规则	示例
数字	去逗号分隔符、去单位符号（$、%）	"$1,234.56" → "1234.56"
字符串	转小写、去冠词（the/a/an）、去多余空格、去末尾标点	"The United States" → "united states"
列表	按逗号切分 → 逐元素归一化 → 按字母序排序 → 重新连接	"Paris, London, Berlin" → "berlin, london, paris"

12.3.4 指标与完整算例

1. Exact Match Rate（GAIA 核心指标） = (1/N)·Σᵢ Quasi_Exact_Match(...)
2. Level-wise Accuracy = (1/|D_ℓ|)·Σ_{i∈D_ℓ} Quasi_Exact_Match(...)，ℓ ∈ {1,2,3}
3. ⭐ Drop Rate（难度递进下降率） = (Accuracy_ℓ − Accuracy_{ℓ+1}) / Accuracy_ℓ，特指 Drop_{1→2} 与 Drop_{2→3}
4. Avg Steps（平均推理步骤数） = (1/N_correct)·Σ_{i∈Correct} steps_i

10 样本算例（全套数字，务必记住推导过程）：

• total=10、correct=7（第 1,2,3,5,6,8,9 题）→ exact_match_rate = 0.70
• Level1 = 3/3 = 1.00；Level2 = 2/3 = 0.67；Level3 = 2/4 = 0.50
• Drop 1→2 = (1.00−0.67)/1.00 = 0.33；Drop 2→3 = (0.67−0.50)/0.67 = 0.25
• 打印值：70.00% / 100.00% / 66.67% / 50.00% / 33.00% / 25.00%
• 结论：整体 70% 良好；1→2 降 33%，中等难度衰减明显；Level 3 仅 50%，仍有提升空间。

指标读法：Drop Rate = 0.3 → 难度上升导致准确率下降 30%；= 0.0 → 不受难度影响（理想）。

12.3.5 官方系统提示词 ⭐

必须使用 GAIA_SYSTEM_PROMPT，关键约束（第 3 章"格式规约"原则的最佳范例）：

• 结尾必须写成 FINAL ANSWER: [YOUR FINAL ANSWER]；
• 答案应是一个数字、尽可能少的词、或逗号分隔的数字/字符串列表；
• 数字不带逗号分隔符与 $/% 等单位符号；字符串不用冠词、不用缩写；列表按元素类型套用上述规则。

12.3.6 使用方式与实测数据

方式 1：GAIAEvaluationTool 一键评估（注意必须注入官方提示词）：

agent = SimpleAgent(name="TestAgent", llm=llm, system_prompt=GAIA_SYSTEM_PROMPT)   # ⭐ 关键
results = gaia_tool.run(agent=agent, level=1, max_samples=5,
                        export_results=True, generate_report=True)

方式 2：GAIADataset + GAIAEvaluator（深度定制，可导出 JSONL 提交榜单）。

实测数字：

• 下载后 ✓ 加载了 165 个样本 → validation / Level 1 / 样本数 53
• 一次运行：精确匹配率 80.00%、部分匹配率 80.00%、正确数 4/5
• 报告样例（另一次运行）：总样本 2、精确匹配率 50.00%；失败样本预测 24000 vs 答案 17 ❌，成功样本 3 vs 3 ✅
• 三类产物：JSONL 结果（可直接提交排行榜）、提交说明、评估报告（摘要 + 详细指标 + 样本详情 + 可视化）

⭐ 原文提醒：结果不理想属正常现象——Level 1 也需搜索引擎、计算器等工具能力；当前 SimpleAgent 主要用于演示流程，工具调用还有明显提升空间。

12.3.7 核心组件实现要点

• GAIADataset：load() 先从 HF 下载再按 level 过滤，支持多模态（文本、附件文件、图片）。
• GAIAEvaluator.evaluate() 五步：_build_prompt() → agent.run() → _extract_answer()（正则抓 FINAL ANSWER:）→ _normalize_answer() 双侧归一化 → 比较。
• ⭐ _normalize_answer：含逗号则切分 → 逐项归一化 → parts.sort()（GAIA 要求按字母序） → ','.join；单答案处理依次为 strip + lower → 去首冠词 ['the','a','an'] → 去 $ % € £ → re.sub(r'(\d),(\d)', r'\1\2') 去数字逗号 → 压缩空格 → rstrip('.,;:!?')。
• _extract_answer 兜底策略：首选 r'FINAL ANSWER:\s*(.+?)(?:\n|$)'，备选中英文模式，最终兜底返回最后一个非空且不以 # 开头的行。
• GAIAEvaluationTool 的报告模板：评估概览 → 详细指标（分级准确率）→ 样本详情（前 10 个） → 可视化 → 建议（<50% 提示检查工具使用与多步推理）。

提交到排行榜：JSONL 每行 {"task_id":"xxx","model_answer":"答案","reasoning_trace":"推理过程"}；榜单地址 https://huggingface.co/spaces/gaia-benchmark/leaderboard。

12.4 数据生成质量评估 ⭐

12.4.1 场景设定

AIME：美国数学协会（MAA）主办，难度介于 AMC 10/12 与 USAMO 之间，答案为 0–999 的整数，覆盖代数、几何、数论、组合、概率，需多步推理但不涉高深理论，相当于 AIME 第 6–9 题水平。

选它的理由：答案格式统一便于自动评估、难度适中。参考数据集 TianHongZXY/aime-1983-2025（实测加载 963 道）。

三种互补方法：LLM Judge（题目质量的绝对多维评分）+ Win Rate（与真题的相对对比）+ 人工打分（最终把关）。分工逻辑：前两者评"题目生成质量"，人工评"答案生成质量"。

12.4.2 LLM Judge

LLM-as-a-Judge：用 LLM 当评委给生成内容打分，替代昂贵的人工评估，实现快速、一致的多维评分，还能给出评分理由与改进建议。

四个评分维度（每项 1–5 分）：正确性 Correctness（数学逻辑与答案）、清晰度 Clarity（表述与解答是否易懂）、难度匹配 Difficulty Match（是否符合 AIME 中等偏难标准）、完整性 Completeness（解答步骤是否完整）。

三个汇总指标：

• Average Score = (1/N)·Σᵢ ( Σ_{d=1}^{4} S_{i,d} / 4 )——先算每题四维均值，再对全体求均
• Pass Rate = |{i : Score_i ≥ 3.5}| / N——及格阈值 3.5
• Excellent Rate = |{i : Score_i ≥ 4.5}| / N——优秀阈值 4.5

三者分工：平均分看整体、及格率保质量、优秀率看占比。

Prompt 写法要点：给 题目 / 答案 / 解答 三段上下文 → 逐条描述四个维度的判断标准 → ⭐ 强制 JSON 输出（correctness / clarity / difficulty_match / completeness / comments）。默认评审模型 judge_model="gpt-4o"。

实测结果：平均总分 4.2/5.0、通过率 85.0%、优秀率 40.0%；分维度：正确性 4.3、清晰度 4.1、难度匹配 4.0、完整性 4.4。

12.4.3 Win Rate 成对比较

动机：LLM Judge 给绝对分，还需要相对指标衡量生成题与真题的差距；成对对比更符合人类判断习惯。

三种结果：Win（生成题更好）/ Loss（真题更好）/ Tie（质量相当）。

公式：Win Rate = Wins / Total Comparisons，同理 Loss Rate 与 Tie Rate，⭐ 三者之和 = 100%。

判读：⭐ 理想值 ≈ 50%（双方各有五成胜率）；显著低于 50% → 生成质量不如真题，需优化；显著高于 50% → 可能确有超越，也可能是评估标准存在偏差。

实测结果：20 次比较中生成题 9 胜（45.0%）、真题 8 胜（40.0%）、平局 **3 次（15.0%）**→ Win Rate = 45.0%，评级 “✅ 良好：接近参考数据（差距 < 10%）”。

12.4.4 人工验证

为什么还需要人：数学题需严格逻辑推理，自动化替代不了；人还能发现自动化遗漏的创新性、趣味性；为此开发 Gradio Web 界面降低门槛。

流程：阅读题目/答案/解答 → 四维度打分（1–5 分，gr.Slider）→ 标注 ✅ approved / ❌ rejected / 🔄 needs_revision（gr.Radio）→ 添加评论。

启动：python data_generation/human_verification_ui.py <data_path> → 浏览器 http://127.0.0.1:7860；结果写 <data_path>_verifications.json。

12.4.5 生成器与完整流水线

四大组件：AIMEGenerator（批量生成、进度保存、处理 API 速率限制）、LLMJudgeTool、WinRateTool、HumanVerificationUI。

生成 Prompt 要点：给【Reference Example】但明确"仅作风格参考，生成完全不同的题目"；声明 AIME 特征（答案 0–999 整数、五大主题、需多步推理但不涉高深理论）；要求输出 JSON {problem, answer, solution, topic}。

• 为什么用英文出题：与真题一致、评估公平（英文对英文）、便于国际化、避免翻译偏差。
• ⭐ LaTeX 解析坑：生成题含 $\frac{a}{b}$，反斜杠在 JSON 中是非法转义，报错 Invalid \escape；修复用 re.sub(r'(?<!\\)\\(?!["\\/bfnrtu])', r'\\\\', json_str) 把未转义反斜杠转双反斜杠。
• 参考数据只用 AIME 2025：时效性、简化维护、格式统一（JSONL 小写字段）、代表性充分（30 题足以评估）。

完整入口：

python data_generation/run_complete_evaluation.py 30        # 默认 3 秒延迟
python data_generation/run_complete_evaluation.py 30 3.0    # 自定义延迟

三步：生成 → 评估（LLM Judge 取 max_samples=num_problems、Win Rate 取 min(num_problems,20) 次，均用 gpt-4o，各自 try/except 容错）→ 生成 comprehensive_report.md。

实测：生成 30 题（延迟 3.0 秒/题，tqdm 显示进度）、参考加载 963 道、总耗时 01:30；LLM Judge 平均 4.2/5.0、通过率 85.0%；Win Rate 45.0%。

12.4.6 综合评估报告七段模板 ⭐

1. 基本信息：生成时间、题目数量（30）、参考年份（2025）
2. 主题分布：代数 10/33.3%、几何 8/26.7%、数论 7/23.3%、组合 3/10.0%、概率 2/6.7%
3. LLM Judge：平均分 4.2 / 通过率 85.0% / 优秀率 40.0%（分维度 4.3 / 4.1 / 4.0 / 4.4）
4. Win Rate：9 胜 45.0% / 8 负 40.0% / 3 平 15.0%
5. 综合结论：“质量优秀，达到或超过 AIME 真题水平，可用于实际应用”
6. 改进建议：保持生成策略、可增加数量、建议人工验证
7. 下一步行动：人工验证命令、质量满意后用于训练或测试

质量门槛 ⭐：

• 生成侧：延迟 2–3 秒规避限流；启用检查点保存；先小批量 10 个验证再放大；定期检查生成质量及时调 prompt。
• 评估侧分工：LLM Judge 做绝对质量、Win Rate 做相对对比、人工验证做最终把关。
• 阈值：LLM Judge 平均分 ≥ 4.0/5.0；Win Rate ≥ 45%；通过率 ≥ 80%；人工验证通过率 ≥ 90%。

第十二章小结

本章回答"怎么证明你的 Agent 真的变好了"。起点是三大挑战——输出不确定、标准多样、成本高昂，必须靠标准化 Benchmark 把主观判断变成数字。

三层评估体系各有分工：

场景	数据	核心算法	考察点
BFCL	simple / multiple / parallel / irrelevance	AST 匹配（比结构性等价，容忍参数顺序、等价表达式与格式差异，代价是函数名必须精确一致）	函数调用正确性
GAIA	466 个真实问题，三个难度级别	准精确匹配（先归一化再精确比：数字去单位去逗号、字符串去冠词小写、列表要排序）	多步推理、工具使用、文件处理
数据生成质量	AIME 风格数学题	LLM Judge（四维 1–5 分，及格 3.5、优秀 4.5，默认评委 gpt-4o）+ Win Rate（理想 ≈ 50%）+ 人工验证（≥90%）	题目正确性、清晰度、难度匹配、完整性

工程上记住三点：① 模块化三层架构（Dataset / Evaluator / Metrics，全部封装成 Tool）；② 报告自动化模板（概览 → 指标 → 样本详情 → 可视化 → 建议）；③ 两条策略——渐进式评估 5 → 50 → 全部、以 accuracy > 0.8 晋级，对比评估每次只改一个变量。扩展方向：新增 Benchmark、自定义指标、⭐ 集成 CI/CD、数据生成评估加创新性/多样性维度。

最后提醒：BFCL 用自研 [TOOL_CALL:...] 格式的 SimpleAgent 在复杂场景弱于原生 Function Calling，这是项目做评测时的一个可优化方向。

---

附录：本篇速查表

概念	一句话
为什么需要协议	单体 Agent 有工具集成困境、能力扩展瓶颈、协作缺失三大限制
MCP	Anthropic，智能体与工具的桥梁，上下文共享，生态最成熟
A2A	Google，智能体间对等通信（P2P），核心抽象 Task 与 Artifact
ANP	社区，智能体"互联网"，DID 身份 + .well-known/agent-descriptions 服务发现，尚无成熟生态
MCP 三能力	Tools（主动执行）、Resources（被动供数）、Prompts（指导性模板）
MCP 五步工作流	发现 → 上下文构建 → 模型推理 → 执行 → 结果整合；工具描述质量决定成败
FC vs MCP	互补而非竞争：学会打电话 vs 全球通话标准；底层 JSON-RPC 2.0 + stdio
五种传输	Memory / Stdio / Stdio+Args / Stdio(npx) / HTTP·SSE·StreamableHTTP；远程传输用底层 MCPClient
自动展开	一个 MCPTool 自动展开成多个工具，必须给不同 name 作前缀（calculator→6、fs→14、weather→3）
自建 MCP Server	MCPServer + add_tool；统一返回 JSON 字符串、错误返回而非抛出、外部请求必设超时
Smithery	MCP 发布平台；必需 pyproject.toml + smithery.yaml；Docker EXPOSE 8081
协议解耦的证据	同一 Server 能被 HelloAgents 与 Claude Desktop 同时调用
Agentic RL	把 LLM 作为可学习策略嵌入感知—决策—执行循环，优化轨迹累积折扣奖励
PBRFT vs Agentic RL	状态从一步 → 序列；行动从文本 → 含工具；奖励从终局 → 累积折扣
SFT 先行	教会可解析格式（否则抽不出答案、算不了奖励），并缩小 RL 探索空间
LoRA	ΔW=BA 冻结原权重；rank 默认 8、alpha 常取 2×rank；4096² → 减少 256 倍
GRPO 省掉了什么	⭐ 去掉 Value/Critic，用组内相对优势 r − r̄ 当基线，只留 Policy + Reference + KL
三类奖励	准确率（二值稀疏）、长度惩罚（α=0.001，只罚答对的）、步骤奖励（每步 +0.1，只奖答对的）
训练收益	GSM8K：SFT 40–50% → RL 60–70%；短板 计算错误 42.1%；步数越难越差（78.5→58.3→31.6%）
BFCL	UC Berkeley，AST 匹配；四类 simple/multiple/parallel/irrelevance；主指标 Accuracy
AST 等价三条件	函数名精确一致 + 参数键值对集合相等 + 参数值语义等价
GAIA	Meta + HF，466 题三级；准精确匹配 = 先归一化再精确比；数字去单位、字符串去冠词、列表排序
GAIA 三指标	Exact Match Rate、Level-wise Accuracy、Drop Rate（下降率）
LLM Judge	四维（正确性/清晰度/难度匹配/完整性）1–5 分；及格 3.5、优秀 4.5；默认评委 gpt-4o
Win Rate	成对对比，⭐ 理想 ≈ 50%；Wins + Losses + Ties = 100%
生成侧质量门槛	平均分 ≥ 4.0、Win Rate ≥ 45%、通过率 ≥ 80%、人工通过率 ≥ 90%
评估模块三层	Dataset（数据）/ Evaluator（评估）/ Metrics（指标），全部封装成 Tool