【2026 最新】Trajectory2Gym 教學：成功 Trace 怎麼檢查？從可見證據到互動權重（CPU 練習）

你讓 Agent 查訂單，最後答案對了，就把整段紀錄收進訓練集。可是，它當時真的看得到訂單編號嗎？這篇 Trajectory2Gym 教學，帶你在開始微調前，先檢查示範到底教了什麼。

本文寫給第一次整理 Agent 訓練資料的讀者。前半用查訂單的小故事理解；後半需要已安裝 Python 的電腦。你會看懂可見資訊、學習目標與互動權重，再產出一份合成資料檢查報表，無須先下載模型權重。

本文於 2026 年 10 月 28 日核對官方程式，固定 revision da4fa739e69ec8d2da64cf76a2747ec06036bab9。AlphaLab 在 macOS、Python 3.11 執行了官方小型結構選擇示範及下方投影／權重練習；Linux 完整回歸測試與模型訓練未在本次執行。這三種成果，後面分開驗收。

先說結論：可學示範＝可見證據＋合格目標＋合理權重

把示範當成「師傅教徒弟的工作錄影」。師傅做對是一件事，徒弟能否從鏡頭裡的線索學會，是另一件事。可學示範＝可見證據＋合格目標＋合理權重：鏡頭要拍到必要線索，答案要有依據，同一堂課也別因剪成更多片段而重複算學分。

SFT（監督式微調）像拿示範答案練習：模型依前文預測後面的目標 token，答得不符就產生 loss，也就是訓練用的誤差。Hugging Face 的 SFT 文件說明對話資料與 assistant-only loss；但「只學 assistant」和「只學有根據的 assistant 決策」仍是兩層檢查。

Trajectory2Gym 論文於 2026 年 10 月 24 日提交，提出從互動結構、決策依據到權重分配的一套方法。本文不把它當成新的 Agent 聊天介面；你要建立的是送進訓練之前的資料檢查流程。若不熟悉模型怎麼拿工具工作，先讀 Agent Harness 白話解說。

一、Trajectory2Gym 教學：先分清五個零件

• Trace／軌跡：一件工作從請求、工具動作到結果的完整紀錄，不只是最後答案。
• Policy view／學習者畫面：把完整紀錄投影成 Agent 當時有權看到的訊息，像從監控全景切回當事人的視角。
• Target admission／答案入場審查：決定哪個動作有足夠執行證據、可見依據與工作流程支持，適合當學習目標。
• Supervision mask／計分遮罩：標記哪些 assistant 決策要計算模仿誤差。留作上下文的訊息，不必都拿來計分。
• Parent／原始互動：同一件語意完整的工作。它可能轉成多列訓練資料；列數是包裝方式，不能直接當成工作數。

還有一個容易漏掉的問題：資料是否示範了「查詢失敗後補問、重試、再完成」？只收一大堆一步答完的範例，和收齊多步依賴，是不同的資料設計。官方另有結構支援選擇器，補足不同互動路徑的示範；下面的小型官方例子就檢查這一層。

二、先看查訂單：答案正確，線索卻在鏡頭外

想像以下刻意編寫的假例子：使用者只說「用 demo@example.com 查我的訂單」。收集系統私下查後台得到 O-42，Agent 接著說「我要查 O-42」。後台確實有這張訂單，但請在 Agent 決策前把錄影按暫停：它能看到的使用者請求只有信箱。

這時要問的不是 O-42 是否真的存在，而是這個特定編號從哪一則先前可見訊息進來。若來自使用者明確提供，或它自己呼叫工具後取得的公開回單，證據鏈可以往前追；若只在收集者的私有結果，就應列成待審目標。

官方 policy_view.py會依訊息角色與工具呼叫歸屬，移除私有外部行為及其回覆，同時保留 assistant 決策與完整證據。投影不等於修正答案：把私有訊息拿走後，那句「我要查 O-42」仍在，所以還要做目標入場審查。這不是任意搜尋並刪除所有 user 或 tool 訊息。

若一次工具呼叫回錯誤，原始錯誤可以留下，幫助模型理解下一步為何補問或重試；是否模仿該動作，另由遮罩決定。也別把事後才拿到的成功結果倒灌進先前決策的輸入：時間順序本身就是依據的一部分。

三、用現有 Python 跑投影與權重練習

