HF Agents Course Unit4 GAIA

阶段: B18 · OSS 收口 + 英文 + 全局 SOTA 复核（Day 171-180） 标签: #gaia-benchmark #agent-tooling #provider-agnostic #leaderboard

今日导引（由浅入深）

到 B18 尾声，AICAP 的评测能力已经历一整条自有评测链：

• 「自建 29-task suite → partial-credit / κ harness → A/B + CI → outcome 仪表盘」；
• 但一直缺一块：用公认的外部 benchmark 给自己的 agent runner 一个可对外横比的分数；
• 今天用 Hugging Face Agents Course Unit4 的 GAIA（Level 1）来补这一块——它是 2026 主流的多步工具使用 benchmark，提交后有 leaderboard 分数；
• 这是「我的 runner 在外部标准下能拿多少分」的可核验答案。

承上启下：昨天（Day 178）把一个修复提成了 open PR；今天换轨到「跑外部 benchmark」；明天（Day 180）是 stretch 的 verifiers Environment + 全批次收口。今日最小可判定产出：GAIA L1 leaderboard 分数 + 提交截图（里程碑目标 ≥30% L1）。

1. 机理精读

GAIA 是什么、Level 1 考什么。

• GAIA（General AI Assistants benchmark）测的是真实助手任务：需要搜索、推理、文件处理等多步工具使用才能答对。
• 每题有唯一可判定答案（grounded QA，自动判分），不靠主观打分。
• Level 1 是最低难度档——题型相对短链、工具组合较少，但仍要求「正确编排多个工具 + 给出精确答案」。
• 依据：HF Agents Course Unit4（2026）；GAIA paper。

为什么 GAIA L1 与本仓 29-task suite 可迁移。

• seed 指出二者在「多工具编排 + 可判定答案」这两个维度上同构。
• 本仓 tasks.ts 里的 planning-tool-selection 要求在 getTokenPrice / getWalletBalance 间正确选工具并带对参数（codeCheck 断言出现 getWalletBalance + 0xABC 且不出现 getTokenPrice）。
• reasoning-grounding-only 要求只用给定 watchlist [0xAAA, 0xBBB] 判定 0xCCC，不臆造 label——这正是 GAIA grounded QA 的结构。
• 换句话说：会做本仓 suite 的 runner，结构上就具备跑 GAIA 的能力，只需把工具集适配过去。

runner 的工具接口如何适配 GAIA。

• seed 让 runner 复用 toolRegistry.ts 的工具接口适配 GAIA 工具集。
• toolRegistry.ts 把「工具暴露给 LLM 的契约层」抽成了 register(spec, handler) + list()（tools/list）+ call(name, args)（tools/call，先按 inputSchema 校验再进 handler）。
• GAIA 需要的搜索/文件工具，只要按这套 spec/handler 契约注册进去，runner 的调用路径不变。
• 这就是「provider-agnostic + tool-agnostic」runner 的价值：换 benchmark 只换工具注册，不改编排核心。

provider-agnostic 的含义与诚实边界。

• 本仓 runner 默认 provider 是 deepseek，跑 GAIA 时用 DeepSeek-V4（经 OpenRouter 或直连）起真模型回合。
• 这一步需要 key，且涉及外部提交到 HF leaderboard，所以是「待跑(需 key) + 外部提交」——不是确定性单测能覆盖的部分。
• 本仓的 29-task 基线（V4-Pro 89.7% / V4-Flash 79.3%）是在本仓自有任务集上测的，与 GAIA 是不同任务、不同判分，不可直接横比。
• 这条边界必须在结论里讲清，否则就是误导性对标。

与相邻概念的边界。

• 今天不是「自评自己的 suite」（那是 B1-B17 已做、且 seed 反复警示循环自评的局限）。
• GAIA 的价值恰在于它是外部标注 + 外部判分，补上了自有 suite 缺的独立 ground truth。
• 但它也只测「通用助手任务」，不测 AML 合规专精——所以它是补充，不是替代本仓 AML 评测。

2. 代码走读：runner 复用的工具契约

seed 明确 runner 复用 toolRegistry.ts 工具接口适配 GAIA 工具集。走读其真实契约（已 Read src/agent/mcp/toolRegistry.ts）：

• McpToolSpec { name, description, inputSchema: JsonSchema } —— 工具声明三件套，对应 GAIA 工具集里每个工具要暴露给 LLM 的契约。
• McpToolRegistry.register(spec, handler) —— 注册一个内部函数为工具；重名抛错（避免静默覆盖）；强制 inputSchema.type === 'object'；名字须匹配 /^[a-zA-Z][\w.-]*$/。适配 GAIA 时，把搜索/文件工具按此注册即可。
• list() —— tools/list，按 name 稳定排序返回声明列表，stateless 可缓存（注释：「结果可被客户端按 ttl 缓存」）。
• call(name, args) —— tools/call：先 validate(spec.inputSchema, args)，校验失败抛 McpCallError(RPC.INVALID_PARAMS, …, errs)；handler 抛错包成 McpCallError(RPC.INTERNAL_ERROR, …)。先校验后执行是工具调用的安全最小防线。
• handle(req: JsonRpcRequest) —— JSON-RPC 2.0 信封版，永不抛错（所有失败折成 response.error），演示 MCP over JSON-RPC 报文形状。
• validate(schema, value) —— 递归校验 type / enum / minLength / minimum/maximum / array items / object required+properties，返回错误数组（空=通过）。

