ai-llm

LLM 适配

调整模型的权重，让它更擅长某项任务：监督微调（SFT）、参数高效微调（PEFT：LoRA、QLoRA、DoRA）、全量微调、蒸馏与压缩恢复，以及决定这些方法能否奏效的数据集和分词器相关工作。

判断是否需要适配（提示词 vs 思考 vs RAG vs 微调 vs 后训练）不属于本技能范围。请先使用 ai-architecture-advisor 中的单一构建阶梯；确认其建议为“微调”或“蒸馏”后，再使用本技能。

何时使用本技能

• 配置 LoRA 或 QLoRA：秩、alpha、alpha 约定、目标模块、学习率
• 选择全量微调还是 PEFT，或在 LoRA 效果停滞时升级方案
• 构建 SFT 数据集：聊天模板、提示词 token 的损失屏蔽、打包、污染控制
• 将大型教师模型蒸馏为较小的学生模型，或在剪枝后恢复质量
• 诊断部分输入上的分词器切分、词元拆分率或异常词元问题
• 判断微调能否带来回报（盈亏平衡所需的用量和稳定性）

范围边界

需求	前往
选择哪种方案；模型和提供方选择；MoE 还是稠密模型	ai-architecture-advisor
偏好与 RL 后训练：RLHF/PPO、DPO、GRPO、RLVR、奖励模型	ai-post-training
评测设计、评判器校准、阈值、基准测试框架	ai-evals
提示词、结构化输出、模式约束	ai-prompt-engineering
上下文组装与记忆	ai-context-layer
RAG 与 Agent	ai-rag、ai-agents
服务、量化格式、剪枝运行时支持	ai-llm-inference
本地运行与 GGUF 打包	ai-local-model-ops
部署、推出、监控、模型/提供方迁移	ai-mlops
API 成本模型、缓存、自托管盈亏平衡点	ops-cost-optimization
预训练、分词器构建、缩放定律	ai-pretraining、ai-scaling-laws
多 GPU 并行	ai-distributed-training
Hugging Face TRL 训练器细节	外部 huggingface-skills: 插件

默认工作流

1. 确认差距属于行为问题，而非知识或推理问题。 缺失的事实应通过检索补充，多步逻辑应通过思考预算处理（参见顾问阶梯）。只有当提示词和 RAG 调整无法解决，且差距涉及稳定行为、格式或风格时，才进行微调。
2. 先构建评估，再构建数据集。 按切片留出任务集，使用相同随机种子记录未调优模型的基线，并添加一个域外遗忘集。
3. 构建数据集。 将重复和近似重复的源示例分组，然后在扩增或合成生成之前，将完整分组分配到训练集或评估集；检查是否仍有重叠。应用模型自身的聊天模板，并在训练和服务时使用相同模板（包括生成提示词和轮次结束标记）：通过训练流程和服务引擎分别渲染一个示例，并比较 token ID，因为模板不匹配不会报错，看起来就像微调毫无效果（§5E）。仅计算助手 token 上的损失（对提示词 token 设置 ignore_index=-100）。打包不得让注意力或损失跨越示例边界。参见 dataset-formatting-guide.md。
4. 从 PEFT 开始。 对所有线性层使用 LoRA 或 QLoRA；记录秩、alpha、alpha 约定、目标模块和有效批量大小（微批量 × 累积步数 × world size）。可训练参数占比 = 适配矩阵的 Σ r·(d_in + d_out) ÷ 总参数量；请针对自己的模型计算，而不是引用某个百分比。
5. 仅在有证据时升级。 如果 LoRA 在难度较高、与预训练领域相距较远的领域停滞，请遵循 fine-tuning-recipes.md 中的升级顺序，并保留遗忘评估。
6. 蒸馏步骤。 在调用教师模型前，确认其条款允许训练竞争模型，并记录许可证。然后根据 advanced-llm-patterns.md，选择你能够获取的监督信号（logits、生成文本或推理过程）。
7. 发布门禁。 针对确切的服务产物和配置运行门禁：如果服务时会单独加载适配器，就单独测试适配器；如果部署路径会合并并量化产物，就测试合并并量化后的产物。只有在量化后才出现的差异，不属于微调的差异（合并与量化）。根据任务切片和遗忘切片选择发布检查点；验证损失仅用于提前停止时对检查点排序。按切片、符合架构的比例、工具调用率和遗忘集与基线进行比较。将部署交给 ai-mlops。

快速参考

