工具调用大语言模型微调完整指南：基于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 底层实现的开发者参考。