torchtune

概述 | 安装 | 开始使用 | 文档 | 社区 | 引用 torchtune | 许可证

📣 最新更新 📣

• 2025年5月: torchtune 已新增对 Qwen3 模型的支持！所有配置请查看 这里
• 2025年4月: Llama4 现已在 torchtune 中可用！您可以尝试我们的全参数和 LoRA 微调配置 这里
• 2025年2月: 多节点训练现已在 torchtune 中正式开放 使用指南！通过多节点进行全参数微调，以充分利用更大的批量大小和模型规模。
• 2024年12月: torchtune 现已支持 Llama 3.3 70B！按照我们的安装说明 这里 进行设置，然后运行任意一个配置 这里。
• 2024年11月: torchtune 发布了 v0.4.0，其中包含了对激活卸载和多模态 QLoRA 等激动人心功能的稳定支持。
• 2024年11月: torchtune 已将 Gemma2 添加到其支持的模型列表中！
• 2024年10月: torchtune 增加了对 Qwen2.5 模型的支持——相关配置请见 这里。
• 2024年9月: torchtune 现已支持 Llama 3.2 11B Vision、Llama 3.2 3B 和 Llama 3.2 1B 模型！按照我们的安装说明 这里 进行设置，然后运行任意一个文本配置 这里 或视觉配置 这里。

概述 📚

torchtune 是一个基于 PyTorch 的库，用于轻松构建、后训练和实验大型语言模型。它提供：

• 可自定义的训练配方，适用于 SFT、知识蒸馏、DPO、PPO、GRPO 以及量化感知训练；
• Llama、Gemma、Mistral、Phi、Qwen 等流行 LLM 的简单 PyTorch 实现；
• 利用最新 PyTorch API 实现的一流内存效率、性能优化和扩展能力；
• 使用 YAML 配置文件，方便地配置训练、评估、量化或推理流程。

后训练配方

torchtune 支持 完整的后训练生命周期。一个成功的后训练模型通常会结合以下几种方法。

监督微调 (SFT)

示例：tune run lora_finetune_single_device --config llama3_2/3B_lora_single_device
您也可以运行例如 tune ls lora_finetune_single_device 来查看所有可用配置。

知识蒸馏 (KD)

示例：tune run knowledge_distillation_distributed --config qwen2/1.5B_to_0.5B_KD_lora_distributed
您还可以运行例如 tune ls knowledge_distillation_distributed 查看所有可用配置。

强化学习 / 人类反馈强化学习 (RLHF)

示例：tune run lora_dpo_single_device --config llama3_1/8B_dpo_single_device
您也可以运行例如 tune ls full_dpo_distributed 查看所有可用配置。

量化感知训练 (QAT)

示例：tune run qat_distributed --config llama3_1/8B_qat_lora
您还可以运行例如 tune ls qat_distributed 或 tune ls qat_single_device 查看所有可用配置。

以上配置仅为入门示例。完整的配方列表可在 这里 找到。如果您希望填补其中的空白，请提交 PR！如果您有全新的后训练方法想要在 torchtune 中实现，也欢迎随时提出 Issue。

模型

对于上述配方，torchtune 支持许多在 Hugging Face Hub 或 Kaggle Hub 上可用的最先进模型。我们支持的部分模型如下：

我们一直在添加新模型，但如果您希望在 torchtune 中看到某个新模型，请随时 提交 issue。

内存与训练速度

以下是不同 Llama 3.1 模型的内存需求和训练速度示例。

[!注意] 为了便于比较，以下所有数据均基于批次大小为 2（无梯度累积）、数据集打包至序列长度 2048，以及启用 Torch 编译的情况。

如果您有兴趣在不同的硬件或使用不同的模型上运行，请查看我们的内存优化文档 这里，以找到适合您的设置。

*= 在一个完整训练周期内测量
**= 使用带有融合优化器的 CPU offload

优化标志

torchtune 提供了多个用于提高内存效率和性能的工具。下表展示了将其中一些技术依次应用于 Llama 3.2 3B 模型的效果。每种技术都是在前一种技术的基础上添加的，除了 LoRA 和 QLoRA，它们不使用 optimizer_in_bwd 或 AdamW8bit 优化器。

