Chapter 11
常见错误与社区资源
Axolotl 错误大多在 YAML 验证、数据 tokenize、多卡通信三类。本章按高频列。
11.1YAML 类
| 现象 | 处理 |
|---|---|
| "AxolotlInputConfig" validation error | 看错误 path，通常是字段拼错或类型错 |
| "datasets must be a list" | datasets 必须是 list[dict]，每个 dict 有 path + type |
| "adapter qlora requires load_in_4bit" | 两个字段成对出现 |
| "sequence_len > model max_position_embeddings" | 用 rope_scaling 扩；或减 sequence_len |
11.2数据 / Tokenize 类
| 现象 | 处理 |
|---|---|
| "unknown type 'xxx'" | type 拼错；或自定义文件没放对位置 |
| tokenize 后 labels 全 -100 | roles 字段没列全 assistant 别名 |
| tokenize 巨慢 | 开 dataset_processes: 16；删 dataset_prepared_path 重新跑 |
| "index out of range" | chat_template 与数据列对不上；调试 tokenize |
| train_size = 0 | val_set_size 太大；或数据 split 写错 |
11.3训练 / OOM 类
| 现象 | 处理 |
|---|---|
| OOM 第 0 step | 开 gradient_checkpointing；降 micro_batch_size；考虑 QLoRA |
| OOM 中途 | 显存碎片化；PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True |
| NaN loss | lr 太大；或 fp16 而非 bf16；或 grad clip 失效 |
| loss 不降 | tokenizer 跟 base 不匹配；或 chat_template 反了 |
| save 极慢 | 多卡 ZeRO-3 save；开 save_only_model: true |
11.4多卡 / 分布式
| 现象 | 处理 |
|---|---|
| "NCCL timeout" | 多机网络问题；查 NCCL_SOCKET_IFNAME |
| FSDP + LoRA 报错 | fsdp_use_orig_params: true |
| DeepSpeed ZeRO-3 + LoRA 训不动 | 升级 peft >= 0.13 |
| 多机 dataset 加载冲突 | 用 NFS 共享路径，或先在节点 0 preprocess |
11.5调试技巧
# 1) 用小模型先跑通
base_model: meta-llama/Llama-3.2-1B
num_epochs: 1
val_set_size: 0.0
# 2) preprocess only
axolotl preprocess my.yml --debug
# 输出 tokenize 结果，看第一条样本
# 3) 看 verbose
export AXOLOTL_LOG_LEVEL=DEBUG
export NCCL_DEBUG=INFO
# 4) sanity-check：单卡 1 step
micro_batch_size: 1
max_steps: 111.6社区资源
- GitHub：
https://github.com/axolotl-ai-cloud/axolotl（11k+ ⭐） - Discord：链接在 README，社区最活跃；YAML 调试基本都在这问；
- 官方文档：
https://axolotl.continuumlabs.ai/； - Modal Cloud 模板：仓库
examples/modal/； - 每月 release notes：跟 PR；
- Hermes / NousResearch / Teknium 案例：Hugging Face 上模型卡片基本都贴 Axolotl YAML。
11.717 个 Integrations 速查
v2026 之后 src/axolotl/integrations/ 已经有 17 个插件，比单纯的 LoRA / DPO 更丰富。每个都通过 plugins: 字段启用：
| integration | 用途 | 典型场景 |
|---|---|---|
kernels | Triton kernel 集合（ScatterMoE LoRA 等） | MoE LoRA 加速 |
liger | Liger Kernel fused 算子 | SFT 加速 +20% / 省 60% 显存 |
cut_cross_entropy | 分块 CE 算 logits | 大词表模型（200K+）省显存 |
kd（Knowledge Distillation） | 师生训练，offline/online KD | 压缩大模型 |
diffusion | 文本扩散模型训练 | Diffusion LM |
expert_parallel | MoE expert 跨 GPU 并行 | 大 MoE 训练 |
eaft | Entropy-Aware Focal Training | 长上下文 loss 权重 |
spectrum | 谱分析（SNR） 数据质量 | 训练前数据筛 |
grokfast | 梯度预测优化器 | 稳定 grokking |
mora | Mixture of Rank Adaptation | LoRA 替代 |
nemo_gym | NVIDIA NeMo Gym RL 环境 | agent / 指令任务 reward |
hatchery | 自定义 RL trainer 脚手架 | 研究用 |
lm_eval | lm-evaluation-harness | MMLU/ARC/HellaSwag 评测 |
lm_compressor | Neural Magic 压缩工具 | 训后量化 / 剪枝 |
densemixer | Dense + Sparse 层混合 | 架构实验 |
swanlab | SwanLab 实验跟踪（W&B 国产替代） | 国内训练监控 |
grpo | GRPO + 内置 reward 函数 | R1 风格推理 |
11.8--sweep：超参 sweep
跑 6 组学习率试试好坏，不用写 6 份 yaml。来源 cli/main.py:98–137：
# sweep.yaml
learning_rate: [1e-5, 5e-5, 1e-4, 2e-4, 5e-4]
lora_r: [8, 16, 32]
# 触发笛卡尔积 5 × 3 = 15 个实验
axolotl train base.yml --sweep sweep.yaml每个组合输出独立目录（output_dir-lr=1e-5-r=8/ 等）。Axolotl 自动跑 + 收集 metric。
11.9agent-docs：让 LLM 自己读文档
2026 后新增的有意思命令：axolotl agent-docs 把 Axolotl 文档转成结构化、单文档、不超 token-budget 的形式，给 AI agent（Cursor / Cline / Aider 等）灌进上下文：
axolotl agent-docs # 默认 quickstart
axolotl agent-docs --list # 列所有 topic
axolotl agent-docs grpo # GRPO topic
axolotl agent-docs config-schema # 配置 schema给 Claude / GPT-4 写 axolotl YAML 时把这段 paste 进 system prompt，让 agent 不会瞎编字段。
11.10这章你需要带走的
- 三大错误类：YAML 校验 / tokenize / 分布式；
- 调试黄金法则：先小模型 + preprocess only 跑通；
- FSDP + LoRA 必须 fsdp_use_orig_params: true；
- Discord 是最快的求助渠道。