swift-ft-cookbook · 微调训练配方与排障手册

来自 21 个真实训练 run 的一线配方与血泪判据（全谱系实录：https://modelscope.cn/models?name=theGAI ）。

一、21 法速查（谁配什么参数）

| 家族 | 方法 | 关键配置 | 适用 | |------|------|----------|------| | SFT | FullSFT / LoRA / QLoRA | --sft_type lora --lora_rank 8 --lora_alpha 32 | 指令跟随；大基座用 QLoRA（61B 也可 r=8 撬动） | | 偏好 | DPO / KTO / ORPO / SimPO / CPO | 成对数据（KTO 例外：单条好/坏） | 风格对齐；KTO 免成对标注成本减半 | | RL | GRPO / DAPO / GSPO / RLOO / REINFORCE++ | --rlhf_type grpo --reward_funcs accuracy --max_completion_length 768 | 可验证任务（数学/代码） | | 自进化 | ReFT | 采样→过滤→SFT 循环 | 免新标注的自我提升 | | 检索 | 嵌入 / 重排 | 嵌套列表数据格式（见三） | 句向量 / 排序 | | 多模态 | 视觉 / 语音 LoRA | messages 带 <image>/<audio> 占位 + images/audios 路径列 | VQA / ASR |

二、RL reward 恒零排障链（四层根因，逐层排查）

1. 奖励格式不匹配：swift 的 format 奖励要求严格 <think>...</think><answer>...</answer>，自由生成的模型不产出 → 换 reward_funcs: accuracy
2. 协议不兼容：reward_funcs: math 映射 MathORM 需要 infer_requests 协议参数，GRPO 直调 TypeError → 用 accuracy（走 solution 列）
3. ⚠️ 生成截断顶板（最隐蔽）：日志里 mean_length = min_length = max_length = max_completion_length 三值合一生效 ＝ 模型没写完就被截断，答案永远出不来 → 升 max_completion_length（256→768 实测 reward 0→0.2）
4. 数据缺 solution 列：accuracy 奖励靠标准答案列，数据集必须带（MATH-lighteval 有，gsm8k 用 #### 格式需抽取）

reward 0.2 ≈ 4B 模型在 MATH 上的真实采样正确率——这就是"学习信号活了"的健康基线。

三、嵌入/重排数据格式（八轮格式考古定案）

swift 的 TextCapsEmbPreprocessor 要求 positive_messages/negative_messages 是列表的列表：

{"messages": [{"role":"user","content":"问题"}],
 "positive_messages": [[{"role":"user","content":"正例文本"}]],
 "negative_messages": [[{"role":"user","content":"负例文本"}]]}

七种直觉格式（平铺列表/字符串/assistant 角色…）会被静默滤光（1500→0），不报错。硬负例构造：负例取自其他问题的正例回答。

四、ReFT 拒绝采样配方

四级答案抽取链（逐级回退）：\boxed{} → <answer> 标签 → #### 分隔 → 末行数字。校验通过的采样进 SFT 集；π₁ 可回灌再采样迭代。

五、"假异常"判别（别把数据规模问题当管线 bug）

• loss 精确归零 + token_acc 精确满分 ＝ 微样本数据集的必然（几十步背熟），不是管线挂了
• 偏好准确率 ≈50% ＝ 随机水平：训练不充分或数据无信号，与跟踪链路无关
• 判别法：看 run 的数据行数 tag（冒烟集 1~29 行 vs 正式集 7k 行，一眼分辨）

六、训练过程六要素（每要素都要可追溯）

①数据集（id+行数）②配方超参（args.json 随产物）③指标曲线（逐步日志）④基座谱系（README front-matter base_model）⑤框架版本 ⑥产物本体。缺一不可复现。

七、发布验证门禁（四项，无 ALL PASS 不上传）

1. SVG/XML 合法 + 几何属性必须数值（防"文字入属性"暗伤——浏览器会静默不渲染）
2. 文字碰撞检测（CJK 1.0em/ASCII 0.62em 估宽做边界框相交）
3. 本地引用存在性
4. CDN URL 全量 HTTP 探活（200+image 才放行）

实例仓库

21 方法各有真数据 run 实录：theGAI/Qwen3.5-4B-GRPO-*-MATH-fix（修复版含根因叙事）、theGAI/Qwen3.5-4B-ReFT-gsm8k、theGAI/gte-modernbert-LoRA-embed-zhihu 等 29 仓。