Axolotl 开源 LLM 微调框架实战指南从安装配置到首个 LoRA 训练任务【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotlAxolotl 是一个免费开源的 LLM 后训练与微调框架核心理念是「配置驱动」——通过单一 YAML 配置文件串联起数据集预处理、训练、评估、量化与推理的完整流程。本文以仓库根目录 README.md 为主体结合 CLI 实现、示例配置 与 依赖声明 等源码证据系统讲解 Axolotl 的定位、核心能力、安装方式并带你完成一次可复现的 LoRA 微调实战最后梳理完整 CLI 命令、面向 AI Agent 的文档工具与遥测机制。读完本文你将掌握 Axolotl 的完整上手路径并能独立读懂、修改和运行一份微调配置。一、Axolotl 是什么一个配置驱动的 LLM 微调框架Axolotl 被官方描述为A Free and Open Source LLM Fine-tuning Framework其设计目标是为最新的 LLM 提供精简高效streamline的后训练与微调体验。它的最鲜明特征在 AGENTS.md 中被概括为一句话Config-driven: every training run is defined by a single YAML file.即每一次训练运行都由一份 YAML 文件完整定义。无论是数据集的加载与格式化、adapter 的选择LoRA/QLoRA 还是全参微调、优化器与学习率调度、混合精度、梯度累积还是多 GPU 并行策略都通过配置项而非修改代码来完成。配置文件的校验由 Pydantic 模型统一负责定义在 src/axolotl/utils/schemas/config.pyAxolotlInputConfig这也让config-schema等程序化工具成为可能。当前仓库版本为0.19.0.dev0见 VERSION项目采用 Apache-2.0 协议见 LICENSE技术栈覆盖 Python、PyTorch、HuggingFace Transformers、TRL、PEFTLoRA/QLoRA、DeepSpeed、FSDP 以及 vLLM用于 GRPO 在线生成。二、核心能力总览Axolotl 能做什么根据 README.md 的 Overview 一节Axolotl 的能力可以归纳为六个维度以下结合仓库文件逐一说明。1. 多模型支持Axolotl 可以训练 Hugging Face Hub 上的大量模型包括 GPT-OSS、LLaMA、Mistral、Mixtral、Pythia 等。这一点在仓库的 examples 目录中有最直观的体现——按模型分目录存放了 60 组开箱即用的配置例如llama-2、llama-3、llama-3-vision、llama-4mistral、mixtral、ministral3qwen2、qwen2-vl、qwen3、qwen3.5、qwen3.8-flash-nextgemma2、gemma3、gemma3n、gemma4、gemma4-unifiedphi、jamba、mamba、gpt-oss、granite4 等从 README 的更新日志看模型支持始终在快速扩展2026 年 8 月新增 Ling 3.0、Muse Glimmer、North Micro Vision Instruct 与 Shieldstral2026 年 7 月支持通过 ScatterMoEW4A16与 SonicMoEW4A4进行NVFP44-bitMoE LoRA 训练并且可以把 adapter 合并回普通的 NVFP4 checkpoint。2. 多模态训练除了纯文本模型Axolotl 支持视觉语言模型VLM与音频模型的微调包括 LLaMA-Vision、Qwen2-VL、Pixtral、LLaVA、SmolVLM2、GLM-4.6V、InternVL 3.5、Gemma 3n、PaddleOCR-VL、Muse Glimmer以及 Voxtral 等音频模型支持图像、视频与音频输入。仓库中对应的示例包括 llama-3-vision/lora-11b.yaml、qwen2-vl/lora-7b.yaml、pixtral/lora-12b.yml、gemma3n/gemma-3n-e2b-vision-audio-qlora.yml、voxtral/voxtral-mini-audio-qlora.yml 等。3. 丰富的训练方法Axolotl 覆盖了从 SFT 到偏好对齐再到强化学习的完整方法谱系全参微调Full Fine-tuning、LoRA、QLoRA、GPTQQAT 量化感知训练int8/int4/FP8/NVFP4/MXFP4FP8 混合精度训练以及NVFP4/MXFP4 MoE LoRA偏好对齐DPO、IPO、KTO、ORPO强化学习GRPO、GDPOGeneralized DPO奖励模型Reward ModellingRM与 Process Reward ModellingPRMAGENTS.md 给出了这些方法对应的配置键速查表DPO 用rl: dpoIPO 用rl: dpo, dpo_loss_type: [ipo]KTO 用rl: ktoORPO 用rl: orpoGRPO 用rl: grpoEBFT基于内部表征特征匹配奖励用rl: ebft。仓库中对应示例分布在 examples/qwen2/dpo.yaml、examples/llama-3/qlora-1b-kto.yaml、examples/qwen2/reward-model.yaml 等文件中。4. 性能优化README 列举了 Axolotl 内置或可选的性能优化手段Multipacking样本打包、Flash Attention 2/3/4、Xformers、Flex Attention、SageAttention、Liger Kernel、Cut Cross Entropy、ScatterMoE、Sequence ParallelismSP、LoRA 内存优化、多 GPU 训练FSDP1/FSDP2/DeepSpeed、多节点训练Torchrun/Ray。这些优化的依赖与版本约束可以在 pyproject.toml 的 dependencies 与 extras 中确认例如flash-attn、liger-kernel0.8.0、torchao0.17.0等。对应示例包括 examples/llama-3/fft-8b-liger-fsdp.yaml、examples/llama-3/lora-1b-kernels.yml 等。5. 灵活的数据集处理支持从本地文件、HuggingFace Hub 以及云存储S3、Azure、GCP、OCI加载数据集——这一点在 pyproject.toml 中有依赖佐证s3fs、gcsfs、adlfs、ocifs分别对应 S3、GCS、Azure Data Lake 与 OCI 文件系统。数据集格式的处理逻辑集中在 src/axolotl/prompt_strategies/ 目录每种type:值都映射到对应的处理函数如alpaca、chat_template、dpo、kto、orpo等。6. 云就绪项目同时发布 Docker 镜像 与 PyPI 包可运行于云平台与本地硬件。仓库的 docker/ 目录提供了Dockerfile-uv、Dockerfile-uv-base等多份镜像构建文件examples/cloud/ 还包含 baseten、modal 等云平台示例。三、环境要求与安装1. 硬件与软件要求根据 README 的 Quick Start 一节项目要求GPUNVIDIA GPUAmpere 或更新架构以支持bf16与 Flash Attention或 AMD GPUPython≥ 3.11推荐 3.12PyTorch≥ 2.11.0推荐 2.12.1注意 pyproject.toml 中声明的requires-python 3.10是包的最小约束而 README 给出的 3.11/3.12 是经过验证的推荐环境二者并不冲突。2. 使用 uv 安装推荐Axolotl 自 2026 年 4 月起转为uv-first工作流README 给出的标准安装流程如下# 1. 安装 uv如尚未安装安装后建议重启 shell curl -LsSf https://astral.sh/uv/install.sh | sh # 2. 根据系统设置 PyTorch 的 CUDA 后端示例为 cu130 export UV_TORCH_BACKENDcu130 # 3. 创建 Python 3.12 虚拟环境并激活 uv venv --python 3.12 source .venv/bin/activate # 4. 安装 PyTorch 与 Axolotldeepspeed extra uv pip install torch2.12.1 torchvision uv pip install --no-build-isolation axolotl[deepspeed] # 5.可选拉取官方示例配置与 DeepSpeed 配置 axolotl fetch examples axolotl fetch deepspeed_configsaxolotl[deepspeed]是 extras 安装的一种。从 pyproject.toml 可以看到完整的 extras 体系除deepspeed对应deepspeed0.18.6,0.19.0外还有flash-attn、ring-flash-attn、mamba-ssm、auto-gptq、galore、apollo、optimizers、ray、vllm、llmcompressor、opentelemetry等。需要说明的是pyproject.toml 的[tool.uv.conflicts]明确列出了若干互斥组合——例如 axolotl 与vllm、flash-attn、ring-flash-attn、mamba-ssm、auto-gptq等 extra 存在依赖冲突安装时应避免同时启用冲突的 extras。3. 使用 Docker 安装README 建议在自己的环境中安装容易出现依赖问题使用 Docker 往往更省心docker run --gpus all --ipchost --rm -it axolotlai/axolotl:main-latest仓库中的 docker/Dockerfile-uv 展示了镜像构建逻辑基于axolotlai/axolotl-base-uv通过uv pip install --no-build-isolation -e .[deepspeed,optimizers,ray]arm64 架构不装 deepspeed安装核心依赖再安装 cut cross entropy 等内核。此外 docker/Dockerfile-uv 还启用了 bash 自动补全脚本axolotl-complete.bash。4. 云平台一键使用README 列出了 RunPod、Vast.ai、PRIME Intellect、Modal、Novita、JarvisLabs.ai、Latitude.sh 等多个云 GPU 平台的现成模板可直接以预置镜像创建实例仓库内 examples/cloud/ 也提供了 modal.yaml、baseten.yaml 的部署参考。四、第一次微调实战用 LoRA 训练 Llama-3.2-1B1. 三步跑通README 给出的最小实战路径只有三步命令# 获取官方示例配置 axolotl fetch examples # 也可以指定自定义下载路径 axolotl fetch examples --dest path/to/folder # 使用 LoRA 训练 Llama 模型 axolotl train examples/llama-3/lora-1b.ymlfetch命令的实现位于 src/axolotl/cli/main.pyfetch_from_github逻辑它支持拉取examples、deepspeed_configs、docs三类资源train命令则由 src/axolotl/cli/train.py 承接。2. 逐段解读 lora-1b.yml 配置examples/llama-3/lora-1b.yml 是 README 指明的默认入门配置这里完整解读其含义它几乎涵盖了 Axolotl 配置文件的全部核心区块base_model: NousResearch/Llama-3.2-1B # Automatically upload checkpoint and final model to HF # hub_model_id: username/custom_model_namebase_model基座模型在 Hugging Face Hub 上的 ID是每个配置的必备项hub_model_id注释设置后会自动把 checkpoint 与最终模型上传到 Hugging Face。datasets: - path: teknium/GPT4-LLM-Cleaned type: alpaca val_set_size: 0.1 output_dir: ./outputs/lora-outdatasets数据集列表。这里从 HF Hub 加载teknium/GPT4-LLM-Cleanedtype: alpaca指定使用 src/axolotl/prompt_strategies/ 中的 alpaca 提示词策略instruction/input/output 三元组格式val_set_size: 0.1从训练集中切出 10% 作为验证集output_dircheckpoint 输出目录。adapter: lora lora_model_dir: sequence_len: 2048 sample_packing: true eval_sample_packing: trueadapter: lora选择 LoRA 适配器其他取值包括qlora或省略该项进行全参微调sequence_len: 2048序列最大长度sample_packing: true启用样本打包Multipacking把多个样本拼进一个序列以提升吞吐eval_sample_packing对验证集做同样处理。lora_r: 16 lora_alpha: 32 lora_dropout: 0.05 lora_target_modules: - gate_proj - down_proj - up_proj - q_proj - v_proj - k_proj - o_projlora_r/lora_alpha/lora_dropoutLoRA 的秩、缩放系数与 dropoutlora_target_modules注入 LoRA 的线性层这里覆盖了 Llama 架构的注意力q/k/v/o与 MLPgate/up/down全部门。wandb_project: wandb_entity: wandb_watch: wandb_name: wandb_log_model:以上是 Weights Biases 日志相关配置默认留空表示不启用或使用默认行为。gradient_accumulation_steps: 2 micro_batch_size: 2 num_epochs: 1micro_batch_size每步微批大小gradient_accumulation_steps梯度累积步数等效 batch size micro_batch_size × gradient_accumulation_stepsnum_epochs训练轮数。optimizer: adamw_8bit lr_scheduler: cosine learning_rate: 0.0002 bf16: auto tf32: false gradient_checkpointing: true resume_from_checkpoint: logging_steps: 1 attn_implementation: flash_attention_2optimizer: adamw_8bit8-bit AdamWbitsandbytes显著降低优化器状态内存lr_scheduler: cosinelearning_rate: 0.0002余弦退火学习率调度bf16: auto按硬件自动启用 bf16 混合精度tf32: false关闭 TF32gradient_checkpointing: true梯度检查点用计算换显存attn_implementation: flash_attention_2使用 Flash Attention 2README 强调这需要 Ampere 或更新的 GPU。loss_watchdog_threshold: 5.0 loss_watchdog_patience: 3 warmup_ratio: 0.1 evals_per_epoch: 4 saves_per_epoch: 1 weight_decay: 0.0 special_tokens: pad_token: |end_of_text| # save_first_step: true # uncomment this to validate checkpoint saving works with your configloss_watchdog_threshold/loss_watchdog_patienceloss 看门狗当 loss 超过阈值并持续若干步时触发保护逻辑这是 Axolotl 训练稳定性机制的一部分warmup_ratio: 0.1前 10% 步数做学习率预热evals_per_epoch: 4/saves_per_epoch: 1每个 epoch 内做 4 次评估、1 次保存special_tokens.pad_token把 pad token 设为 Llama 的 EOS token避免填充 token 造成干扰save_first_step注释取消注释可在第一步就保存 checkpoint用于尽早验证配置与保存链路是否正常。3. 配置驱动的底层原理Axolotl 的一份配置贯穿全流程并非口号从源码可以看到其支撑机制配置校验所有配置项由 src/axolotl/utils/schemas/config.py 中的AxolotlInputConfigPydantic 模型统一校验运行时通过axolotl config-schema可以导出完整的 JSON Schema详见下文CLI 与配置互通src/axolotl/cli/main.py 中的每个命令都通过add_options_from_config_options(AXOLOTL_CONFIG_CLI_OPTIONS)把 YAML 配置项同时暴露为命令行参数实现配置即参数、参数即配置训练器构建SFT 与 RLHF 分别由 src/axolotl/core/builders/ 下的TrainerBuilder类如causal.py、rl.py负责组装。五、完整 CLI 命令一览根据 README.md 与 src/axolotl/cli/main.py 的源码Axolotl 的 CLI 入口axolotl定义于 pyproject.toml 的[project.scripts]映射到axolotl.cli.main:main提供以下命令命令功能源码位置axolotl train config训练/微调单卡或自动检测的多卡cli/main.pytrainaxolotl preprocess config预分词数据集并校验配置加--debug可检查 token 化样本与标签掩码cli/main.pypreprocessaxolotl inference config推理支持--gradio浏览器界面与--chat多轮对话界面二者互斥cli/main.pyinferenceaxolotl evaluate config评估模型cli/main.pyevaluateaxolotl merge-lora config把训练好的 LoRA adapter 合并回基座模型cli/main.pymerge_loraaxolotl merge-sharded-fsdp-weights config合并 FSDP 分片权重cli/main.pymerge_sharded_fsdp_weightsaxolotl vllm-serve config启动 vLLM 服务供 GRPO/EBFT 训练使用cli/main.pyvllm_serveaxolotl quantize config模型量化cli/main.pyquantizeaxolotl fetch examples / deepspeed_configs / docs拉取示例、DeepSpeed 配置或文档支持--dest指定目录cli/main.pyfetchaxolotl delinearize-llama4 model outputLlama 4 专用把 linearized 权重还原cli/main.pydelinearize_llama4axolotl agent-docs [topic]查看面向 AI Agent 的文档见下节cli/main.pyagent_docsaxolotl config-schema导出配置 JSON Schemacli/main.pyconfig_schema几点值得注意的源码细节train命令支持--launcher参数accelerate/torchrun/python默认accelerate并通过--sweep指定超参数扫描配置src/axolotl/cli/main.py 中定义了LAUNCHER_COMMAND_MAPPING将 launcher 映射为底层进程启动命令train与evaluate等命令支持--之后的额外参数透传给启动器launcher_args如果配置中启用了use_raytrain会自动绕过 launcher 走 Ray 路径源码中_launcher None if kwargs.get(use_ray) else launcher。六、面向 AI Agent 的文档与 Schema 工具这是 Axolotl 近年新增的特色能力内置专门为 AI 编程 AgentClaude Code、Cursor、Copilot 等优化过的文档。这些文档随 pip 包一起分发无需 clone 仓库即可使用# 查看总览与可用训练方法 axolotl agent-docs # 按主题查看 axolotl agent-docs sft # 监督微调 axolotl agent-docs grpo # GRPO 在线强化学习 axolotl agent-docs preference_tuning # DPO、KTO、ORPO、SimPO axolotl agent-docs reward_modelling # 结果/过程奖励模型 axolotl agent-docs pretraining # 持续预训练 axolotl agent-docs --list # 列出所有主题如果你直接使用源码仓库这些 Agent 文档同样位于 docs/agents/如 docs/agents/sft.md、docs/agents/grpo.md、docs/agents/preference_tuning.md、docs/agents/reward_modelling.md、docs/agents/pretraining.md项目总览则写在 AGENTS.md。配套的程序化工具是config-schema# 导出完整配置 JSON Schema供程序化使用 axolotl config-schema # 只导出某个字段的 Schema axolotl config-schema --field adapter从 src/axolotl/cli/main.py 的实现看config-schema支持--format json|yaml底层直接调用AxolotlInputConfig.model_json_schema()生成当完整 Schema 生成失败例如某些torch.dtype无法 JSON 序列化时会降级为输出字段名、类型与默认值的简化版并可通过axolotl config-schema | jq .properties | keys快速浏览全部配置键。七、文档生态导航README 官方推荐了以下入口本文以仓库内路径给出对应文件安装选项docs/installation.qmd —— 不同环境的详细安装说明支持矩阵docs/support-matrix.qmd —— 功能支持、兼容性与已知缺口数据集加载docs/dataset_loading.qmd —— 从各种来源加载数据集数据集格式docs/dataset-formats/ —— 支持的格式与用法chat_template、alpaca、input_output 等多 GPU 训练docs/multi-gpu.qmd多节点训练docs/multi-node.qmdMultipackingdocs/multipack.qmd调试指南docs/debugging.qmdFAQdocs/faq.qmd此外AGENTS.md 还指向了 docs/getting-started.qmd快速上手教程、docs/choosing_method.qmdSFT vs DPO vs GRPO 方法选型、docs/rlhf.qmd、docs/grpo.qmd、docs/training_stability.qmdloss/NaN/OOM 排障等深度资料。分布式训练所需的 DeepSpeed 配置则存放在 deepspeed_configs/zero1/zero2/zero3 及 bf16/cpuoffload 变体还有配套的 torch_compile 版本。八、遥测机制与隐私Axolotl 内置默认开启、可关闭opt-out的遥测用于帮助项目团队理解使用方式并排定改进优先级。根据 README 与 src/axolotl/telemetry/manager.py 的实现收集内容基本的系统信息、模型类型、错误率绝不收集个人数据或文件路径关闭方式设置环境变量AXOLOTL_DO_NOT_TRACK1实现细节源码中_telemetry_enabled()会同时检查AXOLOTL_DO_NOT_TRACK与通用的DO_NOT_TRACK两个环境变量见 telemetry/manager.py任一为真即关闭且遥测上报按 GPU 去重避免多卡重复发送。更详细的说明见 docs/telemetry.qmd。九、贡献、引用与许可贡献项目欢迎社区贡献贡献指南与 CI 矩阵、GPU e2e 测试约定记录在 .github/CONTRIBUTING.md引用在论文或项目中引用 Axolotl 时README 给出了推荐格式software{axolotl, title {Axolotl: Open Source LLM Post-Training}, author {{Axolotl maintainers and contributors}}, url {https://github.com/axolotl-ai-cloud/axolotl}, license {Apache-2.0}, year {2023} }许可项目采用 Apache-2.0 协议详见 LICENSE。结语Axolotl 用一份 YAML 配置贯穿预处理、训练、评估、量化与推理的设计把 LLM 微调的复杂度收敛到了可配置、可复现、可审计的形态。本文从 README.md 出发覆盖了它的能力全景、安装路径uv/Docker/云平台、首个 LoRA 实战examples/llama-3/lora-1b.yml 逐字段解读、完整 CLI 命令cli/main.py 源码佐证、Agent 文档工具以及遥测隐私说明。下一步建议你顺着 docs/getting-started.qmd 走一遍更详尽的教程再用axolotl config-schema | jq .properties | keys探索全部配置项按需组合出属于你自己的训练配置。【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Axolotl 开源 LLM 微调框架实战指南：从安装配置到首个 LoRA 训练任务
Axolotl 开源 LLM 微调框架实战指南从安装配置到首个 LoRA 训练任务【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotlAxolotl 是一个免费开源的 LLM 后训练与微调框架核心理念是「配置驱动」——通过单一 YAML 配置文件串联起数据集预处理、训练、评估、量化与推理的完整流程。本文以仓库根目录 README.md 为主体结合 CLI 实现、示例配置 与 依赖声明 等源码证据系统讲解 Axolotl 的定位、核心能力、安装方式并带你完成一次可复现的 LoRA 微调实战最后梳理完整 CLI 命令、面向 AI Agent 的文档工具与遥测机制。读完本文你将掌握 Axolotl 的完整上手路径并能独立读懂、修改和运行一份微调配置。一、Axolotl 是什么一个配置驱动的 LLM 微调框架Axolotl 被官方描述为A Free and Open Source LLM Fine-tuning Framework其设计目标是为最新的 LLM 提供精简高效streamline的后训练与微调体验。它的最鲜明特征在 AGENTS.md 中被概括为一句话Config-driven: every training run is defined by a single YAML file.即每一次训练运行都由一份 YAML 文件完整定义。无论是数据集的加载与格式化、adapter 的选择LoRA/QLoRA 还是全参微调、优化器与学习率调度、混合精度、梯度累积还是多 GPU 并行策略都通过配置项而非修改代码来完成。配置文件的校验由 Pydantic 模型统一负责定义在 src/axolotl/utils/schemas/config.pyAxolotlInputConfig这也让config-schema等程序化工具成为可能。当前仓库版本为0.19.0.dev0见 VERSION项目采用 Apache-2.0 协议见 LICENSE技术栈覆盖 Python、PyTorch、HuggingFace Transformers、TRL、PEFTLoRA/QLoRA、DeepSpeed、FSDP 以及 vLLM用于 GRPO 在线生成。二、核心能力总览Axolotl 能做什么根据 README.md 的 Overview 一节Axolotl 的能力可以归纳为六个维度以下结合仓库文件逐一说明。1. 多模型支持Axolotl 可以训练 Hugging Face Hub 上的大量模型包括 GPT-OSS、LLaMA、Mistral、Mixtral、Pythia 等。这一点在仓库的 examples 目录中有最直观的体现——按模型分目录存放了 60 组开箱即用的配置例如llama-2、llama-3、llama-3-vision、llama-4mistral、mixtral、ministral3qwen2、qwen2-vl、qwen3、qwen3.5、qwen3.8-flash-nextgemma2、gemma3、gemma3n、gemma4、gemma4-unifiedphi、jamba、mamba、gpt-oss、granite4 等从 README 的更新日志看模型支持始终在快速扩展2026 年 8 月新增 Ling 3.0、Muse Glimmer、North Micro Vision Instruct 与 Shieldstral2026 年 7 月支持通过 ScatterMoEW4A16与 SonicMoEW4A4进行NVFP44-bitMoE LoRA 训练并且可以把 adapter 合并回普通的 NVFP4 checkpoint。2. 多模态训练除了纯文本模型Axolotl 支持视觉语言模型VLM与音频模型的微调包括 LLaMA-Vision、Qwen2-VL、Pixtral、LLaVA、SmolVLM2、GLM-4.6V、InternVL 3.5、Gemma 3n、PaddleOCR-VL、Muse Glimmer以及 Voxtral 等音频模型支持图像、视频与音频输入。仓库中对应的示例包括 llama-3-vision/lora-11b.yaml、qwen2-vl/lora-7b.yaml、pixtral/lora-12b.yml、gemma3n/gemma-3n-e2b-vision-audio-qlora.yml、voxtral/voxtral-mini-audio-qlora.yml 等。3. 丰富的训练方法Axolotl 覆盖了从 SFT 到偏好对齐再到强化学习的完整方法谱系全参微调Full Fine-tuning、LoRA、QLoRA、GPTQQAT 量化感知训练int8/int4/FP8/NVFP4/MXFP4FP8 混合精度训练以及NVFP4/MXFP4 MoE LoRA偏好对齐DPO、IPO、KTO、ORPO强化学习GRPO、GDPOGeneralized DPO奖励模型Reward ModellingRM与 Process Reward ModellingPRMAGENTS.md 给出了这些方法对应的配置键速查表DPO 用rl: dpoIPO 用rl: dpo, dpo_loss_type: [ipo]KTO 用rl: ktoORPO 用rl: orpoGRPO 用rl: grpoEBFT基于内部表征特征匹配奖励用rl: ebft。仓库中对应示例分布在 examples/qwen2/dpo.yaml、examples/llama-3/qlora-1b-kto.yaml、examples/qwen2/reward-model.yaml 等文件中。4. 性能优化README 列举了 Axolotl 内置或可选的性能优化手段Multipacking样本打包、Flash Attention 2/3/4、Xformers、Flex Attention、SageAttention、Liger Kernel、Cut Cross Entropy、ScatterMoE、Sequence ParallelismSP、LoRA 内存优化、多 GPU 训练FSDP1/FSDP2/DeepSpeed、多节点训练Torchrun/Ray。这些优化的依赖与版本约束可以在 pyproject.toml 的 dependencies 与 extras 中确认例如flash-attn、liger-kernel0.8.0、torchao0.17.0等。对应示例包括 examples/llama-3/fft-8b-liger-fsdp.yaml、examples/llama-3/lora-1b-kernels.yml 等。5. 灵活的数据集处理支持从本地文件、HuggingFace Hub 以及云存储S3、Azure、GCP、OCI加载数据集——这一点在 pyproject.toml 中有依赖佐证s3fs、gcsfs、adlfs、ocifs分别对应 S3、GCS、Azure Data Lake 与 OCI 文件系统。数据集格式的处理逻辑集中在 src/axolotl/prompt_strategies/ 目录每种type:值都映射到对应的处理函数如alpaca、chat_template、dpo、kto、orpo等。6. 云就绪项目同时发布 Docker 镜像 与 PyPI 包可运行于云平台与本地硬件。仓库的 docker/ 目录提供了Dockerfile-uv、Dockerfile-uv-base等多份镜像构建文件examples/cloud/ 还包含 baseten、modal 等云平台示例。三、环境要求与安装1. 硬件与软件要求根据 README 的 Quick Start 一节项目要求GPUNVIDIA GPUAmpere 或更新架构以支持bf16与 Flash Attention或 AMD GPUPython≥ 3.11推荐 3.12PyTorch≥ 2.11.0推荐 2.12.1注意 pyproject.toml 中声明的requires-python 3.10是包的最小约束而 README 给出的 3.11/3.12 是经过验证的推荐环境二者并不冲突。2. 使用 uv 安装推荐Axolotl 自 2026 年 4 月起转为uv-first工作流README 给出的标准安装流程如下# 1. 安装 uv如尚未安装安装后建议重启 shell curl -LsSf https://astral.sh/uv/install.sh | sh # 2. 根据系统设置 PyTorch 的 CUDA 后端示例为 cu130 export UV_TORCH_BACKENDcu130 # 3. 创建 Python 3.12 虚拟环境并激活 uv venv --python 3.12 source .venv/bin/activate # 4. 安装 PyTorch 与 Axolotldeepspeed extra uv pip install torch2.12.1 torchvision uv pip install --no-build-isolation axolotl[deepspeed] # 5.可选拉取官方示例配置与 DeepSpeed 配置 axolotl fetch examples axolotl fetch deepspeed_configsaxolotl[deepspeed]是 extras 安装的一种。从 pyproject.toml 可以看到完整的 extras 体系除deepspeed对应deepspeed0.18.6,0.19.0外还有flash-attn、ring-flash-attn、mamba-ssm、auto-gptq、galore、apollo、optimizers、ray、vllm、llmcompressor、opentelemetry等。需要说明的是pyproject.toml 的[tool.uv.conflicts]明确列出了若干互斥组合——例如 axolotl 与vllm、flash-attn、ring-flash-attn、mamba-ssm、auto-gptq等 extra 存在依赖冲突安装时应避免同时启用冲突的 extras。3. 使用 Docker 安装README 建议在自己的环境中安装容易出现依赖问题使用 Docker 往往更省心docker run --gpus all --ipchost --rm -it axolotlai/axolotl:main-latest仓库中的 docker/Dockerfile-uv 展示了镜像构建逻辑基于axolotlai/axolotl-base-uv通过uv pip install --no-build-isolation -e .[deepspeed,optimizers,ray]arm64 架构不装 deepspeed安装核心依赖再安装 cut cross entropy 等内核。此外 docker/Dockerfile-uv 还启用了 bash 自动补全脚本axolotl-complete.bash。4. 云平台一键使用README 列出了 RunPod、Vast.ai、PRIME Intellect、Modal、Novita、JarvisLabs.ai、Latitude.sh 等多个云 GPU 平台的现成模板可直接以预置镜像创建实例仓库内 examples/cloud/ 也提供了 modal.yaml、baseten.yaml 的部署参考。四、第一次微调实战用 LoRA 训练 Llama-3.2-1B1. 三步跑通README 给出的最小实战路径只有三步命令# 获取官方示例配置 axolotl fetch examples # 也可以指定自定义下载路径 axolotl fetch examples --dest path/to/folder # 使用 LoRA 训练 Llama 模型 axolotl train examples/llama-3/lora-1b.ymlfetch命令的实现位于 src/axolotl/cli/main.pyfetch_from_github逻辑它支持拉取examples、deepspeed_configs、docs三类资源train命令则由 src/axolotl/cli/train.py 承接。2. 逐段解读 lora-1b.yml 配置examples/llama-3/lora-1b.yml 是 README 指明的默认入门配置这里完整解读其含义它几乎涵盖了 Axolotl 配置文件的全部核心区块base_model: NousResearch/Llama-3.2-1B # Automatically upload checkpoint and final model to HF # hub_model_id: username/custom_model_namebase_model基座模型在 Hugging Face Hub 上的 ID是每个配置的必备项hub_model_id注释设置后会自动把 checkpoint 与最终模型上传到 Hugging Face。datasets: - path: teknium/GPT4-LLM-Cleaned type: alpaca val_set_size: 0.1 output_dir: ./outputs/lora-outdatasets数据集列表。这里从 HF Hub 加载teknium/GPT4-LLM-Cleanedtype: alpaca指定使用 src/axolotl/prompt_strategies/ 中的 alpaca 提示词策略instruction/input/output 三元组格式val_set_size: 0.1从训练集中切出 10% 作为验证集output_dircheckpoint 输出目录。adapter: lora lora_model_dir: sequence_len: 2048 sample_packing: true eval_sample_packing: trueadapter: lora选择 LoRA 适配器其他取值包括qlora或省略该项进行全参微调sequence_len: 2048序列最大长度sample_packing: true启用样本打包Multipacking把多个样本拼进一个序列以提升吞吐eval_sample_packing对验证集做同样处理。lora_r: 16 lora_alpha: 32 lora_dropout: 0.05 lora_target_modules: - gate_proj - down_proj - up_proj - q_proj - v_proj - k_proj - o_projlora_r/lora_alpha/lora_dropoutLoRA 的秩、缩放系数与 dropoutlora_target_modules注入 LoRA 的线性层这里覆盖了 Llama 架构的注意力q/k/v/o与 MLPgate/up/down全部门。wandb_project: wandb_entity: wandb_watch: wandb_name: wandb_log_model:以上是 Weights Biases 日志相关配置默认留空表示不启用或使用默认行为。gradient_accumulation_steps: 2 micro_batch_size: 2 num_epochs: 1micro_batch_size每步微批大小gradient_accumulation_steps梯度累积步数等效 batch size micro_batch_size × gradient_accumulation_stepsnum_epochs训练轮数。optimizer: adamw_8bit lr_scheduler: cosine learning_rate: 0.0002 bf16: auto tf32: false gradient_checkpointing: true resume_from_checkpoint: logging_steps: 1 attn_implementation: flash_attention_2optimizer: adamw_8bit8-bit AdamWbitsandbytes显著降低优化器状态内存lr_scheduler: cosinelearning_rate: 0.0002余弦退火学习率调度bf16: auto按硬件自动启用 bf16 混合精度tf32: false关闭 TF32gradient_checkpointing: true梯度检查点用计算换显存attn_implementation: flash_attention_2使用 Flash Attention 2README 强调这需要 Ampere 或更新的 GPU。loss_watchdog_threshold: 5.0 loss_watchdog_patience: 3 warmup_ratio: 0.1 evals_per_epoch: 4 saves_per_epoch: 1 weight_decay: 0.0 special_tokens: pad_token: |end_of_text| # save_first_step: true # uncomment this to validate checkpoint saving works with your configloss_watchdog_threshold/loss_watchdog_patienceloss 看门狗当 loss 超过阈值并持续若干步时触发保护逻辑这是 Axolotl 训练稳定性机制的一部分warmup_ratio: 0.1前 10% 步数做学习率预热evals_per_epoch: 4/saves_per_epoch: 1每个 epoch 内做 4 次评估、1 次保存special_tokens.pad_token把 pad token 设为 Llama 的 EOS token避免填充 token 造成干扰save_first_step注释取消注释可在第一步就保存 checkpoint用于尽早验证配置与保存链路是否正常。3. 配置驱动的底层原理Axolotl 的一份配置贯穿全流程并非口号从源码可以看到其支撑机制配置校验所有配置项由 src/axolotl/utils/schemas/config.py 中的AxolotlInputConfigPydantic 模型统一校验运行时通过axolotl config-schema可以导出完整的 JSON Schema详见下文CLI 与配置互通src/axolotl/cli/main.py 中的每个命令都通过add_options_from_config_options(AXOLOTL_CONFIG_CLI_OPTIONS)把 YAML 配置项同时暴露为命令行参数实现配置即参数、参数即配置训练器构建SFT 与 RLHF 分别由 src/axolotl/core/builders/ 下的TrainerBuilder类如causal.py、rl.py负责组装。五、完整 CLI 命令一览根据 README.md 与 src/axolotl/cli/main.py 的源码Axolotl 的 CLI 入口axolotl定义于 pyproject.toml 的[project.scripts]映射到axolotl.cli.main:main提供以下命令命令功能源码位置axolotl train config训练/微调单卡或自动检测的多卡cli/main.pytrainaxolotl preprocess config预分词数据集并校验配置加--debug可检查 token 化样本与标签掩码cli/main.pypreprocessaxolotl inference config推理支持--gradio浏览器界面与--chat多轮对话界面二者互斥cli/main.pyinferenceaxolotl evaluate config评估模型cli/main.pyevaluateaxolotl merge-lora config把训练好的 LoRA adapter 合并回基座模型cli/main.pymerge_loraaxolotl merge-sharded-fsdp-weights config合并 FSDP 分片权重cli/main.pymerge_sharded_fsdp_weightsaxolotl vllm-serve config启动 vLLM 服务供 GRPO/EBFT 训练使用cli/main.pyvllm_serveaxolotl quantize config模型量化cli/main.pyquantizeaxolotl fetch examples / deepspeed_configs / docs拉取示例、DeepSpeed 配置或文档支持--dest指定目录cli/main.pyfetchaxolotl delinearize-llama4 model outputLlama 4 专用把 linearized 权重还原cli/main.pydelinearize_llama4axolotl agent-docs [topic]查看面向 AI Agent 的文档见下节cli/main.pyagent_docsaxolotl config-schema导出配置 JSON Schemacli/main.pyconfig_schema几点值得注意的源码细节train命令支持--launcher参数accelerate/torchrun/python默认accelerate并通过--sweep指定超参数扫描配置src/axolotl/cli/main.py 中定义了LAUNCHER_COMMAND_MAPPING将 launcher 映射为底层进程启动命令train与evaluate等命令支持--之后的额外参数透传给启动器launcher_args如果配置中启用了use_raytrain会自动绕过 launcher 走 Ray 路径源码中_launcher None if kwargs.get(use_ray) else launcher。六、面向 AI Agent 的文档与 Schema 工具这是 Axolotl 近年新增的特色能力内置专门为 AI 编程 AgentClaude Code、Cursor、Copilot 等优化过的文档。这些文档随 pip 包一起分发无需 clone 仓库即可使用# 查看总览与可用训练方法 axolotl agent-docs # 按主题查看 axolotl agent-docs sft # 监督微调 axolotl agent-docs grpo # GRPO 在线强化学习 axolotl agent-docs preference_tuning # DPO、KTO、ORPO、SimPO axolotl agent-docs reward_modelling # 结果/过程奖励模型 axolotl agent-docs pretraining # 持续预训练 axolotl agent-docs --list # 列出所有主题如果你直接使用源码仓库这些 Agent 文档同样位于 docs/agents/如 docs/agents/sft.md、docs/agents/grpo.md、docs/agents/preference_tuning.md、docs/agents/reward_modelling.md、docs/agents/pretraining.md项目总览则写在 AGENTS.md。配套的程序化工具是config-schema# 导出完整配置 JSON Schema供程序化使用 axolotl config-schema # 只导出某个字段的 Schema axolotl config-schema --field adapter从 src/axolotl/cli/main.py 的实现看config-schema支持--format json|yaml底层直接调用AxolotlInputConfig.model_json_schema()生成当完整 Schema 生成失败例如某些torch.dtype无法 JSON 序列化时会降级为输出字段名、类型与默认值的简化版并可通过axolotl config-schema | jq .properties | keys快速浏览全部配置键。七、文档生态导航README 官方推荐了以下入口本文以仓库内路径给出对应文件安装选项docs/installation.qmd —— 不同环境的详细安装说明支持矩阵docs/support-matrix.qmd —— 功能支持、兼容性与已知缺口数据集加载docs/dataset_loading.qmd —— 从各种来源加载数据集数据集格式docs/dataset-formats/ —— 支持的格式与用法chat_template、alpaca、input_output 等多 GPU 训练docs/multi-gpu.qmd多节点训练docs/multi-node.qmdMultipackingdocs/multipack.qmd调试指南docs/debugging.qmdFAQdocs/faq.qmd此外AGENTS.md 还指向了 docs/getting-started.qmd快速上手教程、docs/choosing_method.qmdSFT vs DPO vs GRPO 方法选型、docs/rlhf.qmd、docs/grpo.qmd、docs/training_stability.qmdloss/NaN/OOM 排障等深度资料。分布式训练所需的 DeepSpeed 配置则存放在 deepspeed_configs/zero1/zero2/zero3 及 bf16/cpuoffload 变体还有配套的 torch_compile 版本。八、遥测机制与隐私Axolotl 内置默认开启、可关闭opt-out的遥测用于帮助项目团队理解使用方式并排定改进优先级。根据 README 与 src/axolotl/telemetry/manager.py 的实现收集内容基本的系统信息、模型类型、错误率绝不收集个人数据或文件路径关闭方式设置环境变量AXOLOTL_DO_NOT_TRACK1实现细节源码中_telemetry_enabled()会同时检查AXOLOTL_DO_NOT_TRACK与通用的DO_NOT_TRACK两个环境变量见 telemetry/manager.py任一为真即关闭且遥测上报按 GPU 去重避免多卡重复发送。更详细的说明见 docs/telemetry.qmd。九、贡献、引用与许可贡献项目欢迎社区贡献贡献指南与 CI 矩阵、GPU e2e 测试约定记录在 .github/CONTRIBUTING.md引用在论文或项目中引用 Axolotl 时README 给出了推荐格式software{axolotl, title {Axolotl: Open Source LLM Post-Training}, author {{Axolotl maintainers and contributors}}, url {https://github.com/axolotl-ai-cloud/axolotl}, license {Apache-2.0}, year {2023} }许可项目采用 Apache-2.0 协议详见 LICENSE。结语Axolotl 用一份 YAML 配置贯穿预处理、训练、评估、量化与推理的设计把 LLM 微调的复杂度收敛到了可配置、可复现、可审计的形态。本文从 README.md 出发覆盖了它的能力全景、安装路径uv/Docker/云平台、首个 LoRA 实战examples/llama-3/lora-1b.yml 逐字段解读、完整 CLI 命令cli/main.py 源码佐证、Agent 文档工具以及遥测隐私说明。下一步建议你顺着 docs/getting-started.qmd 走一遍更详尽的教程再用axolotl config-schema | jq .properties | keys探索全部配置项按需组合出属于你自己的训练配置。【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
