工具呼叫大語言模型微調完整指南：基於XYZ-Aquila-SFT與Qwen3

本教程展示瞭如何為工具呼叫大語言模型構建一條完整的監督微調（SFT）流水線，資料來自 XYZAILab 釋出的 XYZ-Aquila-SFT 資料集，基礎模型使用 Qwen/Qwen3-0.6B。整個實現基於 Hugging Face Transformers、PyTorch、PEFT 和 Accelerate，並提供了從資料流式載入、軌跡解析、語料統計、ChatML 渲染、自定義資料集與 collator，到 LoRA 訓練和評估的完整程式碼。

流水線首先以流式方式讀取 400 條英文樣本，檢查資料集的欄位結構，包括每個樣本的問題、答案、宣告的工具呼叫數量以及多輪軌跡。作者實現了巢狀安全的 JSON 掃描器和正則解析器，從助手訊息中提取符合 Qwen 格式的工具呼叫，同時保留 reasoning block（推理塊）和 observation（觀察）資訊。每個樣本被轉換為一個 Trajectory 物件，並透過與資料集宣告的工具呼叫數量進行對比，驗證解析器的準確性。

接著，作者對語料進行了統計分析，包括每條軌跡的工具呼叫次數、訊息深度、字元長度分佈、各工具的呼叫頻率以及引數鍵的使用情況，並用直方圖和柱狀圖進行視覺化。分析顯示工具呼叫分佈具有長尾特徵，最長的 10% 軌跡佔用了相當比例的字元，這對後續的截斷策略和訓練效率有重要影響。

在格式轉換方面，教程展示瞭如何從系統訊息中提取嵌入的工具 schema，轉換為結構化 tools 列表，並支援逆向重組。為了確保轉換不丟失資訊，作者比較了原始系統訊息與重組後的系統訊息，如果出現模板漂移，就會使用原文中的 verbatim tools_suffix 進行渲染。之後，作者沒有直接使用 Qwen3 的 apply_chat_template，而是手動渲染 ChatML 格式，因為 Qwen3 的模板會刪除除最後一輪外的所有 assistant turn 中的推理塊，這會破壞訓練時要學習的推理監督訊號。手動渲染可以精確控制每個 token 的標籤，並且僅對 assistant 部分的 token 計算損失，system 和 user 部分的 token 使用 -100 忽略。

資料準備階段實現了自定義 PyTorch Dataset 和 collate 函式，對序列進行右側填充，並設定截斷策略。訓練配置採用 LoRA（rank=16），學習率 1e-4，梯度累積 8 步，最大序列長度 2048，訓練 30 步，並使用餘弦退火學習率排程。最終在訓練前後對工具呼叫預測進行評估，並匯出轉換後的資料集和語料統計資訊，方便後續實驗。

總體來說，這篇教程為工具呼叫 LLM 的微調提供了一個可復現的工程化示例，特別強調了在資料解析、格式渲染和損失掩碼等細節上避免常見陷阱，適合希望深入理解 SFT 底層實現的開發者參考。