为什么原始轨迹不能直接微调?claude-fable-5-claude-code与teich的过滤机制深度解读

原创2026-10-16 13:11:141,959 阅读

为什么原始轨迹不能直接微调?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 会完成一整条数据清洗流水线:

  1. 提取:从本地 harness 会话目录中抽取对应模型的轨迹,并做匿名化;
  2. 过滤:剔除限流合成消息、模型切换、以及上述各类非对话记录;
  3. 转换:输出 OpenAI 风格的标准 chat 格式(role/content 消息数组);
  4. 对齐:按已知工具 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 同源,微调时只用其一。✅
登录后查看全文
claude-fable-5-claude-code