quantized-export

量化导出

checkpoint-promotion 交接 PROMOTE 判定后的最后一站：一个通过了四阶段门禁的检查点，在按目标运行时导出为正确格式、并验证导出后仍能正常工作之前，仍然不算已部署。REJECT 判定永远不会到达这一技能——导出只从被提升的检查点开始。

输入： 一个被提升的检查点（或 LoRA 适配器），加上目标部署环境——GPU 类别、服务栈，以及是否涉及长上下文/代码/数学工作负载。 输出格式： 按所选格式导出的产物，加上一份冒烟测试差异报告，对比导出前与导出后的 3–5 个黄金输出。

格式对照表

按硬件和部署形态选择格式，而不是凭习惯——选错要么浪费吞吐余量，要么在特定工作负载上静默失效（参见工作负载覆盖）。

• FP8 是 Hopper 级及更新 GPU 上的默认选择。 它以大约一半的显存保持接近 bf16 的质量，只要目标 GPU 支持且没有边缘设备约束，它就是安全的首选。
• AWQ INT4 面向早于 FP8 硬件支持的旧 GPU。 GPTQ 在新部署中已被取代——全新导出不要选它；在相同位宽下 AWQ 的精度保持更好，且当前工具支持更广。
• 基于 imatrix 构建的 GGUF 配合 Q4_K_M 量化，是边缘/llama.cpp 格式。 用于本地或贴近 CPU 的部署，不要用于 GPU 服务吞吐——它优化的是占用空间，而不是数据中心 GPU 上的 tokens/sec。
• NVFP4 仅用于 Blackwell 规模化部署——并且明确不适用于 GB10。 在 SM121（GB10）上 NVFP4 比 FP8 慢 约 32%，因为除非内核以 sm_121a 编译，硬件缺少原生的 cvt.e2m1x2 路径。在 GB10 目标上选择 NVFP4 是倒退，不是升级——那里应改选 FP8。
• 合并导出与仅 LoRA 是与量化格式不同的另一个维度。 合并导出将适配器折入基础权重：产物更大，服务时无基础模型依赖。仅 LoRA 保持适配器独立：产物小得多，但服务栈必须同时加载完全相同的基础模型——基础模型不匹配或版本错误会静默改变输出。当产物可移植性比存储更重要时选合并；当磁盘占用或多适配器服务更重要时选仅 LoRA。

实际选择

核心的格式选择权衡，作为常见场景的查找表：

目标	工作负载	格式
数据中心 GPU	通用对话	FP8
数据中心 GPU	长上下文/代码/数学	FP8 或 W8A8——绝不用 INT4
较旧 GPU 代际	通用	AWQ INT4
边缘设备/笔记本	llama.cpp 服务	GGUF Q4_K_M + imatrix
GB10	任意工作负载	通过 vLLM nightly 用 FP8，或本地通过 llama.cpp 用 GGUF——跳过 NVFP4

# quick decision snippet — see the table above for the full map
hopper_or_newer: fp8
older_gpu: awq-int4
edge_llama_cpp: gguf-q4_k_m+imatrix
gb10_any_workload: fp8-vllm-nightly   # never nvfp4 on GB10

工作负载覆盖

上面的格式映射是默认值，并非适用于所有工作负载的规则。长上下文、代码和数学工作负载会在 INT4 下失效 —— 量化误差会在长序列中累积，而精确的 token 级推理所受到的这种影响，不会在简短、通用的提示词上显现。对于这三类工作负载中的任何一种，都应保持使用 FP8 或 W8A8，即使目标硬件在成本上本可支持 INT4。

• 不要用 MMLU 或类似的广泛知识基准来验证这一覆盖规则 —— 它们并不会施压该失效模式。应使用实际的任务评估来测量 —— 即来自 eval-harness-first 的 goldens 和评分器，通过导出的产物运行 —— 因为在长上下文、代码或数学任务上，INT4 的退化会表现为任务特有的失败（上下文丢失、语法破坏、算术错误），远早于它影响某个知识基准。
• 如果在这三类工作负载之一上，某次 INT4 导出后任务评估出现回退，解决办法是切换格式，而不是重新调整量化配方 —— 相同位宽下的 AWQ 和 GPTQ 变体在这些工作负载上具有相同的累积误差失效模式。

冒烟测试

导出 bug 在文件层面是无声的 —— 一个格式错误的导出仍然会产出一个可加载的产物，所以文件存在性检查什么都证明不了。每次导出都必须进行冒烟测试，对于某种"本应就能正常工作"的格式也不例外：

1. 在实际目标运行时中加载导出的产物 —— FP8/AWQ 用 vLLM，GGUF 用 llama.cpp，而不是在一个与生产环境中将要服务它的框架不同的框架里做一个快速的健全性加载。
2. 通过它运行 3–5 个 golden 提示词 —— 从 eval-harness-first 维护的同一个 eval/goldens.jsonl 中提取这些，而不是临时新凑一组。
3. 将每个输出与导出前的生成结果进行对比，针对相同的提示词、相同的确定性采样设置 —— 贪心解码（temperature 0）和一个固定种子，在导出前和导出后的运行之间持久化并复用，而不仅仅是名义上相同的配置。对于无损导出，字节匹配就是门槛 —— 任何差异都是 bug。 对于有损（量化）导出，字节匹配预期会失败；门槛改为任务评分器判定的一致性 —— 参见 references/export-commands.md 的 Smoke-Test Script Skeleton。

将此作为门槛来运行，而不是手动检查：

python smoke_test.py "$EXPORT_PATH" \
    eval/goldens.jsonl pre-export-outputs.jsonl
# non-zero exit on any pre/post mismatch

失败特征

导出 bug 实际看起来是什么样，而不是一个干净通过/失败标志：

• 模板不匹配表现为输出乱码或连成一串 —— 烘焙进导出中的聊天模板与检查点训练和评估时所用的模板不一致，因此轮次边界或特殊 token 落在了错误的位置。
• 对 lm_head 应用了错误的量化表现为偏离模板或语义上毫无意义的输出，却仍显得流畅 —— 输出头失去了它所需的精度，即便网络其余部分量化得很干净。

绝不要发布跳过了这一步的导出 —— 检查点的 PROMOTE 判定说明的是未导出的检查点是好的；它对导出流水线什么也没说。在任何量化方法或运行时版本升级时都要重新运行，而不仅是在首次导出之后。每种格式的可运行命令序列以及冒烟测试脚本骨架：references/export-commands.md。

相关技能

• checkpoint-promotion — 本技能唯一有效的 上游来源。没有 PROMOTE 结论的检查点 不会进入导出流程。
• eval-harness-first — 拥有本技能冒烟测试 从中抽取 3–5 条提示词的 eval/goldens.jsonl，以及 Workload Overrides 一节 为长上下文/代码/数学 验证所要求的任务评测。
• finetuning-method-selection — 其 references/model-catalog.md 是在从上方 Format Map 中选择格式之前，核对硬件级别假设（基础模型 面向哪些 GPU 代际）的地方。

Spark 用户： 在 GB10 上，通过 llama.cpp 使用 GGUF 很适合本地服务，而通过 vLLM nightly 构建进行 FP8 服务 是另一条经验证可行的路径 — NVFP4 是在那里 应当避免的唯一格式（见上方 Format Map 例外）。一旦 dgx-spark-ops 插件安装完成，请将 Spark 特定的服务和散热问题交给它的技能处理， 而不要在这里重新推导。