基线使用配方=full_finetune_single_device，模型=Llama 3.2 3B，批次大小=2，最大序列长度=4096，精度=bf16，硬件=A100

表格中的最后一行与基线 + 数据集打包相比，内存减少了 81.9%，而每秒处理的 token 数增加了 284.3%。

tune run lora_finetune_single_device --config llama3_2/3B_qlora_single_device \
dataset.packed=True \
compile=True \
loss=torchtune.modules.loss.CEWithChunkedOutputLoss \
enable_activation_checkpointing=True \
optimizer_in_bwd=False \
enable_activation_offloading=True \
optimizer=torch.optim.AdamW \
tokenizer.max_seq_len=4096 \
gradient_accumulation_steps=1 \
epochs=1 \
batch_size=2

安装 🛠️

torchtune 仅在最新的稳定版 PyTorch（当前为 2.6.0）以及预览版 nightly 版本上进行了测试，并利用 torchvision 对多模态 LLM 进行微调，同时借助 torchao 实现最新的量化技术；您也应安装这些库。

安装稳定版

# 安装稳定版 PyTorch、torchvision 和 torchao
pip install torch torchvision torchao
pip install torchtune

安装夜间版本

# 安装 PyTorch、torchvision 和 torchao 的夜间版本。
pip install --pre --upgrade torch torchvision torchao --index-url https://download.pytorch.org/whl/nightly/cu126 # 可选的完整选项包括 cpu/cu118/cu124/cu126/xpu/rocm6.2/rocm6.3/rocm6.4
pip install --pre --upgrade torchtune --extra-index-url https://download.pytorch.org/whl/nightly/cpu

您还可以查看我们的安装文档，以获取更多信息，包括从源代码安装 torchtune。

为了确认软件包是否正确安装，您可以运行以下命令：

tune --help

应该会看到如下输出：

usage: tune [-h] {ls,cp,download,run,validate} ...

欢迎使用 torchtune 命令行界面！

选项：
  -h, --help            显示此帮助信息并退出

...

开始使用 🚀

要开始使用 torchtune，请参阅我们的首次微调教程。我们的端到端工作流教程将向您展示如何评估、量化以及运行 Llama 模型的推理。本节的其余部分将以 Llama3.1 为例，快速概述这些步骤。

下载模型

请按照官方 meta-llama 仓库中的说明操作，以确保您有权访问官方 Llama 模型权重。确认权限后，您可以运行以下命令将权重下载到本地机器上。这还将下载分词器模型和负责任使用指南。

要下载 Llama3.1，您可以运行：

tune download meta-llama/Meta-Llama-3.1-8B-Instruct \
--output-dir /tmp/Meta-Llama-3.1-8B-Instruct \
--ignore-patterns "original/consolidated.00.pth" \
--hf-token <HF_TOKEN> \

[!提示] 设置您的环境变量 HF_TOKEN 或在命令中传递 --hf-token，以验证您的访问权限。您可以在 https://huggingface.co/settings/tokens 找到您的令牌。

运行微调配方

您可以在单个 GPU 上使用 LoRA 对 Llama3.1 8B 进行微调，命令如下：

tune run lora_finetune_single_device --config llama3_1/8B_lora_single_device

对于分布式训练，tune CLI 集成了 torchrun。 要在两个 GPU 上运行 Llama3.1 8B 的完整微调：

tune run --nproc_per_node 2 full_finetune_distributed --config llama3_1/8B_full

[!提示] 请务必将任何 torchrun 命令放在配方规范之前。此后输入的任何 CLI 参数都会覆盖配置，而不会影响分布式训练。

修改配置

有两种方法可以修改配置：

配置覆盖

您可以直接从命令行覆盖配置字段：

tune run lora_finetune_single_device \
--config llama2/7B_lora_single_device \
batch_size=8 \
enable_activation_checkpointing=True \
max_steps_per_epoch=128

更新本地副本

您也可以将配置复制到本地目录，并直接修改内容：

tune cp llama3_1/8B_full ./my_custom_config.yaml
已复制到 ./my_custom_config.yaml