决策	默认选择	何时更改	避免
方法	LoRA/QLoRA，目标为所有线性层	在难度较高的领域中，尝试更高秩和 DoRA 后仍停滞 → GaLore，然后进行全量微调	直接跳到秩 256
内存	基础模型无法以 BF16 装入时使用 QLoRA	基础模型能够装入 → 普通 LoRA	按活跃参数量估算 MoE（所有专家都会加载）
多 GPU	冻结的基础模型能装入一块 GPU 时使用数据并行	基础模型无法装入 → FSDP / ZeRO-3（内存模型）	不加判断地分片
损失	仅计算助手 token	对原始文本进行类似预训练的持续训练	在系统和用户 token 上训练
蒸馏	基于教师模型输出的序列 KD	能访问 logits → 软标签 KD；有推理轨迹 → 轨迹 KD	使用条款禁止训练竞争模型的任何教师模型
投资回报	使用 ROI 计算器	用量大且领域稳定	为会变化的知识进行微调

常见陷阱

• 为本应通过检索获取的信息进行微调，或为可通过增加思考预算弥补的推理缺口进行微调
• 引用 LoRA 参数占比，而不针对实际模型计算 Σ r·(d_in + d_out)
• 对提示词 token 计算损失，或打包样例，导致注意力跨越边界
• 将近乎重复的源样例拆分到训练集和评估集，或在分配源分组到各数据集之前进行数据增强
• 使用条款禁止训练竞品模型的托管模型进行蒸馏
• 根据困惑度评估压缩或调优后的模型；推理、符合 schema 的输出和工具调用切片会最先出问题
• 将过于理想的评估分数视为成功，而不是数据泄漏警报
• 按活跃参数估算 MoE 微调规模，或忽略路由器逐渐偏向少数专家的情况

训练器功能、支持的损失和框架维护状态经常变化。

1. 在承诺使用某种方法前，请查阅训练器自身的文档，确认支持的方法和损失（例如，是否内置了偏好损失）。
2. 请查阅模型卡和 config.json，确认架构信息（层数、隐藏层大小、KV 头数、MoE 专家数量），不要凭记忆判断。
3. 开始新工作前，请检查框架的仓库状态；有些微调库已停止维护。

脚本

此技能不附带脚本。单次调用成本估算器位于 ops-cost-optimization（scripts/cost_estimator.py），离线提示词回归运行器位于 ai-evals（scripts/prompt_eval_runner.py）。

导航：参考资料

• 微调方案：SFT、指令微调、LoRA/QLoRA 配置、PEFT 方法系列、全面微调升级、多 GPU 和 MoE 说明、安全数据、中期训练、数据反馈循环、污染控制
• 数据集格式指南：指令、聊天和转换格式；数据集规范；损失掩码（ignore_index=-100、第一个 EOS 不屏蔽）；在样例边界内打包。ai-pretraining 将 SFT 格式处理交由此处负责。
• 适配模式：特定任务调优、合成数据、知识蒸馏（logit、序列、on-policy、推理依据、先剪枝再蒸馏、推理轨迹），并设有教师模型许可门槛；压缩检查清单、多任务学习。ai-architecture-advisor 负责决定是否蒸馏；ai-pretraining 将蒸馏交由此处负责。
• 分词器诊断：词元化率和奇偶性、异常和训练不足的词元、领域碎片化、数字词元化、错字脆弱性。构建 BPE 分词器属于 ai-pretraining。
• 多模态模式：视觉、音频和文档工作流。此内容不属于适配范围；在确定负责人之前，暂时保留在此处。

已从此技能移出的内容：后训练 → ai-post-training；评估模式 → ai-evals；成本分析 → ai-api-cost-guide；部署、迁移和监控 → ai-mlops；构建阶梯和模型选择 → ai-architecture-advisor。

模板

• 微调配置：可复现的 SFT/LoRA 配置记录
• SFT 聊天数据集 和 指令数据集：最简记录格式
• 数据质量：训练数据的去重、PII 和质量检查
• 微调 ROI 计算器：适配投资的盈亏平衡分析

外部来源

有关配方（LoRA、QLoRA、DoRA、rsLoRA、IA³、LoRA 与完整微调的比较、蒸馏）背后的论文和文档，以及用于核查当前事实的提供商查询页面，请参阅 data/sources.json。

学习循环

如果以往的决策或陷阱与当前任务相关，请在存在时查阅 learnings.consolidated.md；仅在需要了解历史记录或将其作为可用的备选文件时，才使用 learnings.md。否则跳过这两个文件。

应用相关经验后，如果遇到了值得记住的模式、值得避免的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目符号。不要修改 SKILL.md 本身。