为什么原始轨迹不能直接微调?claude-fable-5-claude-code与teich的过滤机制深度解读
为什么原始轨迹不能直接微调?claude-fable-5-claude-code与teich的过滤机制深度解读
claude-fable-5-claude-code 是一个开源的 Agent 轨迹数据集:它汇集了 Glint Research 等团队收集的 claude-fable-5 模型在真实编码会话中使用工具(Bash、Read、Edit、Task 等)的原始事件日志,采用 MIT 许可。本文带你打开真实的轨迹文件,解释为什么这些原始轨迹(raw traces)不能直接拿去微调,以及 teich 工具的过滤机制是如何把它们转换成 OpenAI 风格训练数据的。🔍
一、先认识这份数据:63 个 .jsonl 文件里的"会话录像"
这个仓库非常"纯粹"——没有代码,只有数据:
| 内容 | 说明 |
|---|---|
| 55 个主会话文件 | UUID 命名,如 21576682-1c94-4e42-a9d2-0f9e0137ffa7.jsonl |
| 8 个子代理文件 | agent-*.jsonl 命名,如 agent-a87ca9b22d0fee3f9.jsonl,对应被委派的子任务线程 |
| 工具清单快照 | README.md 中给出了训练就绪的工具 schema 快照(约 35 个工具) |
| 许可 | MIT(见 README.md) |
随便打开一个文件,比如 21576682-1c94-4e42-a9d2-0f9e0137ffa7.jsonl,你会看到一段很真实的"录像":用户问 "How do I start this?",模型连续调用 Bash(ls 目录)、Read(package.json)、Bash(检查 server 入口),最后给出启动命令。看起来就像一段对话,对吧?
别急着丢进训练框架。 这正是这篇文章要拆解的坑。⚠️
二、打开一条原始轨迹:它根本不是"干净的聊天"
以 6ae0aeed-340e-4b4d-9d74-f905a74ca2fc.jsonl(一个"从零构建 Roblox 克隆"的长会话,单文件 6.5 MB)为例,统计其中每一行 JSON 的 type 字段,会发现一个会话文件里其实混着 11 种记录:
| 记录类型(type) | 实际是什么 | 能训练吗 |
|---|---|---|
user / assistant |
真实对话、思考块、工具调用与结果 | ✅ 这才是训练素材 |
last-prompt / ai-title |
会话元信息:提示词指针、AI 生成的标题 | ❌ |
mode / permission-mode |
会话模式与权限级别(如 bypassPermissions) |
❌ |
bridge-session |
Claude Desktop 桥接会话 ID(cse_...) |
❌ |
queue-operation |
输入排队操作(enqueue/dequeue) | ❌ |
file-history-snapshot |
供文件回滚用的快照 | ❌ |
attachment |
Hook 注入内容(本数据集中甚至有 SessionStart hook 注入的角色设定文案) | ❌ |
system |
本地命令输出(如 /remote-control 连接日志) |
❌ |
实测该文件:assistant 303 条、user 162 条,而上面这些"噪声"记录加起来有 301 行——将近 40% 的内容根本不是对话。原始轨迹截取几行感受一下:
{"type": "permission-mode", "permissionMode": "bypassPermissions", "sessionId": "6ae0aeed-…"}
{"type": "ai-title", "aiTitle": "Build Roblox clone with multiplayer and game editor", …}
{"type": "bridge-session", "bridgeSessionId": "cse_01V4tM…", "lastSequenceNum": 0, …}
直接把这样的文件按行解析成 chat,训练框架要么报错,要么把元数据当成"模型发言"来学。
三、四个让原始轨迹"不能直接微调"的硬伤
1️⃣ 限流提示被写进了 assistant 消息
这是最隐蔽也最致命的问题。原始轨迹中,当用户触达使用额度时,harness 会注入一条 model 为 <synthetic> 的合成 assistant 消息。本数据集里共有 56 条这样的记录,例如:
{"type": "assistant", "message": {"model": "<synthetic>", "role": "assistant",
"content": [{"type": "text", "text": "You've hit your session limit · resets 3:50am (America/New_York)"}]}}
注意它的 role 是 assistant。如果不做过滤直接微调,模型会认真学到:"额度用完了,我该输出一句限流提示然后停住"——这正是 README.md 强调要用 teich 过滤 "hitting limits" 的原因。
2️⃣ 模型切换与会话中断破坏序列一致性
同一个数据集汇集了多种 harness(claude、hermes、pi、cursor)产生的轨迹,会话中可能出现模型版本切换、用户中途打断(轨迹里能看到 "killed by user" 的中断痕迹)。半截被打断的对话、前后风格不一致的回复,都会污染序列建模——teich 会把 "model switches" 这类记录一并过滤掉。
3️⃣ 子代理(sidechain)与主会话混杂
像 agent-a87ca9b22d0fee3f9.jsonl 这类文件记录的是子代理线程(isSidechain: true):开头就是一条完整的委派任务("为 NEONSTRIKE 构建多人层,只允许新建两个文件……")。它与主会话是并行的另一条对话线,如果粗暴地把所有文件拼在一起,上下文就会错乱。
4️⃣ 工具 schema 不统一,会让学生模型"叫错工具名"
不同会话、不同 harness 暴露的工具集和参数并不完全一致。混着训练,模型容易学会错误的工具名、参数名和描述。这就是为什么 README.md 特意附上了"训练就绪"的工具 schema 快照(Agent、Bash、Edit、Read、WebSearch、Task、MCP 工具等),而 teich 官方说明中强调它 知道这些工具的精确 schema 与描述,能在转换时把它们对齐。
另外,原始轨迹里含有真实环境的路径与输出(虽然数据集已做匿名化处理),但如果你要用自己的 harness 采集数据,也需要先做脱敏——这一步同样交给 teich。🧹
四、teich 过滤机制:一条命令得到"训练就绪"数据
README 给出的工作流非常直接:
pip install -U teich
teich extract claude --model fable-5
teich extract 会完成一整条数据清洗流水线:
- 提取:从本地 harness 会话目录中抽取对应模型的轨迹,并做匿名化;
- 过滤:剔除限流合成消息、模型切换、以及上述各类非对话记录;
- 转换:输出 OpenAI 风格的标准 chat 格式(
role/content消息数组); - 对齐:按已知工具 schema 统一工具调用格式,使数据"开箱即可训练"。
📌 一个重要的避坑提示:Glint-Research/Fable-5-traces 数据集就是这份数据格式化拆分后的版本(见 README.md)——两者是同一批数据,微调时二选一,切勿混用,否则等于重复训练。
五、如何获取这份轨迹数据
仓库为只读数据集,克隆即可使用(注意部分大文件走 Git LFS,克隆时需启用 LFS 拉取,否则只能看到类似 f956721a-0af7-4bdc-8678-3a493d8fcd39.jsonl 的 3 行指针文件):
git clone https://gitcode.com/hf_mirrors/armand0e/claude-fable-5-claude-code
推荐的训练姿势:克隆仓库 → 用 teich 转换为 OpenAI 风格 chats → 再进入微调,全程不要跳过过滤环节。
六、小结
- 原始 Agent 轨迹是"事件日志",不是"对话":近 40% 的行是元信息、Hook、快照等噪声;
- 限流合成消息、模型切换、中断、子代理线程、工具 schema 不一致,是五类最典型的"毒数据";
- teich 的过滤机制(提取 + 匿名化 + 过滤 + 格式对齐)是这份 claude-fable-5 轨迹从"不能训"到"能训"的关键一步;
- 记住:本仓库与 Glint-Research/Fable-5-traces 同源,微调时只用其一。✅