工具調用大語言模型微調完整指南：基於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 底層實現的開發者參考。