奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

`llamafactory-cli` 的八个子命令：一张表说清各自干什么

2026-08-09

本文所有事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中所有命令与默认值均来自仓库源码和 README 的原文。

LlamaFactory 对外只给一个可执行入口 llamafactory-cli，后面跟一个子命令，一共八个。这八个的分工不是靠猜的，也不用去翻文档站——src/llamafactory/launcher.py 里有一个叫 USAGE 的字符串常量，把八条一行一条写死在源码里。

很多人上手时的第一个卡点不是参数，而是”我到底该敲哪条”：想聊两句发现有 chat 也有 webchat，想开界面发现有 webchat 也有 webui，想报 issue 发现不知道该贴什么环境信息。这篇就把这张表摊开，逐条说清它落到哪一层，以及哪几条藏着容易踩空的细节。

先把源码里那张表原样贴出来

下面这段是 launcher.py 里 USAGE 常量拼出来的内容，逐行原文：

----------------------------------------------------------------------
| Usage:                                                             |
|   llamafactory-cli api -h: launch an OpenAI-style API server       |
|   llamafactory-cli chat -h: launch a chat interface in CLI         |
|   llamafactory-cli export -h: merge LoRA adapters and export model |
|   llamafactory-cli train -h: train models                          |
|   llamafactory-cli webchat -h: launch a chat interface in Web UI   |
|   llamafactory-cli webui: launch LlamaBoard                        |
|   llamafactory-cli env: show environment info                      |
|   llamafactory-cli version: show version info                      |
| Hint: You can use `lmf` as a shortcut for `llamafactory-cli`.      |
----------------------------------------------------------------------

读这张表先注意一个可以直接数出来的差别：前五条（api / chat / export / train / webchat）后面都跟了 -h，后三条（webui / env / version）没有。源码里没有解释为什么这么写，我们也不去猜作者的意图，但这行文本本身就是可执行的：想摸清某个子命令能收哪些参数，最靠谱的动作永远是照着表敲一次 llamafactory-cli train -h，让它自己把当前版本的选项打出来，而不是找一篇教程抄参数——参数与默认值会随版本变动，而 -h 打印的永远是你这台机器上这一版。

两条藏在 USAGE 里、正文不太提的细节

这张表最后一行的 Hint 写着 You can use lmf as a shortcut for llamafactory-cli——lmf 是官方给的短别名，lmf train ... 和 llamafactory-cli train ... 指的是同一条命令。它不在 README 的醒目位置，只有把这张表打出来才会看见。

而要把这张表打出来，不需要记任何选项：launcher.py 里的命令解析在没拿到任何参数时，会把命令直接当成 help。所以在一台陌生机器上确认”这个环境到底装没装、装的是哪个入口”，空敲一次 llamafactory-cli 就够了；README 的 TIP 里另外写了 llamafactory-cli help 也能显示帮助信息，两条路殊途同归。

这两点各自对应的源码行我们另有一篇专门讲，这里点到为止，先把八条本身按用途过一遍。

训练、推理、合并：README 的三条 Quickstart 正好各占一条

README 的 Quickstart 用三条命令走完 Qwen3-4B-Instruct 的 LoRA 微调、推理和合并，原文如下：

llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml
llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

这三行把八个子命令里最核心的三个串起来了，也顺带交代了这套 CLI 的基本形态：子命令 + 一份 YAML。注意三条命令用的是三份不同目录下的 YAML（train_lora/、inference/、merge_lora/），不是同一份文件改改就能复用——训练侧和推理侧的配置在这套体系里是分开写的。

export 那条在 USAGE 里的描述是 merge LoRA adapters and export model，也就是说”合并适配器”和”导出模型”在这个项目里是同一个子命令的两件事，不用再找第二条命令。

至于这三份 YAML 里的字段各自什么含义、训练侧与推理侧的配置该怎么对上，我们另有专门篇目讲，这篇只管命令这一层。

两个 Web 入口不是一回事

webchat 和 webui 长得像，USAGE 里的描述却完全不同：

  • llamafactory-cli webchat -h: launch a chat interface in Web UI —— 网页版的聊天界面
  • llamafactory-cli webui: launch LlamaBoard —— 启动 LlamaBoard

注意 webui 后面没有 -h。README 里 LLaMA Board GUI 那一节给的命令就是光秃秃一行：

llamafactory-cli webui

README 的标题里写明了它由 Gradio 驱动，对应实现在 src/llamafactory/webui/ 目录下。