先固定程式版本。在一個新的練習資料夾執行以下指令。這一節使用官方純 Python 投影函式與合成訊息，沒有呼叫訂單服務。先確認 python3 --version；官方要求 Python 3.10 以上，本篇執行環境為 3.11。

git clone https://github.com/yihaohu0118/Trajectory2Gym.git
cd Trajectory2Gym
git checkout da4fa739e69ec8d2da64cf76a2747ec06036bab9
python3 --version

將下列內容存成倉庫根目錄的 practice.py，再執行 python3 practice.py。這是 AlphaLab 的教學檢查程式，不是官方認證器。它只驗證可見訊息投影與一組已給定 token 數的權重算式；O-42 的問題由明確的人工標記指出，不會自動證明任意動作是否合理。

import json
from collections import defaultdict
from pathlib import Path
from trajectory2gym.training.policy_view import project_sft_row

# All identifiers and messages below are synthetic.
row = {'messages': [
    {'role': 'user', 'content': '查詢我的訂單，信箱 demo@example.com'},
    {'role': 'user', 'content': '', 'tool_calls': [
        {'id': 'private-1', 'function': {'name': 'backend_lookup', 'arguments': '{}'}}]},
    {'role': 'tool', 'tool_call_id': 'private-1', 'content': 'order_id=O-42'},
    {'role': 'assistant', 'content': '我要查 O-42'}
]}
projected, receipt = project_sft_row(row)
# Projection preserves decisions; this is NOT a target-certification engine.
assert len(projected['messages']) == 2
assert len(projected['evidence_messages']) == 4
assert projected['messages'][-1] == row['messages'][-1]
rows = [('A', 10), ('A', 20), ('A', 30), ('B', 20)]
totals = defaultdict(int)
for parent, tokens in rows:
    totals[parent] += tokens
M, P = len(rows), len(totals)
report = []
parent_mass = defaultdict(float)
for parent, tokens in rows:
    coefficient = (M / P) * tokens / totals[parent]
    contribution = coefficient / M
    parent_mass[parent] += contribution
    report.append({'parent': parent, 'supervised_tokens': tokens,
                   'row_coefficient': coefficient,
                   'normalized_mass': contribution})
assert all(abs(v - 0.5) < 1e-12 for v in parent_mass.values())
result = {'synthetic_only': True, 'removed_messages': receipt['removed_messages'],
          'assistant_decisions_preserved': True,
          'manual_flag': 'O-42 is absent from the preceding visible request',
          'rows': report, 'parent_mass': dict(parent_mass)}
Path('audit-demo.json').write_text(json.dumps(result, ensure_ascii=False, indent=2))
print(json.dumps(result, ensure_ascii=False, indent=2))

打開 audit-demo.json，你應找到兩筆 removed_messages、assistant_decisions_preserved: true，以及 A、B 各為 0.5 的 parent_mass。這些是本次合成輸入的可核對輸出；換成自己的資料後，仍要逐個檢查工具歸屬、決策順序與識別碼來源。

這支程式省略了 tokenizer、聊天模板、真實工具執行與目標認證。因此 10、20、30、20 是手填練習值，不是對真實訊息算出的 token 數。正式流程須由 官方權重修正程式讀入通過檢查、且綁定資料雜湊的 token audit；別把這份小報表改名就交去訓練。

四、Trajectory2Gym 教學：三列對一列，手算權重

假設互動 A 展開成三列，互動 B 只有一列。若每列先各自算平均誤差，再把四列等權平均，A 合計占四分之三、B 占四分之一。被切得較細的那件事，便得到比較大的總份額。這描述的是指定平均方式，不代表所有訓練器都用同一種 reduction。

Parent normalization 先讓兩件完整互動各占一半，再在同一個 parent 內，依各列的合格目標 token 數分配。A 的三列為 10、20、30，共 60；所以它們占整體的 1/2 × 10/60 = 1/12、1/6、1/4。B 唯一一列占 1/2，四份加起來正好是 1。

對照官方 WORKFLOW 權重定義，列係數是 ωᵢⱼ = (M/P) × nᵢⱼ / Σⱼ nᵢⱼ。M 是列數，P 是 parent 數，n 是已審核的目標 token 數。此例 M/P＝2，因此報表列係數依序為 1/3、2/3、1、2；再除以四列，便得到前述份額。

最常見的誤解，是把每列都設成 1／該 parent 的列數。那會讓 A 的三列等分，並未按 10、20、30 的目標 token 數分配。另一個誤解是「每個 parent 等權，所以梯度一定一樣大」；係數總額相同，不代表每段內容的誤差與梯度相同。