然后，您可以通过将 tune run 命令指向本地文件来运行自定义配方：

tune run full_finetune_distributed --config ./my_custom_config.yaml

请查看 tune --help 以了解所有可能的 CLI 命令和选项。有关使用和更新配置的更多信息，请参阅我们的配置深度解析。

自定义数据集

torchtune 支持在各种不同类型的数据集上进行微调，包括 指令式、聊天式、偏好数据集等。如果您想了解更多关于如何将这些组件应用于您自己的自定义数据集进行微调的信息，请查看提供的链接以及我们的API 文档。

自定义设备

torchtune 支持在多种设备上进行微调，包括 NVIDIA GPU、Intel XPU、AMD ROCm、Apple MPS 和 Ascend NPU。如果您有兴趣在自定义设备上运行配方，例如 Intel XPU，请按照以下步骤操作。

步骤 1：参考 Intel GPU 入门指南 来配置您的环境。

步骤 2：通过 CLI 覆盖或配置更改来更新设备信息。 您可以直接从命令行覆盖配置字段：

tune run lora_finetune_single_device --config llama3_1/8B_lora_single_device device=xpu

或者编辑您本地的配置文件，将 device: cuda 替换为 device: xpu。

社区 🌍

torchtune 致力于与生态系统中的流行工具和库集成。以下仅是一些示例，更多仍在开发中：

• Hugging Face Hub 用于访问模型权重
• EleutherAI 的 LM Eval Harness 用于评估训练好的模型
• Hugging Face Datasets 用于访问训练和评估数据集
• PyTorch FSDP2 用于分布式训练
• torchao 用于低精度数据类型和训练后量化技术
• Weights & Biases 用于记录指标和检查点，并跟踪训练进度
• Comet 是另一个用于记录的选项
• ExecuTorch 用于设备端推理使用微调后的模型
• bitsandbytes 用于我们单设备配方中的低内存优化器
• PEFT 用于在 Hugging Face 生态系统中对 torchtune 模型进行持续微调或推理

社区贡献

我们非常珍视我们的社区以及各位优秀用户所做的贡献。我们将在此部分特别感谢其中一些贡献。如果您也想参与贡献，请参阅 CONTRIBUTING 指南。

• @SalmanMohammadi，为 torchtune 添加了使用 PPO 进行 人类反馈强化学习 (RLHF) 微调的完整端到端流程。
• @fyabc，为 torchtune 添加了 Qwen2 模型、分词器及相应流程的集成。
• @solitude-alive，为 torchtune 添加了 Gemma 2B 模型 的支持，包括流程修改、模型数值验证以及流程正确性检查。
• @yechenzhi，为 torchtune 添加了 直接偏好优化 (DPO) 的支持，包含流程、配置文件及正确性验证。
• @Optimox，为 torchtune 添加了所有 Gemma2 变体 的支持！

致谢 🙏

本仓库中的 Transformer 代码灵感来源于原始的 Llama2 代码。同时，我们也衷心感谢 EleutherAI、Hugging Face 和 Weights & Biases，感谢他们作为出色的合作伙伴，与我们一起完成了 torchtune 中的一些集成工作。此外，我们还想感谢生态系统中其他一些优秀的库和工具：

• gpt-fast，提供了高效的 LLM 推理技术，我们直接采用了这些现成的实现。
• llama recipes，为 Llama2 社区的发展奠定了基础。
• bitsandbytes，将多项内存与性能优化技术引入了 PyTorch 生态系统。
• @winglian 和 axolotl，在 torchtune 的设计与功能集方面提供了早期反馈与头脑风暴。
• lit-gpt，推动了 LLM 微调社区的进步。
• HF TRL，使奖励建模对 PyTorch 社区更加易用。

引用 torchtune 📝

如果您觉得 torchtune 库很有用，请在您的工作中按以下方式引用它。