所以选哪个只看 USAGE 那两行的描述就够：要的是”网页里的聊天界面”，走 webchat；要的是 LlamaBoard 这个面板本身，走 webui。至于 LlamaBoard 打开后长什么样、有哪些功能，我们没有跑过，不描述，只能如实说它由 Gradio 驱动、实现在 src/llamafactory/webui/。这两个名字确实容易记混，记不住的时候还是回去敲一次空命令看表。

api：端口不走命令行参数，走环境变量

这条是八个里配置方式最特别的一个。README 给的 OpenAI 风格 API + vLLM 部署命令原文是：

API_PORT=8000 llamafactory-cli api examples/inference/qwen3.yaml infer_backend=vllm vllm_enforce_eager=true

一行里有两处值得单独拎出来：

端口通过 API_PORT 环境变量传，不是 --port 这种命令行参数。 找不到改端口的选项时，别再翻 -h 了，方向就不对。

命令行末尾那两段 infer_backend=vllm、vllm_enforce_eager=true 是 key=value 形式的覆盖。 也就是说 YAML 里的字段可以在命令行上被就地改掉，不必为了换一个后端复制一份新的 YAML。这个特性在你要跑一批对照实验时很省事。

infer_backend 的可选值写在 examples/inference/qwen3_lora_sft.yaml 的注释里，一共四个：

infer_backend: huggingface  # choices: [huggingface, vllm, sglang, ktransformers]

对应到 model_args.py，infer_backend 的默认值是 EngineName.HF。至于该选哪个，取决于你的硬件和部署形态，官方没给通用建议，我们也没有实测依据，这里只把四个取值和默认值如实列出来。

README 还指向 OpenAI 的 API 文档页作为接口参考，并给了两个示例脚本：图像理解 scripts/api_example/test_image.py、函数调用 scripts/api_example/test_toolcall.py。

env 和 version：报 issue 之前先敲的两条

这两条是八个里最不起眼、但在排查阶段最该先跑的。env 的描述是 show environment info，version 是 show version info。

和版本信息相关的还有一处：launcher.py 的 launch() 里构造了一个 WELCOME 横幅，格式化后包含这两行（我们只核实到它在 launch() 里被构造，至于它在哪些子命令下真的会打印出来，源码这一段没有交代，我们不猜）：

| Welcome to LLaMA Factory, version {VERSION}
| Project page: https://github.com/hiyouga/LLaMA-Factory |

这里有个能核实到的仓库内部不一致：横幅里写的项目主页仍是带连字符的旧名 LLaMA-Factory，而仓库当前的真实路径是 hiyouga/LlamaFactory，PyPI 包名是 llamafactory，命令行工具是 llamafactory-cli；README 正文里两种写法也是混用的。这里只陈述这个差异——改名的时间、原因、有没有重定向，我们都没核实过，不做推断。落到操作上就一句话：搜资料、翻 issue 的时候两种拼法都试一遍。

顺带一提，README 的 TIP 里指了 FAQ 的位置：https://github.com/hiyouga/LlamaFactory/issues/4614。遇到问题先读那条，再考虑开新 issue。

train 是八个里唯一会改写自己启动方式的

前面七条基本是”你敲什么就跑什么”，train 不是。launcher.py 在真正进训练之前，会先判断要不要把自己换成 torchrun 起分布式。判断链条是实读出来的：

  1. 若 USE_MCA 或 USE_MEGATRON_BRIDGE 任一被启用，强制 FORCE_TORCHRUN=1（源码注释原文就是 # force use torchrun）；
  2. 触发分布式训练的条件是：command == "train" 且（FORCE_TORCHRUN 被启用 或（get_device_count() > 1 且 没在用 ray 且 没在用 kt））。

第 2 条值得多看一眼。这是一个”或”的判断：FORCE_TORCHRUN 这一支和”设备数大于 1 且没在用 ray、没在用 kt”这一支，任意一支成立就走分布式。也就是说，在一台多卡机器上直接敲 llamafactory-cli train，即使你从头到尾没提过分布式，它也可能自己转成 torchrun 启动。这一点决定了后面所有”跟预期对不上”的排查方向。

