torchtune 完全指南PyTorch 原生 LLM 后训练库的安装、配方体系与显存优化【免费下载链接】torchtunePyTorch native post-training library项目地址: https://gitcode.com/GitHub_Trending/to/torchtunetorchtune 是 PyTorch 团队推出的 LLM 后训练post-training库覆盖 SFT、LoRA/QLoRA、知识蒸馏、DPO/PPO/GRPO 与量化感知训练等完整生命周期。本文基于仓库根目录 README 及配套的tuneCLI 源码、配方注册表与 YAML 配置系统讲解其安装方式、内置配方与模型矩阵、显存/性能优化手段以及配置覆盖与多设备定制的实操细节帮助读者在单卡或多卡环境下完成一次可复现的微调实验。需要说明的是README 开头明确标注torchtune 自 2025 年起已停止积极维护开发于 2025 年收尾当前仓库处于归档状态本文所述内容以仓库实际代码版本 0.7.0见 version.txt为准。项目定位可 hack 的 PyTorch 原声配方README 将 torchtune 定义为一个用于便捷地编写、后训练与实验 LLM 的 PyTorch 库其核心卖点可归纳为四点可 hack 的训练配方recipesSFT、知识蒸馏KD、DPO、PPO、GRPO、量化感知训练QAT均以独立的 Python 脚本形式提供读者可直接阅读并改写简洁的 PyTorch 模型实现Llama、Gemma、Mistral、Phi、Qwen 等主流 LLM 均以纯 PyTorch 实现代码位于 torchtune/models/ 各子目录如 torchtune/models/llama4/_model_builders.py内存效率与性能利用 PyTorch 最新 APItorch.compile、FSDP2、torchao 等实现显存与吞吐优化YAML 配置驱动训练、评估、量化、推理均可通过 YAML 配置 命令行覆盖完成无需改代码。后训练配方支持矩阵torchtune 支持完整后训练生命周期成功的后训练通常会组合使用下表中多种方法。各配方在不同“权重更新方式 × 硬件规模”组合下的支持情况如下继承自 README 的支持矩阵SFT监督微调权重更新方式1 设备多设备多节点Full支持支持支持LoRA/QLoRA支持支持支持示例命令tune run lora_finetune_single_device --config llama3_2/3B_lora_single_device tune ls lora_finetune_single_device # 查看该配方支持的全部配置知识蒸馏KD权重更新方式1 设备多设备多节点Full不支持不支持不支持LoRA/QLoRA支持支持不支持示例tune run knowledge_distillation_distributed --config qwen2/1.5B_to_0.5B_KD_lora_distributed tune ls knowledge_distillation_distributed强化学习 / RLHF方法权重更新方式1 设备多设备多节点DPOFull不支持支持不支持DPOLoRA/QLoRA支持支持不支持PPOFull支持不支持不支持PPOLoRA/QLoRA不支持不支持不支持GRPOFull建设中支持支持GRPOLoRA/QLoRA不支持不支持不支持示例tune run lora_dpo_single_device --config llama3_1/8B_dpo_single_device tune ls full_dpo_distributed量化感知训练QAT权重更新方式1 设备多设备多节点Full支持支持不支持LoRA/QLoRA不支持支持不支持示例tune run qat_distributed --config llama3_1/8B_qat_lora tune ls qat_distributed # 或 tune ls qat_single_device配方体系在源码中的组织方式从源码结构看每个配方就是一个recipes/下的可运行 Python 脚本如 recipes/lora_finetune_single_device.py、recipes/full_finetune_distributed.py、recipes/knowledge_distillation_distributed.py、recipes/qat_lora_finetune_distributed.py而“配方名 → 脚本路径 → 可选配置列表”的映射统一登记在 torchtune/_recipe_registry.py 的_ALL_RECIPES中。tune ls与tune run都通过get_all_recipes()读取该注册表见 torchtune/_cli/ls.py因此用tune ls看到的每一个“配方 配置”对都真实存在于recipes/configs/目录中例如llama3_1/8B_full对应 recipes/configs/llama3_1/8B_full.yamlGRPO 相关配方目前带dev/前缀如dev/grpo_full_finetune_distributed、dev/async_grpo_full_finetune_distributed表明其处于实验阶段与上表中 GRPO “1 设备建设中”的状态一致。支持的模型与规模以下为 README 给出的受支持模型矩阵含模型实现与配置的仓库路径模型规模实现 / 配置Llama4Scout (17B x 16E)torchtune/models/llama4/_model_builders.py / recipes/configs/llama4/Llama3.370Btorchtune/models/llama3_3/_model_builders.py / recipes/configs/llama3_3/Llama3.2-Vision11B, 90Btorchtune/models/llama3_2_vision/_model_builders.py / recipes/configs/llama3_2_vision/Llama3.21B, 3Btorchtune/models/llama3_2/_model_builders.py / recipes/configs/llama3_2/Llama3.18B, 70B, 405Btorchtune/models/llama3_1/_model_builders.py / recipes/configs/llama3_1/Mistral7Btorchtune/models/mistral/_model_builders.py / recipes/configs/mistral/Gemma22B, 9B, 27Btorchtune/models/gemma2/_model_builders.py / recipes/configs/gemma2/Microsoft Phi414Btorchtune/models/phi4/ / recipes/configs/phi4/Microsoft Phi3Minitorchtune/models/phi3/ / recipes/configs/phi3/Qwen30.6B, 1.7B, 4B, 8B, 14B, 32Btorchtune/models/qwen3/ / recipes/configs/qwen3/Qwen2.50.5B, 1.5B, 3B, 7B, 14B, 32B, 72Btorchtune/models/qwen2_5/ / recipes/configs/qwen2_5/Qwen20.5B, 1.5B, 7Btorchtune/models/qwen2/ / recipes/configs/qwen2/模型权重从 Hugging Face Hub 或 Kaggle Hub 获取pyproject.toml 中声明了对huggingface_hub[hf_transfer]、safetensors、kagglehub的依赖对应 tune download 同时支持两条下载通道。显存占用与训练速度以下数据来自 README统一在“batch size 2无梯度累积、数据集 packing 至序列长度 2048、启用 torch.compile”的条件下测得便于横向比较模型微调方法可运行硬件单卡峰值显存Tokens/secLlama 3.1 8BFull finetune1x 409018.9 GiB1650Llama 3.1 8BFull finetune1x A600037.4 GiB2579Llama 3.1 8BLoRA1x 409016.2 GiB3083Llama 3.1 8BLoRA1x A600030.3 GiB4699Llama 3.1 8BQLoRA1x 40907.4 GiB2413Llama 3.1 70BFull finetune8x A10013.9 GiB使用 CPU offload fused optimizer1568Llama 3.1 70BLoRA8x A10027.6 GiB3497Llama 3.1 405BQLoRA8x A10044.8 GB653Tokens/sec 均为一个完整训练 epoch 的测量值。逐项叠加的优化杠杆Llama 3.2 3B 实测README 给出了在 Llama 3.2 3B 上逐项叠加优化技术的显存/吞吐变化基线配方full_finetune_single_devicebatch size 2序列长度 4096bf16A100。除 LoRA/QLoRA 两行外每一项技术都叠加在上一项之上LoRA/QLoRA 不使用optimizer_in_bwd与 AdamW8bit技术峰值显存 (GiB)显存变化Tokens/sec吞吐变化Baseline25.5-2091- Packed Dataset60.0135.16%7075238.40% Compile51.0-14.93%899827.18% Chunked Cross Entropy42.9-15.83%91741.96% Activation Checkpointing24.9-41.93%7210-21.41% 优化器步进融合进反向23.1-7.29%73091.38% Activation Offloading21.8-5.48%7301-0.11% 8-bit AdamW17.6-19.63%6960-4.67%LoRA8.5-51.61%821017.96%QLoRA4.6-45.71%8035-2.13%最终 QLoRA 行相比“baseline Packed Dataset”节省81.9%显存吞吐提升284.3%。复现最终行的完整命令tune run lora_finetune_single_device --config llama3_2/3B_qlora_single_device \ dataset.packedTrue \ compileTrue \ losstorchtune.modules.loss.CEWithChunkedOutputLoss \ enable_activation_checkpointingTrue \ optimizer_in_bwdFalse \ enable_activation_offloadingTrue \ optimizertorch.optim.AdamW \ tokenizer.max_seq_len4096 \ gradient_accumulation_steps1 \ epochs1 \ batch_size2这些覆盖项在配置中的真实落点可以对照 recipes/configs/llama3_2/3B_qlora_single_device.yaml 验证该文件自带注释是一份很好的参数参考model.lora_rank: 64注释越大精度与显存需求越高、lora_alpha: 128通常 alpha 2×rank、apply_lora_to_mlp: Truedataset.packed: False注释True 提升速度、batch_size: 4、gradient_accumulation_steps: 8用于放大有效 batchoptimizer._component_: torch.optim.AdamW且fused: True、lr: 3e-4学习率调度为 cosine with warmupnum_warmup_steps: 100loss._component_: torchtune.modules.loss.LinearCrossEntropyLoss命令行可切换为CEWithChunkedOutputLoss实现见 torchtune/modules/loss/ce_chunked_output_loss.pycompile: False注释True 提速并降显存、enable_activation_checkpointing: True、enable_activation_offloading: False激活值 offload 到 CPU见 torchtune/training/_activation_offloading.pydevice: cuda、dtype: bf16以及metric_logger、profiler默认禁用等日志与剖析配置。安装README 明确torchtune只针对最新 stable 版 PyTorch当时为 2.6.0与 nightly 预览版进行测试多模态微调依赖 torchvision量化技术依赖 torchao应一并安装。安装 stable 版# 安装 stable 版 PyTorch、torchvision、torchao pip install torch torchvision torchao pip install torchtune安装 nightly 版# 安装 PyTorch、torchvision、torchao nightly 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安装完成后可通过以下命令验证tune --help期望输出usage: tune [-h] {ls,cp,download,run,validate} ... Welcome to the torchtune CLI! options: -h, --help show this help message and exit ...从源码看tune入口由 pyproject.toml 中的[project.scripts] tune torchtune._cli.tune:main注册主解析器定义于 torchtune/_cli/tune.py。当前源码实际注册的子命令比 help 文案多一个cat查看配置内容完整集合为download / ls / cp / run / validate / cat分别对应 torchtune/_cli/download.py、torchtune/_cli/ls.py、torchtune/_cli/cp.py、torchtune/_cli/run.py、torchtune/_cli/validate.py、torchtune/_cli/cat.py。快速上手以下以 Llama3.1 为例串起“下载 → 微调 → 改配置 → 换数据/设备”的完整流程对应 README 的 Get Started 部分。1. 下载模型权重首先按 Hugging Facemeta-llama仓库的流程确认已获得官方 Llama 权重访问授权然后执行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 \该命令同时下载 tokenizer 与负责任使用指南。提示可通过环境变量HF_TOKEN或--hf-token参数校验访问权限。从 torchtune/_cli/download.py 可确认--ignore-patterns与--hf-token均被传入 huggingface_hub 下载流程用于跳过原始 checkpoint 文件并携带鉴权 token。2. 运行微调配方单卡 LoRA 微调 Llama3.1 8Btune run lora_finetune_single_device --config llama3_1/8B_lora_single_device分布式训练时tuneCLI 直接集成了 torchrun 的全部参数。双卡全量微调示例tune run --nproc_per_node 2 full_finetune_distributed --config llama3_1/8B_full注意torchrun 参数必须放在配方名之前配方名之后的参数会作为配置覆盖项不影响分布式启动。这一行为的实现逻辑在 torchtune/_cli/run.py 中非常清晰Run._add_arguments()直接复用了torch.distributed.run的 argparse 解析器L61-L80把 torchrun 的training_script/training_script_args重命名为recipe/recipe_args因此tune run天然支持--nproc_per_node等所有 torchrun 选项_is_distributed_args()L113-L117通过比较命令行总参数数与“配方 配方参数”数量判断用户是否传入了 torchrun 选项从而决定走单卡还是分布式路径_run_distributed()L82-L101在未显式指定 rendezvous endpoint 时默认启用 standalone 模式args.standalone True使同一台机器上可以同时跑多个分布式任务内置配方以绝对路径经runpy.run_path执行自定义配方则以模块点路径经runpy.run_module执行L103-L111。3. 修改配置的两种方式方式一命令行覆盖Config Overridestune run lora_finetune_single_device \ --config llama2/7B_lora_single_device \ batch_size8 \ enable_activation_checkpointingTrue \ max_steps_per_epoch128方式二复制本地配置后编辑Update a Local Copytune cp llama3_1/8B_full ./my_custom_config.yaml # 输出: Copied to ./my_custom_config.yaml然后直接指向本地文件运行tune run full_finetune_distributed --config ./my_custom_config.yaml配置解析、变量插值如${output_dir}与覆盖逻辑分别位于 torchtune/config/_parse.py、torchtune/config/_instantiate.py 与 torchtune/config/_utils.py_component_字段即“字符串 → 可调用对象”的实例化约定每个 YAML 顶层字段最终被解析为对应的 PyTorch 组件。4. 自定义数据集torchtune 内置多类数据集组件instruct 风格torchtune/datasets/_instruct.py、chat 风格torchtune/datasets/_chat.py、preference 偏好数据torchtune/datasets/_preference.py以及 alpaca、wikitext、stack exchange paired 等具体实现。配置中通过dataset._component_指定数据集类型如 recipes/configs/llama3_2/3B_qlora_single_device.yaml 中的torchtune.datasets.alpaca_cleaned_dataset换成自定义数据只需替换该组件路径并按需在 torchtune/datasets/ 下新增数据集类。5. 自定义设备torchtune 支持 NVIDIA GPU、Intel XPU、AMD ROCm、Apple MPS 与 Ascend NPU。以 Intel XPU 为例先按 PyTorch 官方 XPU 指南配置好环境再通过命令行覆盖或编辑本地配置切换设备tune run lora_finetune_single_device --config llama3_1/8B_lora_single_device devicexpu或在本地配置文件中把device: cuda改为device: xpu。源码依据是 torchtune/utils/_device.pyget_device()支持cuda / cpu / npu / xpu / mps五种设备类型get_safetensor_dtypes/设备探测按cuda → npu → xpu → mps → cpu顺序选择默认设备且每种设备都映射了对应的分布式通信后端nccl、hccl、ccl、gloo。生态集成README 列出的 torchtune 生态集成均能在仓库中找到对应代码落点Hugging Face Hub权重下载torchtune/_cli/download.pyEleutherAI LM Evaluation Harness评估训练后的模型recipes/eleuther_eval.pyHugging Face Datasets训练/评估数据集访问torchtune/datasets/_instruct.pyPyTorch FSDP2分布式训练封装于 torchtune/training/_distributed.pytorchao低精度 dtype 与训练后量化PTQ入口 recipes/quantize.py说明见 recipes/quantization.mdWeights Biases / Comet指标与 checkpoint 记录、训练进度追踪日志组件位于 torchtune/training/metric_logging.pybitsandbytes单卡低显存配方的低精度优化器示例 recipes/configs/llama2/7B_full_low_memory.yamlPEFT在 Hugging Face 生态中对 torchtune 产出的 LoRA 权重继续微调或推理。引用与许可若在工作中使用 torchtuneREADME 建议按如下 BibTeX 引用software{torchtune, title {torchtune: PyTorchs finetuning library}, author {torchtune maintainers and contributors}, url {https//github.com/pytorch/torchtune}, license {BSD-3-Clause}, month apr, year {2024} }torchtune 以BSD 3-Clause许可证发布见 LICENSE。需注意模型权重本身的授权由第三方条款约束如 Llama 权重需满足相应服务条款库代码的 BSD 许可并不覆盖权重与数据的使用限制。小结torchtune 用“独立 Python 配方脚本 YAML 配置 tuneCLI”的三层结构组织 LLM 后训练配方逻辑可读可改配置项可用命令行覆盖tune ls/tune run由 torchtune/_recipe_registry.py 统一驱动支持 SFTFull/LoRA/QLoRA、KD、DPO、PPO、GRPOdev、QAT 等完整后训练链路覆盖 Llama4 到 Qwen3 的十余个模型家族通过 packed dataset、torch.compile、chunked cross entropy、activation checkpointing/offloading、8-bit 优化器与 LoRA/QLoRA 的组合可在 Llama 3.2 3B 上实现约 81.9% 的显存节省与 284.3% 的吞吐提升相对 packed 基线当前仓库v0.7.0已停止积极维护适合作为 PyTorch 原生 LLM 后训练的工程参考与代码基线使用。【免费下载链接】torchtunePyTorch native post-training library项目地址: https://gitcode.com/GitHub_Trending/to/torchtune创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 torchtune 完全指南：PyTorch 原生 LLM 后训练库的安装、配方体系与显存优化
torchtune 完全指南PyTorch 原生 LLM 后训练库的安装、配方体系与显存优化【免费下载链接】torchtunePyTorch native post-training library项目地址: https://gitcode.com/GitHub_Trending/to/torchtunetorchtune 是 PyTorch 团队推出的 LLM 后训练post-training库覆盖 SFT、LoRA/QLoRA、知识蒸馏、DPO/PPO/GRPO 与量化感知训练等完整生命周期。本文基于仓库根目录 README 及配套的tuneCLI 源码、配方注册表与 YAML 配置系统讲解其安装方式、内置配方与模型矩阵、显存/性能优化手段以及配置覆盖与多设备定制的实操细节帮助读者在单卡或多卡环境下完成一次可复现的微调实验。需要说明的是README 开头明确标注torchtune 自 2025 年起已停止积极维护开发于 2025 年收尾当前仓库处于归档状态本文所述内容以仓库实际代码版本 0.7.0见 version.txt为准。项目定位可 hack 的 PyTorch 原声配方README 将 torchtune 定义为一个用于便捷地编写、后训练与实验 LLM 的 PyTorch 库其核心卖点可归纳为四点可 hack 的训练配方recipesSFT、知识蒸馏KD、DPO、PPO、GRPO、量化感知训练QAT均以独立的 Python 脚本形式提供读者可直接阅读并改写简洁的 PyTorch 模型实现Llama、Gemma、Mistral、Phi、Qwen 等主流 LLM 均以纯 PyTorch 实现代码位于 torchtune/models/ 各子目录如 torchtune/models/llama4/_model_builders.py内存效率与性能利用 PyTorch 最新 APItorch.compile、FSDP2、torchao 等实现显存与吞吐优化YAML 配置驱动训练、评估、量化、推理均可通过 YAML 配置 命令行覆盖完成无需改代码。后训练配方支持矩阵torchtune 支持完整后训练生命周期成功的后训练通常会组合使用下表中多种方法。各配方在不同“权重更新方式 × 硬件规模”组合下的支持情况如下继承自 README 的支持矩阵SFT监督微调权重更新方式1 设备多设备多节点Full支持支持支持LoRA/QLoRA支持支持支持示例命令tune run lora_finetune_single_device --config llama3_2/3B_lora_single_device tune ls lora_finetune_single_device # 查看该配方支持的全部配置知识蒸馏KD权重更新方式1 设备多设备多节点Full不支持不支持不支持LoRA/QLoRA支持支持不支持示例tune run knowledge_distillation_distributed --config qwen2/1.5B_to_0.5B_KD_lora_distributed tune ls knowledge_distillation_distributed强化学习 / RLHF方法权重更新方式1 设备多设备多节点DPOFull不支持支持不支持DPOLoRA/QLoRA支持支持不支持PPOFull支持不支持不支持PPOLoRA/QLoRA不支持不支持不支持GRPOFull建设中支持支持GRPOLoRA/QLoRA不支持不支持不支持示例tune run lora_dpo_single_device --config llama3_1/8B_dpo_single_device tune ls full_dpo_distributed量化感知训练QAT权重更新方式1 设备多设备多节点Full支持支持不支持LoRA/QLoRA不支持支持不支持示例tune run qat_distributed --config llama3_1/8B_qat_lora tune ls qat_distributed # 或 tune ls qat_single_device配方体系在源码中的组织方式从源码结构看每个配方就是一个recipes/下的可运行 Python 脚本如 recipes/lora_finetune_single_device.py、recipes/full_finetune_distributed.py、recipes/knowledge_distillation_distributed.py、recipes/qat_lora_finetune_distributed.py而“配方名 → 脚本路径 → 可选配置列表”的映射统一登记在 torchtune/_recipe_registry.py 的_ALL_RECIPES中。tune ls与tune run都通过get_all_recipes()读取该注册表见 torchtune/_cli/ls.py因此用tune ls看到的每一个“配方 配置”对都真实存在于recipes/configs/目录中例如llama3_1/8B_full对应 recipes/configs/llama3_1/8B_full.yamlGRPO 相关配方目前带dev/前缀如dev/grpo_full_finetune_distributed、dev/async_grpo_full_finetune_distributed表明其处于实验阶段与上表中 GRPO “1 设备建设中”的状态一致。支持的模型与规模以下为 README 给出的受支持模型矩阵含模型实现与配置的仓库路径模型规模实现 / 配置Llama4Scout (17B x 16E)torchtune/models/llama4/_model_builders.py / recipes/configs/llama4/Llama3.370Btorchtune/models/llama3_3/_model_builders.py / recipes/configs/llama3_3/Llama3.2-Vision11B, 90Btorchtune/models/llama3_2_vision/_model_builders.py / recipes/configs/llama3_2_vision/Llama3.21B, 3Btorchtune/models/llama3_2/_model_builders.py / recipes/configs/llama3_2/Llama3.18B, 70B, 405Btorchtune/models/llama3_1/_model_builders.py / recipes/configs/llama3_1/Mistral7Btorchtune/models/mistral/_model_builders.py / recipes/configs/mistral/Gemma22B, 9B, 27Btorchtune/models/gemma2/_model_builders.py / recipes/configs/gemma2/Microsoft Phi414Btorchtune/models/phi4/ / recipes/configs/phi4/Microsoft Phi3Minitorchtune/models/phi3/ / recipes/configs/phi3/Qwen30.6B, 1.7B, 4B, 8B, 14B, 32Btorchtune/models/qwen3/ / recipes/configs/qwen3/Qwen2.50.5B, 1.5B, 3B, 7B, 14B, 32B, 72Btorchtune/models/qwen2_5/ / recipes/configs/qwen2_5/Qwen20.5B, 1.5B, 7Btorchtune/models/qwen2/ / recipes/configs/qwen2/模型权重从 Hugging Face Hub 或 Kaggle Hub 获取pyproject.toml 中声明了对huggingface_hub[hf_transfer]、safetensors、kagglehub的依赖对应 tune download 同时支持两条下载通道。显存占用与训练速度以下数据来自 README统一在“batch size 2无梯度累积、数据集 packing 至序列长度 2048、启用 torch.compile”的条件下测得便于横向比较模型微调方法可运行硬件单卡峰值显存Tokens/secLlama 3.1 8BFull finetune1x 409018.9 GiB1650Llama 3.1 8BFull finetune1x A600037.4 GiB2579Llama 3.1 8BLoRA1x 409016.2 GiB3083Llama 3.1 8BLoRA1x A600030.3 GiB4699Llama 3.1 8BQLoRA1x 40907.4 GiB2413Llama 3.1 70BFull finetune8x A10013.9 GiB使用 CPU offload fused optimizer1568Llama 3.1 70BLoRA8x A10027.6 GiB3497Llama 3.1 405BQLoRA8x A10044.8 GB653Tokens/sec 均为一个完整训练 epoch 的测量值。逐项叠加的优化杠杆Llama 3.2 3B 实测README 给出了在 Llama 3.2 3B 上逐项叠加优化技术的显存/吞吐变化基线配方full_finetune_single_devicebatch size 2序列长度 4096bf16A100。除 LoRA/QLoRA 两行外每一项技术都叠加在上一项之上LoRA/QLoRA 不使用optimizer_in_bwd与 AdamW8bit技术峰值显存 (GiB)显存变化Tokens/sec吞吐变化Baseline25.5-2091- Packed Dataset60.0135.16%7075238.40% Compile51.0-14.93%899827.18% Chunked Cross Entropy42.9-15.83%91741.96% Activation Checkpointing24.9-41.93%7210-21.41% 优化器步进融合进反向23.1-7.29%73091.38% Activation Offloading21.8-5.48%7301-0.11% 8-bit AdamW17.6-19.63%6960-4.67%LoRA8.5-51.61%821017.96%QLoRA4.6-45.71%8035-2.13%最终 QLoRA 行相比“baseline Packed Dataset”节省81.9%显存吞吐提升284.3%。复现最终行的完整命令tune run lora_finetune_single_device --config llama3_2/3B_qlora_single_device \ dataset.packedTrue \ compileTrue \ losstorchtune.modules.loss.CEWithChunkedOutputLoss \ enable_activation_checkpointingTrue \ optimizer_in_bwdFalse \ enable_activation_offloadingTrue \ optimizertorch.optim.AdamW \ tokenizer.max_seq_len4096 \ gradient_accumulation_steps1 \ epochs1 \ batch_size2这些覆盖项在配置中的真实落点可以对照 recipes/configs/llama3_2/3B_qlora_single_device.yaml 验证该文件自带注释是一份很好的参数参考model.lora_rank: 64注释越大精度与显存需求越高、lora_alpha: 128通常 alpha 2×rank、apply_lora_to_mlp: Truedataset.packed: False注释True 提升速度、batch_size: 4、gradient_accumulation_steps: 8用于放大有效 batchoptimizer._component_: torch.optim.AdamW且fused: True、lr: 3e-4学习率调度为 cosine with warmupnum_warmup_steps: 100loss._component_: torchtune.modules.loss.LinearCrossEntropyLoss命令行可切换为CEWithChunkedOutputLoss实现见 torchtune/modules/loss/ce_chunked_output_loss.pycompile: False注释True 提速并降显存、enable_activation_checkpointing: True、enable_activation_offloading: False激活值 offload 到 CPU见 torchtune/training/_activation_offloading.pydevice: cuda、dtype: bf16以及metric_logger、profiler默认禁用等日志与剖析配置。安装README 明确torchtune只针对最新 stable 版 PyTorch当时为 2.6.0与 nightly 预览版进行测试多模态微调依赖 torchvision量化技术依赖 torchao应一并安装。安装 stable 版# 安装 stable 版 PyTorch、torchvision、torchao pip install torch torchvision torchao pip install torchtune安装 nightly 版# 安装 PyTorch、torchvision、torchao nightly 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安装完成后可通过以下命令验证tune --help期望输出usage: tune [-h] {ls,cp,download,run,validate} ... Welcome to the torchtune CLI! options: -h, --help show this help message and exit ...从源码看tune入口由 pyproject.toml 中的[project.scripts] tune torchtune._cli.tune:main注册主解析器定义于 torchtune/_cli/tune.py。当前源码实际注册的子命令比 help 文案多一个cat查看配置内容完整集合为download / ls / cp / run / validate / cat分别对应 torchtune/_cli/download.py、torchtune/_cli/ls.py、torchtune/_cli/cp.py、torchtune/_cli/run.py、torchtune/_cli/validate.py、torchtune/_cli/cat.py。快速上手以下以 Llama3.1 为例串起“下载 → 微调 → 改配置 → 换数据/设备”的完整流程对应 README 的 Get Started 部分。1. 下载模型权重首先按 Hugging Facemeta-llama仓库的流程确认已获得官方 Llama 权重访问授权然后执行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 \该命令同时下载 tokenizer 与负责任使用指南。提示可通过环境变量HF_TOKEN或--hf-token参数校验访问权限。从 torchtune/_cli/download.py 可确认--ignore-patterns与--hf-token均被传入 huggingface_hub 下载流程用于跳过原始 checkpoint 文件并携带鉴权 token。2. 运行微调配方单卡 LoRA 微调 Llama3.1 8Btune run lora_finetune_single_device --config llama3_1/8B_lora_single_device分布式训练时tuneCLI 直接集成了 torchrun 的全部参数。双卡全量微调示例tune run --nproc_per_node 2 full_finetune_distributed --config llama3_1/8B_full注意torchrun 参数必须放在配方名之前配方名之后的参数会作为配置覆盖项不影响分布式启动。这一行为的实现逻辑在 torchtune/_cli/run.py 中非常清晰Run._add_arguments()直接复用了torch.distributed.run的 argparse 解析器L61-L80把 torchrun 的training_script/training_script_args重命名为recipe/recipe_args因此tune run天然支持--nproc_per_node等所有 torchrun 选项_is_distributed_args()L113-L117通过比较命令行总参数数与“配方 配方参数”数量判断用户是否传入了 torchrun 选项从而决定走单卡还是分布式路径_run_distributed()L82-L101在未显式指定 rendezvous endpoint 时默认启用 standalone 模式args.standalone True使同一台机器上可以同时跑多个分布式任务内置配方以绝对路径经runpy.run_path执行自定义配方则以模块点路径经runpy.run_module执行L103-L111。3. 修改配置的两种方式方式一命令行覆盖Config Overridestune run lora_finetune_single_device \ --config llama2/7B_lora_single_device \ batch_size8 \ enable_activation_checkpointingTrue \ max_steps_per_epoch128方式二复制本地配置后编辑Update a Local Copytune cp llama3_1/8B_full ./my_custom_config.yaml # 输出: Copied to ./my_custom_config.yaml然后直接指向本地文件运行tune run full_finetune_distributed --config ./my_custom_config.yaml配置解析、变量插值如${output_dir}与覆盖逻辑分别位于 torchtune/config/_parse.py、torchtune/config/_instantiate.py 与 torchtune/config/_utils.py_component_字段即“字符串 → 可调用对象”的实例化约定每个 YAML 顶层字段最终被解析为对应的 PyTorch 组件。4. 自定义数据集torchtune 内置多类数据集组件instruct 风格torchtune/datasets/_instruct.py、chat 风格torchtune/datasets/_chat.py、preference 偏好数据torchtune/datasets/_preference.py以及 alpaca、wikitext、stack exchange paired 等具体实现。配置中通过dataset._component_指定数据集类型如 recipes/configs/llama3_2/3B_qlora_single_device.yaml 中的torchtune.datasets.alpaca_cleaned_dataset换成自定义数据只需替换该组件路径并按需在 torchtune/datasets/ 下新增数据集类。5. 自定义设备torchtune 支持 NVIDIA GPU、Intel XPU、AMD ROCm、Apple MPS 与 Ascend NPU。以 Intel XPU 为例先按 PyTorch 官方 XPU 指南配置好环境再通过命令行覆盖或编辑本地配置切换设备tune run lora_finetune_single_device --config llama3_1/8B_lora_single_device devicexpu或在本地配置文件中把device: cuda改为device: xpu。源码依据是 torchtune/utils/_device.pyget_device()支持cuda / cpu / npu / xpu / mps五种设备类型get_safetensor_dtypes/设备探测按cuda → npu → xpu → mps → cpu顺序选择默认设备且每种设备都映射了对应的分布式通信后端nccl、hccl、ccl、gloo。生态集成README 列出的 torchtune 生态集成均能在仓库中找到对应代码落点Hugging Face Hub权重下载torchtune/_cli/download.pyEleutherAI LM Evaluation Harness评估训练后的模型recipes/eleuther_eval.pyHugging Face Datasets训练/评估数据集访问torchtune/datasets/_instruct.pyPyTorch FSDP2分布式训练封装于 torchtune/training/_distributed.pytorchao低精度 dtype 与训练后量化PTQ入口 recipes/quantize.py说明见 recipes/quantization.mdWeights Biases / Comet指标与 checkpoint 记录、训练进度追踪日志组件位于 torchtune/training/metric_logging.pybitsandbytes单卡低显存配方的低精度优化器示例 recipes/configs/llama2/7B_full_low_memory.yamlPEFT在 Hugging Face 生态中对 torchtune 产出的 LoRA 权重继续微调或推理。引用与许可若在工作中使用 torchtuneREADME 建议按如下 BibTeX 引用software{torchtune, title {torchtune: PyTorchs finetuning library}, author {torchtune maintainers and contributors}, url {https//github.com/pytorch/torchtune}, license {BSD-3-Clause}, month apr, year {2024} }torchtune 以BSD 3-Clause许可证发布见 LICENSE。需注意模型权重本身的授权由第三方条款约束如 Llama 权重需满足相应服务条款库代码的 BSD 许可并不覆盖权重与数据的使用限制。小结torchtune 用“独立 Python 配方脚本 YAML 配置 tuneCLI”的三层结构组织 LLM 后训练配方逻辑可读可改配置项可用命令行覆盖tune ls/tune run由 torchtune/_recipe_registry.py 统一驱动支持 SFTFull/LoRA/QLoRA、KD、DPO、PPO、GRPOdev、QAT 等完整后训练链路覆盖 Llama4 到 Qwen3 的十余个模型家族通过 packed dataset、torch.compile、chunked cross entropy、activation checkpointing/offloading、8-bit 优化器与 LoRA/QLoRA 的组合可在 Llama 3.2 3B 上实现约 81.9% 的显存节省与 284.3% 的吞吐提升相对 packed 基线当前仓库v0.7.0已停止积极维护适合作为 PyTorch 原生 LLM 后训练的工程参考与代码基线使用。【免费下载链接】torchtunePyTorch native post-training library项目地址: https://gitcode.com/GitHub_Trending/to/torchtune创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考