@software{torchtune,
  title = {torchtune: PyTorch 的微调库},
  author = {torchtune 维护者及贡献者},
  url = {https//github.com/pytorch/torchtune},
  license = {BSD-3-Clause},
  month = apr,
  year = {2024}
}

许可证

torchtune 采用 BSD 3 许可证 发布。然而，您可能还需遵守其他法律义务，例如关于第三方模型的服务条款等，以规范您对相关内容的使用。

torchtune 快速上手指南

torchtune 是 PyTorch 官方推出的大语言模型（LLM）微调库，专为简化模型作者、后训练（Post-training）及实验流程而设计。它支持 SFT、LoRA/QLoRA、DPO、知识蒸馏等多种前沿训练方法，并针对 Llama、Qwen、Gemma、Mistral 等主流模型提供了开箱即用的配置。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+) 或 macOS。Windows 支持有限，建议使用 WSL2。
• Python: 版本需为 3.9 或更高。
• PyTorch: 需安装与您的 CUDA 版本匹配的最新版 PyTorch (建议 2.4+)。
• GPU: 推荐使用 NVIDIA GPU。对于大模型全量微调或多卡训练，显存需求较高；若资源有限，可使用 LoRA 或 QLoRA 方案。
• 依赖管理: 推荐使用 conda 或 venv 创建独立的虚拟环境。

前置检查： 确保已安装 git 和 pip。若使用国内网络，建议配置 pip 国内镜像源以加速下载：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 创建并激活虚拟环境

conda create -n torchtune python=3.10 -y
conda activate torchtune

2. 安装 PyTorch

请访问 PyTorch 官网 获取适合您硬件的安装命令。以下为 CUDA 12.1 的示例：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

注：国内用户可使用清华源加速 PyTorch 安装（如果可用），或直接使用官方源。

3. 安装 torchtune

通过 pip 直接安装最新稳定版：

pip install torchtune

或者，若您希望体验最新功能（如最新的 Qwen3 或 Llama4 支持），可从源码安装：

git clone https://github.com/pytorch/torchtune.git
cd torchtune
pip install -e .

4. 验证安装

运行以下命令查看可用食谱（recipes）列表，确认安装成功：

tune ls

基本使用

torchtune 的核心工作流是通过 tune run 命令加载预设的 YAML 配置文件来启动训练。以下是使用 LoRA 方法微调 Llama 3.2 3B 模型的最简示例。

第一步：下载模型权重

torchtune 支持直接从 Hugging Face Hub 下载模型。首次运行时会自动下载，也可手动预下载。 (注：若访问 Hugging Face 受限，请配置 HF_ENDPOINT 或使用国内镜像站如 ModelScope)

# 设置环境变量（可选，用于指定模型缓存目录）
export HF_HOME=~/.cache/huggingface

# 运行命令时工具会自动拉取模型，无需单独执行下载脚本

第二步：运行微调任务

使用内置配置文件启动单卡 LoRA 微调。以下命令将自动处理数据加载、模型构建和训练循环。

tune run lora_finetune_single_device --config llama3_2/3B_lora_single_device

命令解析：

• lora_finetune_single_device: 指定使用单卡 LoRA 微调食谱。
• --config llama3_2/3B_lora_single_device: 指定针对 Llama 3.2 3B 模型的预设配置。

第三步：自定义配置（可选）

您可以复制默认配置文件进行修改，以适应自己的数据集或超参数：

# 1. 查看配置内容
tune cp llama3_2/3B_lora_single_device ./my_custom_config.yaml

# 2. 编辑 my_custom_config.yaml (修改 dataset, batch_size, epochs 等)
# vim my_custom_config.yaml 

# 3. 使用自定义配置运行
tune run lora_finetune_single_device --config ./my_custom_config.yaml

其他常用场景示例

• 全量微调 (Full Finetune):

  tune run full_finetune_single_device --config llama3_2/3B_full_single_device
  

• 多卡分布式训练 (DDP):

  tune run --nproc_per_node 4 full_finetune_distributed --config llama3_2/3B_full_distributed
  

• 知识蒸馏 (Knowledge Distillation):

  tune run knowledge_distillation_distributed --config qwen2/1.5B_to_0.5B_KD_lora_distributed
  

• DPO (人类反馈强化学习):

  tune run lora_dpo_single_device --config llama3_1/8B_dpo_single_device
  

训练完成后，生成的适配器权重（adapter weights）或完整模型权重将保存在配置文件中指定的输出目录下，可直接用于推理或进一步评估。