Parable-Qwen3-4B-Claude-Fable-5-GGUF训练原理揭秘:QLoRA微调、Agent轨迹蒸馏与Loss Masking完整指南
Parable-Qwen3-4B-Claude-Fable-5-GGUF训练原理揭秘:QLoRA微调、Agent轨迹蒸馏与Loss Masking完整指南
想搞懂 Parable-Qwen3-4B-Claude-Fable-5-GGUF 这个 4B 本地编码模型是怎么炼出来的吗?它基于 Qwen3-4B,通过 QLoRA 微调 + 真实 Agent 轨迹蒸馏 + Loss Masking 三大技术,把大模型的多步规划与工具使用习惯蒸馏进一个仅 2.5 GB 的小模型。本文带你完整拆解它的训练原理,最后附量化版本选择指南。
一、这个模型是什么?为什么值得关注 🔍
Parable-Qwen3-4B-Claude-Fable-5-GGUF 是一个"带 Agent 直觉"的 4B 本地编码模型:
A 4B local coding model with agent instincts. Planning, tool habits and terminal reasoning distilled from real Claude Fable 5 agent sessions, not synthetic Q&A. Runs on ~2.5 GB of RAM. ——README.md
它的三大亮点:
| 特性 | 说明 |
|---|---|
| ⚡ 真的会回答 | 基础 Qwen3-4B 在 34% 的普通问题上把全部预算耗在 <think> 里却不返回答案;本模型在 34/34 问题上都给出回答,且推理文本少 140 倍 |
| 🤖 Agent 化推理 | 在真实多步 Agent 会话上训练,规划、工具选择、终端工作流输出更结构化,而非临时发挥 |
| 💾 小到可以常开 | Q4_K_M 仅 2.5 GB,笔记本、旧显卡、普通台式机都能离线跑,代码不离开本机 |
👉 训练细节的权威出处:README.md「Model details」
二、QLoRA 微调:4B 模型如何低成本"开窍"
2.1 核心配方一览
本项目没有在满血参数上做全量微调,而是采用 QLoRA(Quantized Low-Rank Adaptation)——一种"冻结大权重 + 只训练低秩旁路"的轻量微调方式。官方记录的关键参数如下(出自 README.md):
| 参数 | 取值 | 通俗含义 |
|---|---|---|
| 量化方式 | nf4(NormalFloat4) | 基础权重以 4-bit 存储进显存,大幅压低内存占用 |
| 秩(rank) | r16 | 低秩适配矩阵的秩为 16,控制可学容量的"宽度" |
| 缩放系数 | alpha 32 | LoRA 更新量的缩放因子,2 倍于秩是常见配比 |
| 作用目标 | all-linear | 所有线性层都挂 LoRA 旁路,覆盖面更广 |
| 通用指令重放 | 30% 混合 | 混入 30% 通用指令数据,防止"学了 Agent 忘了说人话" |
| 种子平均 | seed-averaged weights | 多个随机种子分别训练后对权重取平均,结果更稳 |
| 合并比例 | scale 0.6 | v2.1 重新校准后的合并比例,避免"过冲" |
2.2 为什么选 QLoRA?
- 显存友好:nf4 量化让 4B 模型的权重以 4-bit 驻留显存,微调成本远低于全参微调;
- 改动可控:LoRA 旁路参数量极小,且合并时可以用 scale(本项目为 0.6)精细控制"新习惯"注入的强度;
- 多种子平均:单次小样本微调容易过拟合到特定轨迹风格,seed-averaged 能有效平滑这种波动。
三、Agent 轨迹蒸馏:用"真作业"代替"合成题"
3.1 数据来源:真实 Agent 会话
大多数"教模型当 Agent"的做法是合成问答——自己造一批"用户问题 + 模型操作"的对话。Parable 反其道而行:直接蒸馏真实 Claude Fable 5 Agent 会话。训练数据来自两个数据集(见 README.md 元信息):
Glint-Research/Fable-5-traces:真实 Claude Fable 5 Agent 会话轨迹(AGPL-3.0)Roman1111111/gpt5.5-terminal:终端操作转录(MIT)
数据在入库前经过去重,并针对报告用的基准做了去污染(decontaminated),避免"背题"式的分数虚高。
3.2 v3.1 的升级:执行验证 + 模型自举(Self-Soup)
2026-08-11 发布的 v3.1 在语料上做了关键升级(README.md「v3.1」):
- 保留 v2 的 Agent 轨迹不变;
- 用上一版模型自己生成 1,807 个解题方案;
- 执行验证:只有代码真正在测试上跑通的方案才被保留——"跑不通的聪明"直接剔除;
- 对两个种子的模型做 soup(权重融合),按 v2.1 的规模合并。
结果:v3.1 在全部 4 项执行基准上追平或超过基础 Qwen3-4B(上一版在其中 3 项上落后)。官方提示:如果你拉取的是 2026 年 8 月 11 日之前的版本,请重新拉取。
💡 这就是"执行验证"的价值:不看模型"说得多对",只看代码"跑没跑通",从源头保证蒸馏进来的都是可靠行为。
四、Loss Masking:为什么只对"回答"部分计算损失
4.1 Completion-only Loss Masking 是什么
微调时,训练损失(loss)衡量"模型预测下一个 token 有多准"。如果整条会话(用户提问 + 工具输出 + 模型回答)都参与计算损失,模型会连用户的问题、环境的返回都被要求"预测",训练信号被严重稀释,还可能学会模仿环境噪声。
本项目的做法是 completion-only loss masking(仅对模型生成部分计损,README.md):
[ 用户提问 ] [ 工具调用/终端输出 ] [ 模型规划与回答 ]
loss = 0 loss = 0 loss = 1 ✅ 只学这里
效果:
- ✅ 训练目标精准聚焦在"怎么规划、怎么选工具、怎么写代码"上;
- ✅ 避免模型去"预测"它本不该生成的内容;
- ✅ 这是 Agent 微调中公认的防退化手段之一。
4.2 配套保险:30% 通用指令重放
只喂 Agent 轨迹有个副作用:模型会变得"太专",日常对话能力退化。所以训练时混入 30% 通用指令数据回放(replay mix),让模型在获得 Agent 习惯的同时保持正常的对话行为。
五、训练成果:基准测试全解读 📊
5.1 执行基准(v3.1,贪心解码,Q4_K_M 构建)
| 基准 | 基础 Qwen3-4B | Parable v3.1 | 变化 |
|---|---|---|---|
| HumanEval | 73.2 | 74.4 | 📈 +1.2 |
| HumanEval+ | 68.3 | 68.3 | ➖ 持平 |
| MBPP | 69.0 | 72.8 | 📈 +3.8 |
| MBPP+ | 59.8 | 63.8 | 📈 +4.0 |
| 留出 Agent 轨迹 loss | 2.155 | 1.446 | 📉 越低越好 |
5.2 对话行为(v2.1 构建测量,训练目标与对话行为不变,沿用至今)
| 指标 | 基础 Qwen3-4B | Parable |
|---|---|---|
| 34 题回答套件答出数 | 27/34 | 34/34 |
| BFCL simple_python | 95.3 | 92.3 |
| BFCL multiple | 94.5 | 90.0 |
📌 完整评测表与说明见 README.md「Evaluation」
怎么选?官方建议(README.md):
- 要结构稳定、每次都有可靠回答的本地 Agent/编码工作 → 选 Parable;
- 追求极致 function calling 精度的工具调用框架 → 选基础模型(它在 BFCL 上仍有几个点的优势)。
六、量化版本怎么选 + 快速上手 🚀
6.1 五个量化版本一览
仓库提供了 5 个 GGUF 量化文件(README.md「Files」):
| 文件 | 量化 | 大小 | 适用场景 |
|---|---|---|---|
| Parable-Qwen3-4B-Claude-Fable-5-GGUF-Q4_K_M.gguf | Q4_K_M | 2.5 GB | ⭐ 官方推荐,内存友好 |
| Parable-Qwen3-4B-Claude-Fable-5-GGUF-Q5_K_M.gguf | Q5_K_M | 2.9 GB | 精度与体积平衡 |
| Parable-Qwen3-4B-Claude-Fable-5-GGUF-Q6_K.gguf | Q6_K | 3.3 GB | 追求更高精度 |
| Parable-Qwen3-4B-Claude-Fable-5-GGUF-Q8_0.gguf | Q8_0 | 4.3 GB | 接近半精度 |
| Parable-Qwen3-4B-Claude-Fable-5-GGUF-F16.gguf | F16 | 8.1 GB | 仅供重新量化,日常不用 |
新手建议:直接选 Q4_K_M——2.5 GB 的体量,笔记本和旧显卡都轻松跑得动,且全部基准数据就是用它测的。
6.2 一条命令跑起来
如果你已安装 Ollama,一条命令即可运行 Q4_K_M 版本:
ollama run hf.co/AnkitAI/Parable-Qwen3-4B-Claude-Fable-5-GGUF:Q4_K_M
没有 Ollama?也可以 git clone 仓库后把 GGUF 文件导入 LM Studio 等本地推理工具使用:
git clone https://gitcode.com/hf_mirrors/AnkitAI/Parable-Qwen3-4B-Claude-Fable-5-GGUF
⚠️ 注意:评测时"所有行均关闭 thinking 模式"。本模型本身就不依赖思考模式开关,直接提问即可得到回答。
七、总结:三大技术要点回顾 ✅
| 技术 | 一句话总结 | 关键参数/事实 |
|---|---|---|
| QLoRA 微调 | 4-bit 冻结权重 + 低秩旁路,小显存训出大能力 | nf4 / r16 / alpha 32 / all-linear / 合并 scale 0.6 |
| Agent 轨迹蒸馏 | 用真实 Claude Fable 5 会话而非合成 Q&A,v3.1 加入执行验证的自举数据 | 1,807 个通过测试的方案,soup 两种子 |
| Loss Masking | 只给"模型回答部分"算损失,训练信号不被提问和工具输出稀释 | completion-only masking + 30% 通用指令重放 |
这套"QLoRA 低成本微调 + 真实轨迹蒸馏 + 精准损失掩码"的组合拳,展示了在受限算力下把小模型"调教"成可靠 Agent 的完整路径——这正是其方法报告《Agent-Trace Fine-Tuning of Small Language Models under Constrained Compute》(Zenodo, 2026)所验证的核心。
📎 延伸阅读:README.md 完整文档 | 方法与许可说明见 README.md「Provenance & licensing」