torchtune 命令行界面¶

本页是关于使用 torchtune 命令行界面 (CLI) 的文档，它是一种下载模型、查找和复制相关配方/配置以及运行配方的便捷方式。当您安装 torchtune 时，它会自动可用。

入门指南¶

--help 选项将显示可通过 torchtune CLI 使用的所有可能的命令，以及每个命令的简短描述。

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

Welcome to the torchtune CLI!

options:
-h, --help            show this help message and exit

subcommands:
  {download,ls,cp,run,validate}
    download            Download a model from the Hugging Face Hub.
    ls                  List all built-in recipes and configs
    ...

--help 选项方便获取有关任何命令的更多详细信息。您可以随时使用它来列出所有可用的选项及其详细信息。例如，tune download --help 提供了有关如何使用 CLI 下载文件的更多信息。

下载模型¶

tune download <path> 命令从 Hugging Face 或 Kaggle Model Hub 下载任何模型。

--output-dir	保存模型的目录。注意：当 --source 设置为 kaggle 时，此选项尚不支持。
--output-dir-use-symlinks	与 output-dir 一起使用。如果设置为“auto”，将使用缓存目录，并且文件将被复制或符号链接到本地目录，具体取决于其大小。如果设置为 True，则无论文件大小如何，都将创建符号链接。如果设置为 False，则文件将从缓存中复制（如果已存在）或从 Hub 下载且不缓存。
--hf-token	Hugging Face API 令牌。Llama 等门控模型需要。
--ignore-patterns	如果提供，则不下载与任何模式匹配的文件。默认情况下，忽略 safetensors 文件以避免下载重复的权重。
--source {huggingface,kaggle}	如果提供，则从指定源 hub 上的提供的 <path> 下载模型权重。
--kaggle-username	用于身份验证的 Kaggle 用户名。私有模型或 Llama2 等门控模型需要。
--kaggle-api-key	Kaggle API 密钥。私有模型或 Llama2 等门控模型需要。您可以在 https://kaggle.com/settings 找到您的 API 密钥。

$ tune download meta-llama/Meta-Llama-3-8B-Instruct
Successfully downloaded model repo and wrote to the following locations:
./model/config.json
./model/README.md
./model/model-00001-of-00002.bin
...

$ tune download metaresearch/llama-3.2/pytorch/1b --source kaggle
Successfully downloaded model repo and wrote to the following locations:
/tmp/llama-3.2/pytorch/1b/tokenizer.model
/tmp/llama-3.2/pytorch/1b/params.json
/tmp/llama-3.2/pytorch/1b/consolidated.00.pth

下载门控模型

许多最近由 Meta 或 MistralAI 等组织发布的大型预训练模型要求您先同意使用条款和条件，然后才能下载其模型。如果是这种情况，您可以指定 Hugging Face 访问令牌。

您可以在这里找到访问令牌。

$ tune download meta-llama/Meta-Llama-3-8B-Instruct --hf-token <TOKEN>
Successfully downloaded model repo and wrote to the following locations:
./model/config.json
./model/README.md
./model/model-00001-of-00002.bin
...

注意

如果您愿意，您也可以使用 huggingface-cli login 永久登录到您机器上的 Hugging Face Hub。tune download 命令将从您的环境中提取访问令牌。

指定您不想下载的模型文件

某些检查点目录可能非常大，并且每次都下载所有文件可能会占用大量带宽和本地存储，即使您可能不需要很多文件。当同一检查点以不同格式存在时，这种情况尤其常见。您可以指定要忽略的模式，以防止下载名称匹配的文件。默认情况下，我们忽略 safetensor 文件，但如果您要包含所有文件，则可以传入空字符串。

$ tune download meta-llama/Meta-Llama-3-8B-Instruct --hf-token <TOKEN> --ignore-patterns None
Successfully downloaded model repo and wrote to the following locations:
./model/config.json
./model/README.md
./model/model-00001-of-00030.safetensors
...

注意

仅仅因为模型可以下载并不意味着它可以在 torchtune 的内置配方或配置中开箱即用 (OOTB) 地工作。有关受支持的模型系列和架构的列表，请参阅模型。

列出内置配方和配置¶

tune ls 命令列出 torchtune 中的所有内置配方和配置。

$ tune ls
RECIPE                                   CONFIG
full_finetune_single_device              llama2/7B_full_low_memory
                                         code_llama2/7B_full_low_memory
                                         llama3/8B_full_single_device
                                         mistral/7B_full_low_memory
                                         phi3/mini_full_low_memory
full_finetune_distributed                llama2/7B_full
                                         llama2/13B_full
                                         llama3/8B_full
                                         llama3/70B_full
...

复制内置配方或配置¶

tune cp <recipe|config> <path> 命令将内置配方和配置复制到提供的位置。这允许您制作库配方或配置的本地副本，以便直接为您自己编辑。有关如何使用此命令的示例，请参阅此处。

-n, --no-clobber	如果目标位置已存在，则不要覆盖
--make-parents	如果目标位置的父目录不存在，则创建父目录。如果未设置为 True，则在父目录不存在时会报错

$ tune cp lora_finetune_distributed .
Copied file to ./lora_finetune_distributed.py

运行配方¶

tune run <recipe> --config <config> 是 torchrun 的包装器。tune run 允许您按名称指定内置配方或配置，或按路径使用您的本地配方/配置。

要运行 tune 配方

tune run lora_finetune_single_device --config llama3/8B_lora_single_device

指定分布式 (torchrun) 参数

tune run 通过将配方之前的参数直接传递给 torchrun 来支持启动分布式运行。这遵循 torchrun 使用的模式，即在脚本（配方）之前指定分布式和主机标志。有关分布式设置的可用标志的完整列表，请参阅 torchrun 文档。

一些常用标志

--nproc-per-node	每个节点的工作进程数；支持的值：[auto, cpu, gpu, int]。
--nnodes	节点数，或节点范围，形式为 <minimum_nodes>:<maximum_nodes>。
--max-restarts	工作进程组在失败之前重新启动的最大次数。
--rdzv-backend	Rendezvous 后端。
--rdzv-endpoint	Rendezvous 后端端点；通常采用 <host>:<port> 形式。

tune run --nnodes=1 --nproc-per-node=4 lora_finetune_distributed --config llama3/8B_lora

注意

如果在配方之前未提供任何参数，tune 将绕过 torchrun 并直接使用 python 启动。当不需要分布式时，这可以简化配方的运行和调试。如果您想使用 torchrun 启动，但仅使用单个设备，则可以指定 tune run --nnodes=1 --nproc-per-node=1 <recipe> --config <config>。

运行自定义（本地）配方和配置

要将 tune run 与您自己的本地配方和配置一起使用，只需将文件路径而不是名称传递给 run 命令即可。您可以混合和匹配自定义配方与 torchtune 配置，反之亦然，或者您可以同时使用自定义配置和配方。

tune run my/fancy_lora.py --config my/configs/8B_fancy_lora.yaml

覆盖配置

您可以使用键=值格式从命令行覆盖现有参数。假设您要将训练 epoch 数设置为 1。有关配置覆盖的更多信息，请参阅此处。

tune run <RECIPE> --config <CONFIG> epochs=1

验证配置¶

tune validate <config> 命令将验证您的配置格式是否正确。

# If you've copied over a built-in config and want to validate custom changes
$ tune validate my_configs/llama3/8B_full.yaml
Config is well-formed!