对使用者的实际意义是：train 的启动方式不只由那份 YAML 决定，还由一组环境变量决定。所以当训练进程数、监听地址、节点数跟你想的不一样时，先去看环境变量，而不是先翻 YAML。判断依据是现成的——launcher.py 会打日志行 Initializing {nproc_per_node} distributed tasks at: {master_addr}:{master_port}；nnodes 大于 1 时还会多打一行 Multi-node training enabled: num nodes: {nnodes}, node rank: {node_rank}。这两行有没有出现、里面的数对不对，比任何猜测都直接：如果它压根没打这两行，那说明这次根本没走到分布式那一支，问题就不在这组变量上，得换个方向查。

这组环境变量各自叫什么、launcher.py 里给的默认值分别是多少（包括被源码注释标为 elastic launch support 的那一组），我们另有两篇专门讲，这篇不把那张表整个搬过来。这里只补一句边界：它们该设成多少，取决于你的集群拓扑和硬件，官方没给通用值，我们也没有实测依据，不给建议。

还有一个开关决定这八条落到哪套实现

src/llamafactory/cli.py 除许可证头以外，只有一个 main() 和一段 __main__ 入口，main() 的全部逻辑就这几行：

def main():
    from .extras.misc import is_env_enabled

    if is_env_enabled("USE_V1"):
        from .v1 import launcher
    else:
        from . import launcher

    launcher.launch()

也就是说，环境变量 USE_V1 决定加载 llamafactory.v1.launcher 还是 llamafactory.launcher。仓库里同时存在旧实现和一套 v1/ 重写（配套还有与旧 tests/ 并列的 tests_v1/、以及 examples/v1/）。

我们只核实了 v1/ 的目录文件名和 USE_V1 这个开关的存在，它的完成度、稳定性、该不该用、跟旧实现有什么差异，我们一概没有依据，不写。这里提它只是为了让你知道：同一条 llamafactory-cli train，在 USE_V1 开与不开的两种环境里，走的是不同的 launcher。

另外那段 __main__ 入口里调了 multiprocessing.freeze_support()，这是打包成可执行文件时 Windows 需要的那一句。

Windows 与 Linux/macOS 的写法差异

上面出现的 API_PORT=8000 llamafactory-cli api ...、以及 FORCE_TORCHRUN、USE_V1、NNODES 这些，都是环境变量，而不同 shell 设环境变量的语法不一样。README 里的命令是 Linux/macOS 的前置写法：

# Linux / macOS：README 原文那一行
API_PORT=8000 llamafactory-cli api examples/inference/qwen3.yaml infer_backend=vllm vllm_enforce_eager=true

这种”变量=值 空格 命令”的前置写法在 Windows 的 cmd 和 PowerShell 里都不成立，需要先设置再执行：

:: Windows cmd
set API_PORT=8000
llamafactory-cli api examples/inference/qwen3.yaml infer_backend=vllm vllm_enforce_eager=true

# Windows PowerShell
$env:API_PORT = "8000"
llamafactory-cli api examples/inference/qwen3.yaml infer_backend=vllm vllm_enforce_eager=true

后两段属于 shell 语法层面的差异说明，不是该项目官方文档的内容：命令主体、变量名和 key=value 覆盖都照抄自 README，我们只是把前置赋值拆成了两步，未逐项实测，具体以你所用 shell 的行为和 -h 的实际输出为准。同理，FORCE_TORCHRUN、USE_V1 这些开关在 Windows 上也要用 set / $env: 的方式设，别照着 Linux 的一行式写法敲。

这张表最后怎么用

把八条按”你现在处在哪个阶段”重排一遍，比按字母序记好用：

  • 确认环境：空敲 llamafactory-cli（等价于 help）看表 → env 看环境信息 → version 看版本
  • 训练：train，注意它可能自己转 torchrun
  • 验证效果：chat（命令行里聊）或 webchat（浏览器里聊）
  • 交付：export 合并 LoRA 适配器并导出
  • 上线：api，端口走 API_PORT，后端用 infer_backend= 在命令行覆盖
  • 全程：webui 起 LlamaBoard

记不住就用 lmf 那个短别名多敲几次，横竖八条都在同一张表里。

本文依据 LlamaFactory 官方仓库（github.com/hiyouga/LlamaFactory）的 README、data/README.md、examples/ 下的配置与 src/llamafactory/hparams/ 的参数定义整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装、训练或部署过任何模型，文中显存数字均为官方标注的估算值（README 原文标 * estimated）而非实测占用。参数与默认值随版本变动，请以 llamafactory-cli train -h 的实际输出为准。安全相关做法请结合自身环境评估，本文不构成安全方案建议。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员