五、到 Linux CPU 環境跑官方合成測試

完整套件測試與前一節的小練習分開。官方 README 指定完整回歸套件使用 Linux、PyTorch 與符號連結支援，CI 固定 Python 3.11。已有這類環境的讀者，可依 官方 CI 設定核對安裝與執行。

在已切到上述 revision 的倉庫內，用 Python venv隔離練習依賴。以下是 Linux CPU 路徑；它會下載 Python 套件與 CPU PyTorch，不會載入模型 checkpoint。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-ci.txt
python -m pip install torch==2.7.0 --index-url https://download.pytorch.org/whl/cpu
python -m pytest -q tests
python examples/structural_support_demo.py

官方 structural_support_demo.py用四筆假互動展示選擇結果：depth-1 選 demo-0、demo-2；depth-2 再包含 demo-1、demo-3。AlphaLab 在本次 macOS 執行得到同一組輸出；這份示範只檢查合成案例的結構支援選擇與巢狀關係。完整測試應另存終端輸出與退出碼，不能用這個小例子替代。

如果遇到 PyTorch 安裝失敗，先核對 Python 版本、Linux 架構與 wheel 相容性；若是符號連結錯誤，檢查檔案系統支援。若測試紅燈，先保留失敗名稱與 revision，不要繞過斷言後再稱測試通過。

六、把練習接成資料檢查報表

• 不可見證據：記 parent ID、決策序號、參數值、前綴可見來源與原始證據位置。找不到來源就標成待審，不補寫一段從未出現的工具結果。
• 缺失依賴：看查詢、觀察、確認、修改是否按要求發生；有成功旗標，也要檢查工作要求與順序。
• 權重異常：列出每個 parent 的子列數、合格 token 總數及正規化總份額，特別查零 token、缺 parent、重複列與 tokenizer 變更。
• 版本綁定：保存輸入 SHA-256、程式 revision、模板與 tokenizer 版本。改模板後重新計數，別沿用舊係數。

你今天交出的檔案，應能回答「哪個決策為何被保留」與「哪件事合計占多少」。這和 Agent 可觀測性的留痕互補，也和 評測洩漏檢查不同：本篇檢查示範當下的可學性，後者檢查答案是否污染了考試。

要接到完整 SFT，還需要選定模型、可用的訓練硬體、符合權利範圍的資料、原生模板與真正通過的 train-ready view。官方訓練流程明列 assistant-only loss、列權重欄位與 global_batch_parent_mean 等選項；只把 JSONL 丟進通用 Trainer，並不足以證明採用了同一目標函數。這一篇的 CPU 產物是資料檢查結果，不是訓練完成的模型。

常見問題：八個新手先講答案

成功 Trace 能直接拿來訓練嗎？

先做決策審查。結果成功只提供終點資訊；每個目標仍須對上先前可見依據與工作要求。

Policy view 會自動修好錯誤答案嗎？

不會。本次練習刻意保留了 O-42 那句 assistant 決策；投影與目標認證分開執行。

Mask 掉的訊息要全部刪掉嗎？

分開看。目標遮罩決定哪些決策計分；可見且有用的上下文可以保留，私有資訊則由投影處理。

Parent 就是每個 user 回合嗎？

不是這樣定義。這裡指原始語意互動，一件工作可以跨多個 user 與工具回合。

等權表示長互動不再有影響嗎？

不是。控制的是完整互動的目標函數份額；它的內容、誤差與 token 仍參與學習。

跑 CPU 示例要下載完整模型嗎？

這兩個合成練習不用。官方完整 CPU suite 需要套件依賴；模型訓練與 benchmark 另有資源需求。

本篇的小報表能當官方資料認證嗎？

不能。它沒執行真實工具、token 審核與完整目標認證，人工旗標也不是語意證明。

要先重跑論文分數才有用嗎？

可以先改善資料檢查。先找出一個看不到證據的動作，再確認每個 parent 的份額；能力提升要用另外設計的訓練與評測驗收。

給新手的三個重點

• 先停在決策前一刻：只拿當時可見的內容替答案找依據。
• 保留上下文與計算模仿誤差是兩件事；投影、認證與遮罩分別驗收。
• 數列數，也數 parent：把包裝方式和訓練份額拆開，才知道模型正在多學哪件事。