诚实边界（文件头注已标）：这是教学模拟，实现的是 MCP 2026-07-28 stateless 语义的协议形状，不是网络 server——没有 HTTP transport、没有 OAuth、没有 Tasks 扩展。跑真实 GAIA 时，工具的实际执行（搜索/取文件）需要真后端，本装置只提供「契约层 + schema 校验」。

走读结论：runner 把 GAIA 工具按 register(spec, handler) 契约挂上，调用走 call（先 schema 校验后执行），即可在不改编排核心的前提下适配 GAIA 工具集。

3. 今日实战

1. 用本仓 provider-agnostic runner（默认 deepseek）起 agent。
2. 配 DeepSeek-V4（经 OpenRouter 或直连，需 key）作为模型后端；当周复验可用 id 与价格。
3. 把 GAIA L1 所需工具（搜索/文件处理等）按 toolRegistry.ts 的 register(spec, handler) 契约注册进 runner 的工具集；调用走 call（schema 校验后执行）。
4. 按 GAIA 答案规范做输出抽取/规范化（精确匹配判分，去掉多余解释与单位）。
5. 跑 GAIA L1 题集，收集 runner 的答案。
6. 提交到 HF Agents Course Unit4 评测，取 leaderboard 分数，截图。
7. 在笔记/transcript 里明确标注：GAIA 分数与本仓 29-task 基线（V4-Pro 89.7% / V4-Flash 79.3%）不可直接比（不同任务、不同判分）。

4. 今日实测 / 产出

• GAIA score + 提交截图：待跑(需 key 跑 GAIA 真模型回合) + 外部提交（seed 状态原样保留）。未完成、不升级为已完成。里程碑目标 ≥30% L1。
• 本仓基线参照（已落地，但不可直接比 GAIA）：V4-Pro 89.7% / V4-Flash 79.3%（本仓 29-task，非 GAIA）。
• Block 里程碑参照：HF Agents Course Unit4 GAIA = 待跑(需 key) + 外部提交（目标 ≥30% L1）。

5. 常见误区 / 陷阱

• 拿本仓 29-task 分数对标 GAIA：不同任务集、不同判分标准，直接横比是无效对标。结论里必须显式标「不可直接比」。
• 用旧模型 GAIA 分数作对标：模型代际已换，引旧 GPT-4 GAIA 分数对标会失真（见 SOTA 检查）。
• 把工具适配写死在编排核心：GAIA 工具应通过 register 注册，而非改 runner 主循环——否则换 benchmark 又要改核心，丧失 provider/tool-agnostic 优势。
• 跳过 schema 校验直连 handler：toolRegistry.call 先 validate 后执行是安全最小防线；适配 GAIA 工具时若绕过校验，等于放弃了对工具入参的零信任检查。
• 把「待跑」写成「已跑」：需 key + 外部提交，未实际拿到 leaderboard 分数前不算完成。
• 误把教学装置当真 server：toolRegistry.ts 头注明确这是进程内协议形状模拟，没有 HTTP transport / OAuth / Tasks 扩展；GAIA 工具的真实执行（联网搜索、读文件）需要真后端，本装置只提供契约层。
• 答案格式不匹配判分器：GAIA 自动判分对答案格式敏感（精确字符串匹配）；runner 输出多余解释/单位会判错，需按 GAIA 要求做答案抽取/规范化。

6. 学习资源（每条带 YYYY-MM）

• Hugging Face Agents Course，Unit4（GAIA 评测 + leaderboard），2026。
• GAIA: a benchmark for General AI Assistants（GAIA paper，原始基准定义；多步工具使用 + 唯一可判定答案）。
• HF Agents Course 前序单元（agent 范式 / 工具调用 / 多步推理），2026——Unit4 的能力前置。
• DeepSeek-V4（V4-Pro / V4-Flash）模型卡与 API 文档，当周版本/ id 需复验。
• OpenRouter 路由文档（DeepSeek-V4 接入），2026 当周。
• tau2-bench（工具使用对话 benchmark，GAIA 的互补评测），2025-2026——本仓 gated 清单中的下一组 benchmark。
• 本仓 src/agent/mcp/toolRegistry.ts（register / list / call / validate 工具契约层，本日已走读，seed 依据）。
• 本仓 src/agent/eval/tasks.ts（planning-tool-selection / reasoning-grounding-only 等编排+grounded 任务，与 GAIA 同构，本日已走读）。

SOTA检查 (2026-06 更新)

• GAIA 仍是 2026 主流 agent benchmark，仍 SOTA；与 tau-bench / tau2-bench（工具使用对话 benchmark）互补。
• 模型 id：deepseek-v4-pro / deepseek-v4-flash 为当前 id；legacy deepseek-chat / deepseek-reasoner 已于 2026-07-24 退役，勿用。
• 过时黑名单：
  • 避免引旧 GPT-4 GAIA 分数作对标（模型代际已换）；
  • 避免拿不同任务集的分数做直接横比（本仓 29-task ≠ GAIA）。
• 下次复查点：
  • 提交前复验 HF Agents Course Unit4 leaderboard 当周是否开放、GAIA 题集版本；
  • 复验 DeepSeek-V4 当周可用 id 与价格、OpenRouter 是否仍路由该模型。

衔接

• 昨天：Day 178 — 提 PR + 英文沟通（open 状态上游 PR，正文贴 before/after + N/Δ/CI）
• 今天：用 provider-agnostic runner + DeepSeek-V4 跑 GAIA L1，提交取 leaderboard 分数（目标 ≥30%）
• 明天：Day 180 —（stretch）verifiers Environment + 收口（Environment+Rubric 最小 env 跑 reward，回填 block-summary 三数汇总）