Chapter 11
常见错误
📌 commit 964f70econfig / 训练 / 转换 / 推理四类
XTuner 错误大多在 MMEngine config 语法、数据格式、转换工具上。本章按高频列。
11.1config 类
| 现象 | 处理 |
|---|
| "KeyError: 'type'" | dict 没写 type；或导入路径错 |
| "cannot find module xxx in Registry" | 没注册或拼写错；用 xtuner list-cfg 对照 |
| config 改了不生效 | 跑的是内置 config，改不影响；用 copy-cfg 复制到本地 |
| chat_template 拼错 | 看 xtuner/utils/templates.py 的 PROMPT_TEMPLATE 全清单 |
11.2训练类
| 现象 | 处理 |
|---|
| OOM 第 0 step | 开 gradient_checkpointing；改 QLoRA；增 accumulative_counts |
| FlashAttention 报错 | 装 flash-attn；或 use_varlen_attn=False |
| loss 不降 | chat template 错；用 EvaluateChatHook 看实际输出 |
| NaN | QLoRA 必须用 fp16 compute_dtype；全参试 bf16 |
| 多卡只用 1 张 | 没设 NPROC_PER_NODE |
| DeepSpeed 启动失败 | pip install xtuner[deepspeed]；ds_report 检查 |
11.3转换类
| 现象 | 处理 |
|---|
| pth_to_hf 报 shape mismatch | config 路径和 pth 不匹配；用对应 config |
| merge 后效果差 | QLoRA base 自动 dequant，但跟 fp16 推理会有微小差；可接受 |
| HF 加载报 missing adapter_config | pth_to_hf 输出 dir 完整；检查 adapter_config.json |
| InternVL convert 报 weights 不全 | InternVL 有自己 convert 子命令；不要用通用 pth_to_hf |
11.4推理 / 部署类
| 现象 | 处理 |
|---|
| chat 输出乱码 | prompt_template 不对；用对应模型的 template |
| chat 加 adapter 慢 | 正常，每次都按 LoRA + base 算；用 merge 后版本 |
| vLLM / LMDeploy 加载 merge 后 模型失败 | tokenizer 一起保；检查 chat_template |
| VL 推理无图输出 | 检查 image_token_index 和占位符 |
11.5多卡 / 多机
| 现象 | 处理 |
|---|
| NCCL hang | 查 NCCL_SOCKET_IFNAME；多机要 IB |
| HF cache 多机冲突 | 每节点单独 cache；或共用 NFS |
| ZeRO-3 + LoRA 训不动 | 升 peft >= 0.11、transformers >= 4.45 |
| sequence parallel 没生效 | 命令行 --seq-parallel-size N + config 里 SequenceParallelSampler |
11.6调试技巧
# 1) 小模型先跑通
pretrained_model_name_or_path = "internlm/internlm2-chat-1_8b"
# 2) 短跑
max_epochs = 1
save_steps = 50
# 3) verbose
export MMENGINE_LOG_LEVEL=DEBUG
# 4) 用 EvaluateChatHook 实时看输出
custom_hooks = [
dict(type=EvaluateChatHook,
tokenizer=tokenizer,
every_n_iters=50,
evaluation_inputs=["你好", "请介绍 Python"]),
]
11.7这章你需要带走的
- config 类问题查 Registry / type 拼写；
- OOM 优先 QLoRA + grad_ckpt；
- 转换出问题用对应 config + 对应 pth；VL 走专用 convert；
- EvaluateChatHook 是 XTuner 招牌调试工具。