When a model learns from a tool-using conversation, “one example” is not a simple text string. It is a sequence of roles, tool calls, observations, hidden and visible reasoning, final answers, and choices about which tokens receive loss. Every conversion step expresses an assumption about the behavior we want to reinforce.当模型从工具使用对话中学习时,“一个样本”远不是一段简单文本。它包含角色、工具调用、观察结果、显式与隐式推理、最终回答,以及哪些 token 承担 loss 的选择。每一步转换都在表达我们希望强化哪种行为。

That is why I treat the data contract as part of the model. A correct-looking JSON file is not enough. The contract extends from the original trajectory through template encoding, supervision masks, packed sequences, the loaded checkpoint, and the agent run used to evaluate it.因此,我把数据契约视作模型的一部分。格式正确的 JSON 文件还不够;契约必须贯穿原始轨迹、模板编码、监督掩码、打包序列、实际加载的权重,以及最终用于评测的智能体运行。

Loss masks choose the lesson监督掩码决定课程内容

Suppose a trajectory contains several assistant turns, but only some are intended to teach a deliberate tool decision. Flattening the entire trace into one supervised span may reward a turn that merely inherited context, or a no-thinking action that was meant to be background. Conversely, dropping the earlier turns entirely may remove the history needed to make the supervised decision intelligible.假设一条轨迹包含多个 assistant 轮次,其中只有部分轮次用于学习审慎的工具决策。把整条轨迹铺成一段监督区间,可能强化本来只应作为上下文的轮次,甚至把无思考动作当成正例;但完全删去早期轮次,又会丢掉理解当前决策所需的历史。

A useful split keeps the previous messages as context while making the intended decision turn the supervised target. The invariant is concrete: every turn meant to teach the behavior should receive loss exactly where intended, and no unrelated turn should silently inherit it.有效的切分方式应保留历史消息作为上下文,只让目标决策轮次承担监督。关键不变量很具体:每个应被学习的动作都在预期位置承担 loss,其他轮次不会悄悄继承监督。

The run needs a traceable identity训练运行需要可追溯的身份

Long-context packing adds another layer. A packed sequence may cross several original examples; a truncation rule can remove the turn we intended to supervise; a tool response can dominate token counts without being the action we want to optimize. I check the encoded sample, not only the source record.长上下文打包又添了一层复杂性。一段打包序列可能跨越多个原始样本;截断规则可能删掉本来要监督的轮次;工具返回可能占据大多数 token,却不是我们要优化的动作。因此我会检查编码后的样本,而不仅是源文件。

Finally, an evaluation number belongs to a particular checkpoint, prompt, tool protocol, context budget, and judge. When those links are explicit, a result can guide the next training decision. When they are missing, even a strong score says little about what changed.最后,评测数字总属于某个具体的权重、提示词、工具协议、上下文预算与判分器。把这些连接明确下来,结果才能指导下一次训练;连接一旦缺失,再漂亮的分数也难以说明究竟发生了什么。

The practical habit is to follow one example all the way through the system. From raw messages to encoded tokens, from loss positions to saved weights, and from those weights to an observed agent trace. That single chain often exposes problems a dashboard cannot.最实用的习惯,是沿系统完整追踪一个样本:从原始消息到编码 token,从 loss 位置到保存的权重,再从权重到真实的智能体轨迹。这样一条链,经常能暴露仪表盘看不到的问题。