Axolotl 微调框架：一站式开源模型训练工具

FreeGuideOnline 最新 2026-06-22

bash sudo apt update sudo apt install -y git python3.10 python3.10-venv python3.10-dev build-essential cmake


### 安装 Axolotl

推荐使用 VS Code 远程开发环境或直接本地安装，不要用系统级 Python。创建并激活虚拟环境：

```bash
python3.10 -m venv axolotl-env
source axolotl-env/bin/activate

克隆仓库并安装：

git clone https://github.com/OpenAccess-AI-Collective/axolotl.git
cd axolotl
pip install -e '.[flash-attn,deepspeed]'

注意：flash-attn 需要 CUDA 工具链，若编译失败可先省略该特性，改为 pip install -e .。安装 DeepSpeed 可极大提升训练效率。

验证安装：

python -c "import axolotl; print('Axolotl ready!')"

数据集准备

Axolotl 支持多种数据格式，最常用的是 JSONL。每行一条训练样本，必须包含文本字段或指定输入/输出字段。例如，一条典型的指令数据：

{
  "instruction": "用三句话描述春天",
  "input": "",
  "output": "春天是万物复苏的季节。花朵绽放，树木抽芽。温暖的阳光洒在大地上，带来生机与希望。"
}

字段名称可自定义，后续在配置文件中映射。

示例数据集结构

假设我们构建一个中文问答数据集 my_dataset.jsonl，内容如下：

{"instruction": "什么是机器学习？", "input": "", "output": "机器学习是一种人工智能技术，它使计算机能够从数据中学习并改进，而无需明确编程。"}
{"instruction": "Python的特点是什么？", "input": "", "output": "Python 语法简洁，可读性强，库生态丰富，适合快速开发与数据科学。"}

文件存放在 data/ 目录下。

使用内置模板

Axolotl 自带多种格式模板，例如 alpaca 模板会自动将上述结构组装成：

Below is an instruction that describes a task. Write a response that appropriately completes the request.

### Instruction:
什么是机器学习？

### Response:
机器学习是...

若数据已是纯文本对话格式（如 ShareGPT 格式），也可直接使用。

配置训练参数

Axolotl 的所有训练逻辑由 YAML 配置文件驱动。创建一个 configs/my_qlora.yml 作为起点。

基础配置：选择模型与加载方式

base_model: THUDM/chatglm3-6b-base   # 或 meta-llama/Llama-2-7b-hf，需注意许可证
model_type: AutoModelForCausalLM       # 模型加载类型
tokenizer_type: AutoTokenizer

load_in_8bit: false
load_in_4bit: true                    # 启用4-bit量化
strict: false

数据集设置

datasets:
  - path: data/my_dataset.jsonl
    type: alpaca           # 使用alpaca模板
    shuffle_merged: true
dataset_prepared_path: last_run_prepared   # 缓存预处理结果，加速重复训练
val_set_size: 0.05         # 从数据中切分5%作为验证集

LoRA 参数

adapter: qlora
lora_model_dir:

lora_r: 8
lora_alpha: 16
lora_dropout: 0.05
lora_target_modules:
  - query_key_value
lora_target_linear: true

不同模型的目标模块名称不同（如 Llama 使用 q_proj, v_proj），Axolotl 会自动根据 model_type 推断，你可通过 python -m axolotl.cli.infer_lora_config configs/my_qlora.yml 查看推荐值。

训练超参数

sequence_len: 1024
sample_packing: true          # 打包多个短样本到一个序列，提高效率
pad_to_sequence_len: true

wandb_project: axolotl-chinese-qa
wandb_entity: your_wandb_name   # 可选，若未登录wandb可注释掉

gradient_accumulation_steps: 4
micro_batch_size: 1
num_epochs: 3
optimizer: adamw_bnb_8bit
lr_scheduler: cosine
learning_rate: 0.0002

train_on_inputs: false
group_by_length: false
bf16: true                     # 使用bfloat16加速，需A100/A6000等支持，否则auto为fp16

DeepSpeed 集成（可选）

如果单GPU显存紧张或多卡训练，可添加 DeepSpeed 配置：

deepspeed: deepspeed_configs/zero2.json

示例 zero2.json：

{
  "zero_optimization": {
    "stage": 2,
    "allgather_partitions": true,
    "allgather_bucket_size": 2e8,
    "overlap_comm": true,
    "reduce_scatter": true,
    "reduce_bucket_size": 2e8,
    "contiguous_gradients": true
  },
  "bf16": {
    "enabled": true
  },
  "train_micro_batch_size_per_gpu": 1,
  "gradient_accumulation_steps": 4
}

开始训练

一切准备就绪后，在项目根目录执行：

accelerate launch -m axolotl.cli.train configs/my_qlora.yml

如果使用 DeepSpeed，命令会自动加载。训练过程会输出进度条、损失值等信息。若配置了 wandb，可在浏览器实时监控。

训练完成后，输出目录（默认为 ./lora-out）包含：

适配器权重（adapter_model.bin / adapter_model.safetensors）
配置文件（adapter_config.json）
中间检查点（checkpoint-xxx）

模型评估与推理

合并 LoRA 适配器

训练得到的 LoRA 权重可与基础模型合并，得到完整的可部署模型：

python -m axolotl.cli.merge_lora configs/my_qlora.yml

该命令会读取配置中的基础模型和 LoRA 路径，输出合并后的完整权重至 lora-out/merged。

使用合并模型进行推理

你可以直接加载合并后的模型，用 Transformers 进行测试：

from transformers import AutoTokenizer, AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("lora-out/merged", device_map="auto", trust_remote_code=True)
tokenizer = AutoTokenizer.from_pretrained("lora-out/merged", trust_remote_code=True)

prompt = "### Instruction:\n什么是机器学习？\n\n### Response:\n"
inputs = tokenizer(prompt, return_tensors="pt").to("cuda")
output = model.generate(**inputs, max_new_tokens=128)
print(tokenizer.decode(output[0], skip_special_tokens=True))

评估指标

评估可通过运行 Axolotl 内置的评估脚本实现，例如：

python -m axolotl.cli.evaluate configs/my_qlora.yml --wandb_run_id <run-id>

常用指标包括困惑度（Perplexity）、ROUGE 等，具体根据任务定制。

进阶技巧

多轮对话数据处理

对于多轮对话，推荐使用 ShareGPT 格式：

{
  "conversations": [
    {"from": "human", "value": "你好"},
    {"from": "assistant", "value": "你好！有什么可以帮助你的？"},
    {"from": "human", "value": "今天天气怎么样？"},
    {"from": "assistant", "value": "我无法获取实时天气，但你可以查询天气预报网站。"}
  ],
  "system": ""
}

并在配置中指定 type: sharegpt。

自定义提示模板

在 axolotl/prompt_strategies 目录下可添加自定义模板。例如创建 my_template.py，然后配置中引用：

datasets:
  - path: data/my_conversations.json
    type: my_custom_template

分布式训练加速

使用多GPU时，可利用 torchrun 或 accelerate 启动：

accelerate launch --multi_gpu --num_processes=4 -m axolotl.cli.train configs/my_qlora.yml

配合 DeepSpeed ZeRO-3 可进一步降低单卡显存占用。

使用云端 GPU

若本地资源不足，可借助 Colab Notebook（需 Pro+ 版本）或 AutoDL、Vast.ai 等平台，直接克隆仓库并安装依赖即可。

常见问题排查

Q：安装 flash-attention 一直失败？
A：flash-attn 需 CUDA 11.8+ 且 torch 版本匹配。可先跳过一次安装：pip install -e .，之后在配置里设置 flash_attention: false，训练时使用普通注意力机制，稍微增加显存占用。

Q：训练时 OOM（显存不足）？
A：减小 sequence_len（如 512）、降低 micro_batch_size、增大 gradient_accumulation_steps，或启用 QLoRA 的 load_in_4bit: true。

Q：数据集中有不同字段名，如何映射？
A：通过配置的 dataset_preprocess 部分自定义：

dataset_preprocess:
  - format: |
            {% if input %}用户：{{instruction}}\n{{input}}\n\n助手：{% else %}用户：{{instruction}}\n\n助手：{% endif %}{{output}}