微调模型上线时要注意哪些兼容性问题？
简化版
微调模型上线最常见的问题不是权重无法加载，而是训练和推理协议不一致：基座 Revision、Tokenizer、特殊 Token、Chat Template、RoPE 配置、量化方式或工具调用格式发生变化，导致模型能运行但行为明显退化。
上线前应把模型、Tokenizer、模板和 Adapter 作为同一版本制品，在目标推理引擎做 Logit 对齐、黄金请求回放、长上下文、工具调用和性能压测。LoRA 还要检查目标层与 Scaling，Merge/量化后必须重新评测。
“成功返回文本”只能证明服务没有崩溃，不能证明训练时学到的行为被正确还原。
详细版
可把上线契约写成：
artifact = base_hash + finetune_hash + tokenizer_hash
+ chat_template_version + inference_config任一部分变化都应产生新版本并触发回归。比如训练时使用 <|assistant|> 作为单 Token，服务端 Tokenizer 却把它拆开，模型的角色边界和停止行为会完全不同。
| 兼容层 | 典型错配 | 结果 |
|---|---|---|
| 权重/架构 | 基座 Revision、层数不一致 | 加载失败或静默错误 |
| Tokenizer | 词表、特殊 Token ID 变化 | 输入语义错位 |
| Template | 角色顺序、分隔符不同 | 指令遵循退化 |
| 推理配置 | EOS、RoPE、dtype 不同 | 不停止、长文异常 |
| Adapter | 模块名、rank/scaling 错 | 效果消失或过强 |
| 引擎算子 | 量化、并行、Kernel 差异 | 数值与性能回归 |
完整版教学
1. 为什么“能加载”仍可能不兼容
权重形状相同只保证张量可以赋值。Tokenizer ID、模板和 Scaling 错误往往不报异常，却会把输入映射到模型从未训练过的序列。
因此兼容性验证既要看结构，也要看行为与数值。
2. 基座 Revision 为什么必须精确
LoRA 或增量微调是相对于某一份基座权重学习的。相同模型名称下可能有多个 Revision，维度相同但参数不同。
保存基座 Commit/哈希，加载时强校验；禁止“找一个同规模模型试着挂上”。
3. Tokenizer 哪些字段必须一起发布
词表文件、Merge Rules、Normalizer、Added Tokens、BOS/EOS/PAD ID 和最大长度都属于模型接口。只复制 tokenizer.json 可能漏掉配置。
len(tokenizer) == embedding.num_embeddings
encode(each_special_token) -> exactly one expected id新增 Token 后还要确认 Embedding 和 LM Head 已扩展且保存。
4. Chat Template 为什么最容易静默出错
训练数据中的 system/user/assistant/tool 序列化方式必须与推理一致，包括空格、换行、结束 Token 和 Generation Prompt。
Chat Template 是模型学到的协议，不是可以随意美化的字符串模板。
保存几组结构化消息的黄金 Token IDs，服务启动时做断言。
5. 停止条件如何对齐
模型可能用 EOS、End-of-Turn 或工具结束 Token 停止。服务遗漏一个停止 ID 会生成下一角色或无限续写；过早停止又会截断 JSON。
同时验证流式与非流式、Batch 内不同长度以及 Stop String 跨 Token 边界。
6. LoRA 加载要检查什么
目标模块、rank、alpha、Scaling、Adapter 权重 dtype 和基座哈希必须匹配。加载后打印实际注入层数并跑与训练框架的 Logit 对齐。
动态加载还要检查 Adapter 缓存是否串租户，以及同 Batch 多 Adapter 的引擎支持。
7. Merge 与量化的正确顺序
通常在 FP16/BF16 高精度基座上合并 LoRA，再使用目标流程重新校准量化。直接在 4-bit 权重上反复加减会累积误差。
| 流程 | 推荐度 | 原因 |
|---|---|---|
| 高精度 Merge → Quantize | 推荐 | 可控、可重建 |
| Quantized Base + 动态 LoRA | 视引擎 | 需专用 Kernel |
| 低比特反复 Merge/Unmerge | 不推荐 | 舍入误差累积 |
每个最终制品都要独立回归。
8. RoPE 与最大上下文如何验证
检查 rope_theta、Scaling 类型、最大长度、position_ids 和 KV Cache 位置。训练用 8K 不代表服务配置改到 32K 就可靠。
分别测试短输入、训练上限附近和宣称最大长度，观察质量、显存和 P95 延迟。
9. 张量并行和词表切分有哪些坑
Tensor Parallel 会切分 QKV、FFN、Embedding 和 LM Head。Adapter 合并或动态注入必须按相同分片规则应用，不能每卡重复加完整增量。
词表扩展后分片大小和 Padding 也可能变化，应检查最终 Logits 的 Token 对齐。
10. 推理引擎数值对齐怎么做
选择若干固定输入，比较训练框架与目标引擎的首步 Logits、Top-k Token 和多层隐藏状态。FP16/BF16/量化使用相应容差。
max_abs_diff(logits_ref, logits_engine) < tolerance
top_k_overlap >= threshold数值通过后再做生成行为回归，因为小误差可能导致解码分叉。
11. 工具调用和结构化输出如何回归
验证工具名称、参数 Schema、角色 Token、并行调用和 Tool Result 回填。模型权重正确但服务模板漏字段，工具成功率也会崩。
用 Mock 工具检查真实 Trace 与最终状态，不只看输出字符串像不像 JSON。
12. 性能兼容性包含什么
目标硬件实测 TTFT、TPOT、吞吐、峰值显存、KV Cache 和冷启动。动态 LoRA、长词表或特殊算子可能破坏 Continuous Batching。
性能门槛要与质量同属发布 Gate，避免离线准确但无法满足 SLA。
13. 灰度与回滚如何设计
模型制品使用不可变哈希，小流量回放和真实 Canary 后逐级放量。回滚必须同时恢复权重、Tokenizer、模板和推理配置，不能只切模型文件。
监控格式失败、停止异常、工具成功、质量代理和延迟成本，按版本切片。
14. 常见误区与追问
- 误区：模型权重能加载就兼容。 Tokenizer、模板和推理配置可能静默错配。
- 误区：同名基座都可加载同一 LoRA。 Adapter 依赖精确权重 Revision。
- 误区：量化只影响速度和显存。 它会改变 Logits，并可能放大边界行为回归。
- 误区：只测一条聊天输入即可。 还需多轮、工具、长上下文、Batch 和流式停止。
- 误区：回滚只需恢复模型权重。 Tokenizer、模板、策略和引擎配置必须原子回滚。
- 追问：最有效的上线探针是什么？ 结构化消息到 Token IDs 的黄金断言，加训练框架/引擎 Logit 对齐。
- 追问：Merge 后为什么还要重测？ dtype、Scaling、权重绑定和量化可能引入新误差。
15. 加强记忆
- 四件套：权重、Tokenizer、Chat Template、推理配置共同版本化。
- Adapter 依赖精确基座，检查模块与 Scaling。
- 先数值再行为：Token 断言、Logit 对齐、任务回归。
- 量化/并行/长上下文都可能静默改变结果。
- 原子发布与回滚：所有协议制品一起切换。