Axolotl：YAML 配置驱动的大模型微调全流程框架安装与使用指南
一、官方信息
| 项目名称 | Axolotl |
| 仓库地址 | https://github.com/OpenAccess-AI-Collective/axolotl |
| 官方文档 | https://axolotl-ai-cloud.github.io/axolotl |
| 最新更新 | 持续高频迭代（2026-10-19） |
| Star 数 | 9k+ |
| 项目定位 | OpenAccess-AI-Collective 维护，用 YAML 配置文件描述完整微调流程，从数据预处理到训练、合并、推送 HF 一站完成 |
二、项目背景
Axolotl 由 Wing Lian 发起，现由 Open Access AI Collective 维护。它的核心理念是"配置即代码"：把模型、数据集、微调方法、超参数、导出方式全部写在一个 YAML 文件里，一条命令 axolotl train config.yaml 完成所有工作。它早期是 Koala、WizardLM 等知名开源模型的训练工具，至今仍是工业界微调 LLaMA、Mistral、Qwen 的常用框架。
与 LLaMA-Factory 的 WebUI 路线不同，Axolotl 面向工程师：纯 YAML + Git 管理，便于版本化复现实验，支持 deepspeed、fsdp、torchrun 多机训练，并内置数据打包、 packing、chat template 自动应用、wandb 日志、HF Hub 推送等完整流水线。
三、核心特性
- YAML 全配置：模型/数据/超参/导出全部声明式，可 Git 版本化。
- 方法全覆盖：Full / LoRA / QLoRA / Ptuning / ReLoRA / qGPTQ。
- 对齐算法：DPO / IPO / KTO / ORPO / SimPO。
- 多卡训练：原生支持 DDP、DeepSpeed ZeRO-2/3、FSDP。
- 数据集灵活：支持 HF datasets、JSON、ShareGPT、Alpaca、本地 CSV、远程 URL。
- Unsloth 加速：一行配置切换到 Unsloth 后端，速度翻倍。
- 一键推送：训练完自动推送到 HuggingFace Hub 或 ModelScope。
四、环境要求
- Python：3.10 ~ 3.12
- GPU：NVIDIA 显卡 ≥ 16GB（QLoRA 7B）；全参数 7B 需 ≥ 4×24GB
- CUDA：11.8 / 12.1 / 12.4
- PyTorch：2.1+
五、详细部署步骤
方式一：pip 安装（推荐）
conda create -n axolotl python=3.10 -y
conda activate axolotl
# 安装 PyTorch
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu121
# 安装 axolotl
pip install axolotl
# 验证
axolotl --version方式二：源码安装
git clone https://github.com/OpenAccess-AI-Collective/axolotl.git
cd axolotl
pip install -e ".[all,dev]"
pip install -e .方式三：Docker
docker pull winglian/axolotl:main-latest
docker run -it --rm --gpus all \
-v ~/axolotl:/workspace \
-v ~/.cache/huggingface:/root/.cache/huggingface \
winglian/axolotl:main-llatest bash第一步：写训练配置 YAML
cat > qwen_lora.yaml << 'EOF'
base_model: Qwen/Qwen2.5-7B-Instruct
base_model_config: Qwen/Qwen2.5-7B-Instruct
model_type: AutoModelForCausalLM
tokenizer_config: AutoTokenizer
tokenizer_use_fast: true
load_in_4bit: true
# LoRA 配置
adapter: lora
lora_r: 16
lora_alpha: 16
lora_dropout: 0.05
lora_target_modules:
- q_proj
- k_proj
- v_proj
- o_proj
- gate_proj
- up_proj
- down_proj
# 数据集
datasets:
- path: json
data_files: my_data.jsonl
type: sharegpt
split: train
# 训练超参
gradient_accumulation_steps: 4
micro_batch_size: 2
num_epochs: 3
optimizer: paged_adamw_8bit
lr_scheduler: cosine
learning_rate: 0.0002
lr_warmup_steps: 10
bf16: auto
gradient_checkpointing: true
flash_attention: auto
# 输出
output_dir: ./axolotl-out
logging_steps: 10
save_strategy: steps
save_steps: 100
save_total_limit: 3
hub_model_id: my-qwen25-lora
push_to_hub: false
# 打包
sample_packing: true
eval_sample_packing: true
EOF第二步：启动训练
# 单卡
axolotl train qwen_lora.yaml
# 多卡 DDP（4 卡）
accelerate launch -m axolotl.cli.train qwen_lora.yaml
# DeepSpeed ZeRO-3（大模型）
# 在 yaml 中加：
# deepspeed: ds_config_z3.json
accelerate launch -m axolotl.cli.train qwen_lora.yaml第三步：合并 LoRA 权重
# 合并为完整 HF 模型
axolotl merge qwen_lora.yaml \
--lora_model_dir ./axolotl-out \
--output_dir ./merged-model
# 合并后可直接用 vLLM / TGI / Ollama 部署第四步：DPO 对齐训练
# dpo.yaml 关键配置
cat > dpo.yaml << 'EOF'
base_model: Qwen/Qwen2.5-7B-Instruct
model_type: AutoModelForCausalLM
rl: dpo
dpo:
beta: 0.1
datasets:
- path: my_dpo_data.jsonl
type: chat_template.formatted_prompt
split: train
output_dir: ./dpo-out
num_epochs: 1
learning_rate: 0.000005
EOF
axolotl train dpo.yaml使用 Unsloth 加速
# yaml 中加一行
use_unsloth: true
# 自动启用 Unsloth 后端，2x 速度 + 50% 显存节省六、常见问题（FAQ）
Q1：报 "tokenizer class not found"？
A：确认 base_model 已从 HF 下载完整，且 tokenizer_use_fast 与模型匹配。Qwen2.5 用 fast tokenizer 没问题。
Q2：多卡训练 loss 不下降？
A：检查学习率是否按卡数放大（多卡 lr × N），并确认 gradient_accumulation_steps 已相应减小以保持 global batch size 一致。
Q3：数据格式怎么准备？
A：ShareGPT 格式 JSONL：{"conversations":[{"from":"human","value":"..."},{"from":"gpt","value":"..."}]}。Alpaca 格式用 type: alpaca。
Q4：如何断点续训？
A：在 yaml 加 resume_from_checkpoint: ./axolotl-out/checkpoint-XXX。
Q5：支持 Flash Attention 2 吗？
A：yaml 中 flash_attention: fa2 即可，需先 pip install flash-attn。