Agent training · Data formats
Agent 轨迹如何变成 Foundation Model 训练数据From Agent Traces to Foundation Model Training Dataエージェントの軌跡を基盤モデルの学習データへ
Agent 读文件、调用工具、检查结果,再决定下一步。训练数据需要保留这条因果链,同时告诉模型:哪些内容用来理解上下文,哪些动作需要学会。An agent reads files, calls tools, inspects results, and chooses its next action. Training data must preserve that causal chain—and distinguish the context the model reads from the actions it should learn.エージェントはファイルを読み、ツールを呼び、結果を確認して次の行動を決める。学習データには、この因果関係と、読むための文脈・学習する行動の区別が必要になる。
2026 年 10 月 · 数据工程October 2026 · Data engineering2026年10月 · データエンジニアリング
这里沿着一次 CLI Agent 数据导出,拆开看这套面向基础模型的文本轨迹格式:一条完整会话放进一行 Parquet,消息变成有序片段,片段再标出是否参与训练损失。This walkthrough follows a CLI-agent data export for foundation-model training: one full conversation per Parquet row, messages serialized into ordered segments, and a loss flag on each segment.CLIエージェントのデータ出力を例に、Parquetのテキスト軌跡形式を見ていく。会話全体をParquetの1行に収め、メッセージを順序付きの断片に変換し、各断片に損失計算の対象かどうかを記録する。
静态图Static figure静止図
同一个 CaseThe same case同じCase
沿用库存搭建案例,看一轮工具调用如何从原始消息变成训练输入。Follow one tool-call turn from the inventory case into the two training formats.在庫構築Caseのツール呼び出し1ターンを、元のメッセージから二つの学習形式へ変換する。
读取产品库存Read product inventory商品在庫を読む
lark-cli base +record-list --base-token "<base>" --table-id "<products>" --as user6 条产品记录6 product records商品レコード6件
count=6 · has_more=falseT11核对出入库记录Read stock movements入出庫履歴を確認查看消息字段Message fieldsメッセージのフィールド
一行样本训练一个回答:历史作输入,T10 的读表调用作目标。One row trains one response: history is the input; the T10 read call is the target.1行で1つの応答を学習。履歴が入力、T10の読み取り呼び出しが学習対象。
Query + 历史消息Query + historyQuery + 履歴
past assistant · loss_weight=0读取产品库存Read product inventory商品在庫を読む
Bash → +record-listloss_weight=1“6 条记录”是调用之后的返回,进入 T11 样本的历史,不是 T10 的答案。The 6-record result arrives after the call. It enters T11’s history, not T10’s answer.「6件」は呼び出し後の戻り値。T11の履歴に入り、T10の回答には含まれない。
查看这行 JSONL 的结构This JSONL rowこのJSONL行の構造
一行保留整条轨迹。下面是其中相邻的三个片段:模型输出参与训练,工具返回只提供上下文。One row keeps the full trace. These three adjacent segments train model outputs and use tool results as context.1行に全軌跡を保持。隣り合う3断片を見ると、モデル出力は学習対象、ツール結果は文脈になる。
读取产品库存Read product inventory商品在庫を読む
has_loss=1返回 6 条记录Return 6 records6件を返す
has_loss=0核对出入库记录Read stock movements入出庫履歴を確認
has_loss=1模型按顺序读取:T10 不能看到尚未发生的工具返回。The sequence is causal: T10 cannot see the tool result that comes after it.読み取りは因果順序。T10から、その後のツール結果は見えない。
查看 Parquet 行与片段字段Parquet row and segment fieldsParquet行と断片のフィールド
第一步:先选轨迹,再按任务划分1. Select traces, then split by task1. 軌跡を選び、タスク単位で分割する
质量筛选发生在格式转换之前。同一条轨迹可能被多次评审、在多个批次出现,因此要先固定筛选条件,再去重并保留来源。训练集与测试集按 query 分组,同一个问题的多次尝试不跨集合。Quality selection comes before format conversion. A trajectory may be evaluated repeatedly or appear in several batches, so selection rules are fixed before deduplication, with provenance retained. Splits are grouped by query so repeated attempts at the same task stay together.品質による選別は形式変換より先に行う。同じ軌跡が複数回評価されたり、複数のバッチに現れたりするため、選別条件を固定したうえで重複を除き、出典を残す。データ分割はquery単位とし、同じ問題への再試行を別集合に分けない。
另一次 207 条轨迹的批量导出,Parquet 得到 207 行,方舟逐目标导出得到 6,078 行。两者使用同一批任务与动作,差别在于样本的组织方式。A separate batch of 207 traces produced 207 Parquet rows and 6,078 target-wise Ark rows. Both exports use the same tasks and actions, organized into different sample units.別バッチの207本の軌跡から、Parquetは207行、対象別のArk出力は6,078行になった。タスクと行動は共通で、サンプルのまとめ方が異なる。
| 划分Split分割 | 完整轨迹行Full-trajectory rows軌跡単位の行数 | assistant 学习目标Assistant targetsassistantの学習対象 |
|---|---|---|
| 训练集Train訓練 | 186 | 5,458 |
| 测试集Testテスト | 21 | 620 |
| 合计Total合計 | 207 | 6,078 |
Parquet 一行里可以有多个学习目标。逐目标展开则为每个目标携带它之前的历史。这次两种导出对历史推理的处理也不同:Parquet 版本保留各轮原生推理,方舟版本未在历史 assistant 上重复携带 reasoning_content。因此不能把行数直接解释成数据量或训练成本的倍数。A Parquet row can contain many supervised targets. Target-wise expansion repeats the preceding history for each target. These exports also handle past reasoning differently: Parquet retains native reasoning across turns, while this Ark version does not carry historical assistant reasoning_content. The row ratio is therefore not a ratio of independent data or training cost.Parquetの1行には複数の学習対象が入る。対象ごとの展開では、それぞれに先行する履歴を付ける。この比較では過去の推論の扱いも異なり、Parquetは各ターンの推論を保持するが、Ark版は履歴中のassistantのreasoning_contentを含めない。行数比を独立なデータ量や学習コストの比とみなすことはできない。
为什么和方舟提训格式不同Why the Ark training format differsArkの学習形式と何が違うのか
这次使用的方舟 LLMSft 接口接收 JSONL,每行保留 messages 与 tools 等结构化字段。Parquet 导出则提前完成协议拼接,把带监督标记的输入片段写入 Parquet。区别在于,哪些转换由数据侧做,哪些交给训练平台做。The Ark LLMSft interface used here takes JSONL with structured fields such as messages and tools. The Parquet export prepares the protocol sequence in advance and stores loss-marked segments in Parquet. The key difference is where preparation happens: in the dataset exporter or in the training platform.今回使ったArk LLMSftは、messagesやtoolsなどの構造化フィールドをJSONLで受け取る。Parquet出力は、プロトコルに沿った系列を事前に作り、学習対象を指定した断片をParquetに保存する。違いは、どの変換をデータ側で行い、どこから学習基盤に任せるかにある。
| 比较项Aspect比較項目 | 本次方舟 JSONLArk JSONL used here今回のArk JSONL | 本次 Parquet 导出Parquet export used here今回のParquet出力 |
|---|---|---|
| 文件与字段File and fieldsファイルとフィールド | 每行 JSON;messages / toolsOne JSON object per line; messages / tools1行1JSON。messages / tools | 四列;inputs 内是协议片段Four columns; inputs holds protocol segments4列。inputsにプロトコル断片 |
| 样本单位Sample unitサンプル単位 | 历史前缀 + 一个 assistant 目标History prefix + one assistant target先行履歴 + assistantの1対象 | 完整轨迹 + 多个 assistant 目标Full trace + multiple assistant targets全軌跡 + assistantの複数対象 |
| 工具动作Tool actionsツールの行動 | 原生 tool_calls 与 tools schemaNative tool_calls and tools schemasネイティブなtool_callsとtoolsスキーマ | FunctionSP + XML65 调用文本FunctionSP + XML65 call textFunctionSP + XML65呼び出し本文 |
| 推理内容Reasoning推論内容 | 当前目标用 reasoning_content;历史不重复携带reasoning_content on the current target, not past assistants現在の対象にreasoning_content。過去のassistantには含めない | 各轮原生推理序列化进正文Each turn’s native reasoning in the serialized body各ターンの推論を本文へ直列化 |
| 监督位置Supervision学習対象の指定 | 历史 assistant 的 loss_weight=0,当前目标=1Past assistants: loss_weight=0; current target: 1過去のassistantはloss_weight=0、現在の対象は1 | 按片段设置 has_loss;本批监督全部 assistant 正文与 EOSSegment-level has_loss; all assistant bodies and EOS in this batch断片ごとのhas_loss。本バッチは全assistant本文とEOSを対象とする |
| 长度核算Length accounting長さの計測 | 逐目标计算当行历史与目标长度Check each prefix-and-target row各行の履歴と対象を計測 | 计算完整会话、协议头与各轮推理Check the full conversation, headers, and reasoning全会話、ヘッダー、各ターンの推論を計測 |
下面把同一条两次动作的轨迹拆开。Q 是请求,A₁、A₂ 是两次 assistant 输出,Tool 是第一次动作的真实返回。方舟逐目标导出为两行;Parquet 版本把两个目标保留在同一行。The diagram follows a trace with two assistant actions. Q is the request, A₁ and A₂ are assistant outputs, and Tool is the actual result of the first action. The target-wise Ark export makes two rows; Parquet retains both targets in one row.次の図はassistantの行動が2回ある軌跡を示す。Qは依頼、A₁とA₂はassistant出力、Toolは最初の行動の実際の応答。対象ごとに展開するArk出力は2行、Parquetは両方の対象を1行に収める。
静态图Static figure静止図
逐目标展开,是我们为当次方舟 reasoning_content 提训约定采用的导出方式;多轮上下文仍然存在。这里的片段格式可以直接标记一条长序列中的多个目标,于是这条导出路径选择保留完整轨迹。JSONL 和 Parquet 都只是容器,本身并不强制单目标或多目标。Target-wise expansion was our export choice for that Ark reasoning_content training contract; multi-turn context is still present. This segmented format can mark multiple targets within a long sequence, so this export keeps the full trace. JSONL and Parquet are containers: neither inherently requires single-target or multi-target training.対象ごとの展開は、当時のArkのreasoning_content学習仕様に合わせた出力方法であり、複数ターンの文脈は残っている。Parquetの断片形式は長い系列内の複数学習対象を直接指定できるため、この出力では全軌跡を保持した。JSONLとParquetは容器であり、単一対象か複数対象かを本質的に決めるものではない。
因此,迁移数据不能只把后缀从 jsonl 改成 parquet。需要重新对齐工具协议、推理区段、监督标记和长度检查;比较效果时,也要固定原始轨迹和划分,核对两边实际看见的历史是否相同。Migration therefore requires more than changing a file extension. Tool protocols, reasoning sections, supervision masks, and length checks must be aligned. A meaningful comparison fixes the source traces and splits, then checks whether both training paths actually receive the same history.移行は拡張子を変えるだけでは済まない。ツールの形式、推論区間、教師信号、長さの検証を合わせ直す必要がある。効果を比べる際は元の軌跡と分割を固定し、両方に渡る履歴が実際に同じかを確かめる。
第二步:把动作写成模型要读的协议2. Serialize actions into the model’s protocol2. 行動をモデルが読む形式に変換する
输入开头有三段系统消息:ThinkSP 约定推理与回答的表达方式,FunctionSP 描述工具及其参数,MainSP 保留任务本身的规则。旧记录只有 MainSP 时补齐协议头;已经有三段时校验并规范化,避免重复追加。Three system messages lead the input: ThinkSP defines the reasoning-and-answer convention, FunctionSP describes tools and their parameters, and MainSP retains the task instructions. Legacy records with only MainSP receive the protocol headers; existing three-part prefixes are checked and normalized instead of appended again.入力の先頭は3つのシステムメッセージで構成する。ThinkSPは推論と回答の表現、FunctionSPはツールと引数、MainSPはタスクの指示を担う。MainSPだけの旧記録にはプロトコルのヘッダーを補い、3段構成がある記録は確認して正規化し、重複追加を避ける。
assistant 原来分开的 reasoning_content、content 和 tool_calls,在目标训练序列中合成一段文本:推理区段、回答正文、XML65 工具调用。真实工具返回仍留在下一条 tool 消息中,不搬进模型的回答。The assistant’s separate reasoning_content, content, and tool_calls fields become one text payload in the target training sequence: a reasoning section, answer text, and XML65 tool calls. Actual tool results remain in the following tool messages, not in the assistant’s answer.assistantのreasoning_content、content、tool_callsは、Parquetの列では推論区間、回答本文、XML65のツール呼び出しを含む1つの本文になる。実際の実行結果は後続のtoolメッセージに残し、assistantの回答には移さない。
静态图Static figure静止図
库存案例中的 Read 动作,转换后仍是读取同一个文件,只是调用写法变为 XML65。下面省略实际路径;推理区段也要使用目标协议的标签。The inventory case’s Read action still reads the same file after conversion; its call is now written in XML65. The actual path is omitted below. The reasoning section must also use the target protocol’s tags.在庫CaseのReadは変換後も同じファイルを読む。変わるのはXML65での呼び出し表現だ。以下では実際のパスを省略した。推論区間にも対象プロトコルのタグを使う。
<seed:tool_call><function name="Read">
<parameter name="file_path" string="true">[original path omitted]</parameter>
</function></seed:tool_call>
字符串参数带 string="true";数字、布尔值和对象等用 JSON 表达,并标记 string="false"。这属于模型的序列化协议,不是普通网页 XML:命令和文件内容不能被额外 HTML 转义,也不能被一个通用格式化器悄悄改写。String arguments use string="true". Numbers, booleans, and objects use JSON representations with string="false". This is a model serialization protocol, not ordinary web XML: commands and file contents must not be additionally HTML-escaped or silently rewritten by a generic formatter.文字列引数にはstring="true"を付ける。数値・真偽値・オブジェクトなどはJSONで表し、string="false"とする。これはモデル向けの直列化プロトコルであり、通常のWeb用XMLではない。コマンドやファイル内容を追加でHTMLエスケープしたり、汎用フォーマッターで書き換えたりしない。
第三步:上下文都能读,只有部分要学3. Read the context; learn the selected outputs3. 文脈を読み、指定された出力を学習する
每条消息被拆成四段:起始标记、角色、正文、结束标记。每段都有 type、text 和 has_loss。type 告诉加载器如何处理这一段;has_loss 决定它是否成为需要预测的训练目标。Each message becomes four segments: a start marker, role, body, and end marker. Every segment carries type, text, and has_loss. The type guides the loader; has_loss determines whether the segment contributes supervised prediction targets.各メッセージは開始マーカー、役割、本文、終了マーカーの4断片になる。それぞれにtype、text、has_lossを持たせる。typeはローダーでの扱いを、has_lossは予測の学習対象に含めるかどうかを指定する。
这批导出把 assistant 正文和结束标记设为 1;system、user、tool 以及消息起始和角色标记设为 0。也就是说,模型学习怎么思考、回答和调用工具,但不用学习扮演环境、伪造工具返回。In this export, assistant bodies and end markers are marked 1. System, user, and tool content, plus message-start and role markers, are marked 0. The model is trained on its reasoning, answers, and tool calls—not on impersonating the environment’s responses.この出力ではassistantの本文と終了マーカーを1にし、system・user・toolの内容、開始マーカー、役割マーカーを0にする。モデルが学ぶのは推論、回答、ツール呼び出しであり、環境の応答を生成することではない。
静态图Static figure静止図
has_loss=0 不会把内容从输入中删掉。工具返回不计损失,后面的 assistant 仍然能读到它。若轨迹中保留了教师纠正提示,即使提示本身不计损失,也仍会影响后续输出;是否保留它,要在数据策略里另行决定。has_loss=0 does not remove content from the input. A tool result can carry no loss and still inform the next assistant action. The same applies to a retained teacher correction: masking its loss does not remove its influence. Whether to keep that guidance is a separate dataset decision.has_loss=0にしても入力から内容は消えない。ツール応答を損失対象外にしても、後続のassistantはそれを読める。教師の訂正指示も同様で、損失を除外しても影響は残る。指示を残すかどうかはデータ方針として別に決める。
一行包含未来的工具返回,也不代表前面的动作可以提前看见它。因果注意力只允许读取当前位置之前的内容;loss mask 则决定哪些位置计算损失。可见范围与监督范围是两件事。Storing later tool results in the same row does not let an earlier action see them. Causal attention restricts each position to its preceding context; the loss mask selects which positions contribute to the objective. Visibility and supervision are separate controls.同じ行に後のツール応答があっても、前の行動が先読みできるわけではない。因果的注意は先行する内容だけを参照可能にし、loss maskは損失を計算する位置を選ぶ。参照範囲と教師信号の範囲は別の制御である。
第四步:用四列封装,读回后再检查4. Package four columns, then read them back4. 4列にまとめ、読み戻して確認する
Parquet 是存储容器,聊天协议和监督位置由里面的 inputs 决定。本次文本格式固定四列;inputs 与 metadata 都是 JSON 编码后的字符串,不是 Parquet 的嵌套数组列。Parquet is the storage container. The inputs field determines the conversation protocol and supervised positions. This text-only export has four columns; inputs and metadata are JSON-encoded strings, not nested Parquet array columns.Parquetは保存用の容器であり、会話形式と学習対象の位置はinputsが定める。このテキスト形式は4列で、inputsとmetadataはJSON文字列として保存する。Parquetのネストした配列列ではない。
| 列名Column列名 | 物理类型Physical type物理型 | 内容Contents内容 |
|---|---|---|
images | binary | 空字节;本篇只讨论文本轨迹Empty bytes; this article covers text-only traces空のバイト列。本稿はテキスト軌跡を対象とする |
inputs | string | 有序的 type / text / has_loss 片段数组Ordered type / text / has_loss segmentstype / text / has_lossの順序付き断片 |
uid | string | 稳定的轨迹标识Stable trajectory identifier安定した軌跡識別子 |
metadata | string | 来源、划分与校验信息;不作为模型正文Provenance, split, and checks; not model text出典・分割・検証情報。モデル本文には入れない |
读取 inputs 时做一次 JSON 解析,就得到片段数组。下面以一个示意性的 assistant 文本展示消息边界;完整文件会按时间顺序接上所有消息。Parsing inputs once yields the segment array. The example below uses an illustrative assistant text to show message boundaries; a full row concatenates all messages in chronological order.inputsを一度JSON解析すると断片配列が得られる。以下はassistantの例文でメッセージ境界を示したもの。実際の1行には、全メッセージを時系列でつなげる。
[
{"type":"special_token", "text":"[CLS]", "has_loss":0},
{"type":"special_token", "text":"assistant\n", "has_loss":0},
{"type":"text", "text":"[reasoning + text + XML65 call]", "has_loss":1},
{"type":"special_token", "text":"[EOS]", "has_loss":1}
]
有两类检查不能省略:格式检查确认列类型、协议、工具配对、loss 标记与读回一致性;训练准入检查使用目标 tokenizer 和加载器,确认整条序列是否满足模型窗口及其他要求。Two checks are essential. Format validation checks column types, protocol, tool pairing, loss flags, and readback equality. Training admission uses the target tokenizer and loader to check the complete sequence against the model’s window and other requirements.省略できない確認は2種類ある。形式検証では列型、プロトコル、ツールの対応、lossの指定、読み戻した内容の一致を調べる。学習への受け入れ確認では対象のtokenizerとローダーを使い、全系列がモデルの文脈長などの要件に収まるかを見る。
完整轨迹往往比“只取最后一轮回答”长得多。前面那批 207 条轨迹中,有 4 条的离线文本 token 估算超过 131,072;它们被完整保留并单列,没有截断。该导出未运行目标训练接口的官方 compute_tokens Checker,所以格式验证通过,不等于这些长样本已通过训练准入。Full trajectories can be much longer than a final-answer-only sample. In the matched batch of 207 traces, offline text-token estimates exceeded 131,072 for four rows. They were retained intact and listed separately, not truncated. That export did not run the target training platform’s official compute_tokens Checker, so a format-valid row is not automatically training-admitted.完全な軌跡は、最終回答だけのサンプルより大幅に長くなりうる。先ほどの207本では、4行のオフライン推定値が131,072トークンを超えた。これらは切り詰めずに保持し、別途一覧化した。この出力では対象の学習基盤が提供する公式のcompute_tokens Checkerを実行していないため、形式の妥当性と学習への受け入れを区別する。
最后,检查模型实际在学什么Check what the model is actually learning最後に、何を学習するのかを確かめる
看一条训练样本,最好能回答三个问题:模型当时看到了什么,下一步要学会输出什么,输出之后环境实际返回了什么。原始轨迹、序列化协议和监督标记对齐之后,Parquet 才成为一份能解释、能复查的训练数据。A training sample should make three things clear: what the model could see, what it was supposed to produce next, and what the environment actually returned. Aligning the original trace, serialization protocol, and supervision flags makes the resulting Parquet inspectable and meaningful.学習サンプルから、モデルが何を見られたか、次に何を出力すべきだったか、その後に環境が何を返したかを確認できるようにする。元の軌跡、直列化プロトコル、教師信号の指定が一致してこそ、Parquetを理解し、検証できる学習データになる。
完整轨迹的生成与修复见For trajectory generation and repair, see軌跡の生成と修復については
Coding Agent 的生成与修复 →Generating and Repairing Coding-Agent Trajectories →Coding Agentの軌跡の生成と修復 →