Chapter 02
安装：Docker / Modal / 本地
Axolotl 的依赖比较"硬核"：要装 flash-attn、xformers、bitsandbytes、deepspeed 等扩展。本章给三条路径，按推荐度排序。
2.1路径 A：官方 Docker（推荐）
# 拉镜像
docker pull axolotlai/axolotl:main-latest
# 起容器
docker run --gpus all -it --rm \
--shm-size=16g \
-v $PWD:/workspace \
axolotlai/axolotl:main-latest bash
# 内部 axolotl 已就绪
axolotl --help2.2路径 B：Modal Cloud
Axolotl 在 Modal（按用量计费的 serverless GPU）上有官方模板，零本地配置：
pip install modal
modal token new
# 用 axolotl 仓库自带的 modal 脚本
git clone https://github.com/axolotl-ai-cloud/axolotl
cd axolotl/examples/modal
modal run train.py --config /path/to/config.yaml适合"我没 GPU 但要训"的场景，按训练时间计费。
2.3路径 C：本地 pip
git clone https://github.com/axolotl-ai-cloud/axolotl
cd axolotl
git checkout ab1a0d8 # 本书基线
pip install packaging ninja
pip install torch==2.4.1
pip install -e ".[flash-attn,deepspeed]"本地装机要注意：
flash-attn编译慢（10-30 分钟），用pip install flash-attn --no-build-isolation；bitsandbytes需要 CUDA >= 11.7；deepspeed装完用ds_report验证。
2.4依赖矩阵
| 包 | 版本 | 角色 |
|---|---|---|
| torch | >= 2.4 | 底座 |
| transformers | >= 4.46 | 模型 |
| accelerate | >= 1.0 | 多卡 |
| peft | >= 0.13 | LoRA |
| trl | >= 0.13 | 对齐 |
| bitsandbytes | >= 0.43 | QLoRA |
| deepspeed | >= 0.14 | 多机 |
| flash-attn | >= 2.6 | 性能 |
| xformers | >= 0.0.27 | 性能 |
2.5验证
# 用官方最简配置
axolotl train examples/llama-3/lora-1b.yml能跑通说明环境对。
2.6常见装机问题
| 现象 | 处理 |
|---|---|
| flash-attn 编译失败 | gcc < 11；用 conda gcc 或 Docker |
| bitsandbytes 报 libcudart | CUDA toolkit 版本对不上；conda install cudatoolkit |
| deepspeed 找不到 nccl | 装好 cuda + nccl，ds_report 应全绿 |
| Docker 容器内 GPU 不可见 | 装 nvidia-container-toolkit |
| 本地 pip 装完 import 报错 | 用 Docker 省事 |
2.7axolotl CLI 13 个子命令
v2026 后 axolotl 命令暴露 13 个子命令（来源 src/axolotl/cli/main.py）：
| 子命令 | 位置 | 用途 |
|---|---|---|
axolotl train | main.py:98–137 | ★ 训练（multi-GPU 自动包 accelerate / torchrun） |
axolotl preprocess | main.py:57–75 | 提前 tokenize 数据集（按 CPU 多进程） |
axolotl evaluate | main.py:153–180 | 在验证集上跑评测 |
axolotl inference [--gradio] | main.py:198–228 | CLI 推理或 Gradio UI |
axolotl merge_lora | main.py:282–293 | 合并 LoRA 到 base |
axolotl merge_sharded_fsdp_weights | main.py:245–274 | 合并 FSDP 分片权重 |
axolotl fetch {examples|deepspeed_configs|docs} | main.py:301–314 | 从 GitHub 拉资源到本地 |
axolotl vllm_serve | main.py:321–324 | 给 GRPO / EBFT 起 vLLM 生成 server |
axolotl quantize | main.py:331–334 | 量化导出（GGUF / AWQ / GPTQ） |
axolotl delinearize_llama4 | main.py:340–343 | Llama 4 专用 delinearize 工具 |
axolotl agent-docs [topic] [--list] | main.py:349–375 | 打印面向 AI agent 的文档（给 Cursor / Cline 等用） |
axolotl config-schema [--format json|yaml] | main.py:387–449 | dump 完整 Pydantic config schema |
axolotl lm-eval | main.py:452 | 转给 integrations.lm_eval.cli，跑 lm-evaluation-harness |
train 子命令额外支持的核心 flag：
--launcher {accelerate|torchrun|python}：手动指定多卡 launcher（默认 accelerate）；--cloud config.yml：交给云模板（Modal / RunPod）跑；--sweep hyperparams.yaml：超参 sweep；--后的参数原样转给 launcher。
2.8关键环境变量
| 变量 | 用途 |
|---|---|
PYTORCH_CUDA_ALLOC_CONF | CLI 自动设 expandable_segments:True |
AXOLOTL_NO_TELEMETRY=1 | 关 telemetry 上报 |
ACCELERATE_USE_DEEPSPEED=true | 不写 accelerate 配置直接走 DeepSpeed |
HF_HUB_OFFLINE=1 | 纯离线训练 |
WANDB_PROJECT / WANDB_DISABLED | W&B 项目 / 关闭 |
2.9这章你需要带走的
- Axolotl 装机首选 官方 Docker；
- 没 GPU 用 Modal Cloud；
- 本地装要预编译 flash-attn、确认 CUDA / NCCL；
- 验证用
axolotl train examples/llama-3/lora-1b.yml。