对 `llamafactory-cli api -h` 输出的详细解读

最新推荐文章于 2026-03-31 03:50:34 发布

原创

最新推荐文章于 2026-03-31 03:50:34 发布 · 2.2k 阅读

标签

llamafactory-cli 是 LlamaFactory 项目提供的命令行接口工具，它允许用户通过命令行参数来配置和运行大型语言模型的各种任务，如预训练（PT）、有监督微调（SFT）、奖励模型训练（RM）、基于人类反馈的强化学习（PPO、DPO、KTO）以及模型推理和导出。

首先，命令输出的第一行 [2025-06-03 09:33:04,590] [INFO] [real_accelerator.py:191:get_accelerator] Setting ds_accelerator to cuda (auto detect) 是一个启动时的信息日志，表明程序已检测到并设置使用 CUDA（NVIDIA GPU）作为 DeepSpeed 加速器。这不是一个可配置的 API 参数，而是环境检测的结果。

接下来是 usage 部分，展示了命令的基本用法和所有可选参数。

usage: llamafactory-cli [-h] [--model_name_or_path MODEL_NAME_OR_PATH] ...

下面我们对各个参数选项 (options) 进行分类解读：

一、核心与模型加载参数

这些参数定义了基础模型、适配器以及加载行为。

-h, --help: 显示此帮助信息并退出。
--model_name_or_path MODEL_NAME_OR_PATH: 必需或常用。指定基础模型的路径（本地文件夹）或 Hugging Face Hub/ModelScope Hub 上的模型标识符。
--adapter_name_or_path ADAPTER_NAME_OR_PATH: 指定要加载的适配器（例如 LoRA 权重）的路径或 Hugging Face Hub 上的标识符。可以使用逗号分隔加载多个适配器。
--adapter_folder ADAPTER_FOLDER: 指定包含多个适配器权重的文件夹路径。
--cache_dir CACHE_DIR: 指定从 Hugging Face Hub 或 ModelScope Hub 下载的预训练模型的存储位置。
--model_revision MODEL_REVISION: 指定要使用的特定模型版本（可以是分支名、标签名或 commit ID）。默认为 main。
--low_cpu_mem_usage [LOW_CPU_MEM_USAGE] / --no_low_cpu_mem_usage: 是否使用低 CPU 内存模式加载模型，有助于在内存受限的环境中加载大模型。默认为 True。
--train_from_scratch [TRAIN_FROM_SCRATCH]: 是否从头开始训练，即随机初始化模型权重，而不是加载预训练权重。默认为 False。
--hf_hub_token HF_HUB_TOKEN: 用于登录 Hugging Face Hub 的认证令牌。
--ms_hub_token MS_HUB_TOKEN: 用于登录 ModelScope Hub 的认证令牌。
--om_hub_token OM_HUB_TOKEN: 用于登录 OpenModelDB Hub (魔搭社区) 的认证令牌。
--trust_remote_code [TRUST_REMOTE_CODE]: 是否信任并执行来自 Hub 上模型或数据集的远程代码。默认为 False，出于安全考虑，请谨慎开启。

二、Tokenizer 相关参数

配置分词器的行为。

--use_fast_tokenizer [USE_FAST_TOKENIZER] / --no_use_fast_tokenizer: 是否使用由 tokenizers 库支持的快速分词器。默认为 True。
--resize_vocab [RESIZE_VOCAB]: 是否调整分词器的词汇表大小以及模型嵌入层的大小，通常在添加新词汇时使用。默认为 False。
--split_special_tokens [SPLIT_SPECIAL_TOKENS]: 在分词过程中是否应分割特殊标记（special tokens）。默认为 False。
--add_tokens ADD_TOKENS: 要添加到分词器中的非特殊标记。使用逗号分隔多个标记。
--add_special_tokens ADD_SPECIAL_TOKENS: 要添加到分词器中的特殊标记。使用逗号分隔多个标记。

三、性能与优化参数

这些参数影响模型的训练和推理效率。

--rope_scaling {linear,dynamic,yarn,llama3}: RoPE (Rotary Position Embedding) 嵌入的缩放策略，用于扩展模型的上下文长度。
--flash_attn {auto,disabled,sdpa,fa2}: 是否启用 FlashAttention 以加速训练和推理。auto 会自动选择，sdpa (Scaled Dot Product Attention) 和 fa2 (FlashAttention-2) 是具体实现。默认为 AttentionFunction.AUTO。
--shift_attn [SHIFT_ATTN]: 是否启用 LongLoRA 提出的 Shift Short Attention (S^2-Attn) 机制。默认为 False。
--mixture_of_depths {convert,load}: 是否将模型转换为 Mixture-of-Depths (MoD) 结构或加载已转换的 MoD 模型。
--use_unsloth [USE_UNSLOTH]: 是否使用 Unsloth 的优化来进行 LoRA 训练，可以显著提升速度和减少显存。默认为 False。
--use_unsloth_gc [USE_UNSLOTH_GC]: 是否使用 Unsloth 的梯度检查点（gradient checkpointing），无需安装完整 Unsloth。默认为 False。
--enable_liger_kernel [ENABLE_LIGER_KERNEL]: 是否启用 Liger 内核以加速训练。默认为 False。
--moe_aux_loss_coef MOE_AUX_LOSS_COEF: 针对 Mixture-of-Experts (MoE) 模型，设置辅助路由器损失（auxiliary router loss）的系数。
--disable_gradient_checkpointing [DISABLE_GRADIENT_CHECKPOINTING]: 是否禁用梯度检查点。梯度检查点通过在前向传播中不保存中间激活，在反向传播时重新计算来节省显存，但会增加计算时间。默认为 False (即默认启用梯度检查点，具体看实现)。
--use_reentrant_gc [USE_REENTRANT_GC] / --no_use_reentrant_gc: 是否使用可重入（reentrant）的梯度检查点。默认为 True。
--upcast_layernorm [UPCAST_LAYERNORM]: 是否将 LayerNorm 层的权重提升到 fp32精度进行计算。默认为 False。
--upcast_lmhead_output [UPCAST_LMHEAD_OUTPUT]: 是否将语言模型头部（lm_head）的输出提升到 fp32 精度。默认为 False。
--pure_bf16 [PURE_BF16]: 是否以纯 bf16 精度进行训练（不使用 AMP 自动混合精度）。默认为 False。