官方藏在 USAGE 里的短别名 `lmf`，以及不带参数时默认走 help

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

llamafactory-cli 这个名字有 16 个字符，一天敲几十遍不算轻松。官方其实给了短名 lmf，就写在 USAGE 帮助文本末尾的那句 Hint 里。问题是这行 Hint 只出现在帮助输出里，而 README 的 Quickstart 三条命令、GUI 与 API 那几条示例命令，用的全是长名——于是你按 README 走一遍，很可能一次都不会看到它。

这篇只讲两件小事：这行 Hint 到底藏在什么地方、怎么才能把它调出来；以及紧挨着它的那句源码——不带任何参数时命令默认走 help——是怎么写的、意味着什么。八个子命令各自负责什么，我们另有一篇专门讲，这里不展开。

这行 Hint 的确切位置

它不是 README 里的一句话，而是硬编码在 src/llamafactory/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`.      |
----------------------------------------------------------------------

中间八行是子命令清单，紧接其后、闭合分隔线之前的那一行才是 Hint: 那句。注意它在版式上和上面八行是并列的，没有加粗、没有单独一节、也没有出现在 README 的任何一段示例里。这就是它容易被整批人漏掉的原因：你得先主动去看帮助，才知道有短名可用。

还有一点要说在前面：Hint 只告诉你这个短名存在，至于 lmf 具体由什么机制注册、在哪几种安装方式下一定会被装上，这行文本里没写，我们也不据此推断。

三条能把这块 USAGE 调出来的路径

第一条，README 自己给的 TIP，原文写的是 llamafactory-cli help 显示帮助信息。README 另一条 TIP 是遇到问题先读 FAQ，链接指向 https://github.com/hiyouga/LlamaFactory/issues/4614。

第二条，什么都不带地敲一下命令。这条路径来自 launcher.py 里的一行赋值，原文是：

command = sys.argv.pop(1) if len(sys.argv) > 1 else "help"

翻译成人话：程序去参数列表里取第 2 个元素当作子命令；如果参数列表长度不足（也就是你只敲了命令本身、后面什么都没跟），那么 command 直接取字符串 "help"。所以裸敲一下等价于显式要帮助。

这行还有个细节值得留意：用的是 pop(1) 而不是索引取值，也就是子命令这个词会被从参数列表里摘掉，而不是留在原地。

第三条，就是按那句 Hint，把上面两条里的 llamafactory-cli 换成 lmf。Hint 的字面语义是「shortcut for」，即同一个东西的短写法。

# README TIP 的原文写法
llamafactory-cli help

# 按 Hint 的字面语义换成短名
lmf help

以上第二条为按官方给出的别名语义组合的示例，未逐项实测，以官方文档与 --help 的实际输出为准。

「默认走 help」这件事本身是个设计取向

一个命令行工具在缺省参数时可以有很多种选择：挑一个默认动作跑起来、进交互模式、或者去读当前目录的某个约定文件。LlamaFactory 这一行代码给出的选择是最保守的那种：没给子命令，command 就取 "help"，不替你猜你想做什么。

对使用者来说，这带来一个实际的读法：就这一行的语义看，裸敲 lmf 或 llamafactory-cli 不会落进任何一个子命令的执行分支，而是走帮助那条路，所以它可以当一次「这条命令在不在」的探针来用。相比之下，USAGE 里列的 llamafactory-cli train、llamafactory-cli webui 这些是各有动作的子命令，不能随手敲。这一句是我们按这行赋值语句的字面语义读出来的结论，不是官方文档里的承诺，也没有实机验证过。

它不会替你猜的另一面是：想少打字，得靠短名 lmf，而不是靠省略子命令。这两件事在这一行代码里是分开的。

短名不生效时，分两步判定

这是这篇最有用的部分。现象通常是：你照着 Hint 敲了 lmf，shell 回你一句「找不到该命令」之类的话。

第一步，先分清是「短名没落地」还是「整套 CLI 都没落地」。 判定动作只有一个——把短名换成长名再敲一次帮助：

llamafactory-cli help

• 如果长名能正常打出上一节那块 USAGE，说明 CLI 这一层是通的，问题只在 lmf 这个名字有没有出现在你的可执行文件搜索路径里。
• 如果长名同样报找不到命令，那这篇文章帮不上你——问题在安装那一层，得回去看安装方式和环境，跟别名没关系。这就是「不是这个原因」的判据。

第二步，确认名字在不在搜索路径上。 下面两条是通用 shell 做法，不是 LlamaFactory 官方文档的内容：

:: Windows（cmd）
where lmf
where llamafactory-cli

# Linux / macOS
which lmf
which llamafactory-cli

两条对照着看：长名有输出、短名没输出，问题就锁定在别名这一个点上；两条都没输出，回到第一步的结论。

处置后怎么验证？还是那一句——把 lmf 裸敲一下或者 lmf help 敲一下，能打出那块以 Hint: 结尾的 USAGE，就算通了。这里之所以能拿「打不打得出 USAGE」当验收标准，正是因为上一节那行代码保证了裸敲只会打帮助、不会有别的动作。

Windows 和 Linux/macOS 在哪里会分叉

短名本身没有平台差异，真正会分叉的是跟它组合在一起的环境变量写法。

LlamaFactory 有相当一部分行为是靠环境变量控制的。比如 README 给的 OpenAI 风格 API 启动命令，原文是这样一条：

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

这条命令有两个值得单独记住的点：端口是通过 API_PORT 环境变量传的，不是命令行参数；后面的 infer_backend=vllm 是 key=value 覆盖，也就是 YAML 里的字段可以在命令行上被盖掉。

而写法上的分叉在于：把变量赋值直接前置在命令前面，是 Linux/macOS shell 的语法。Windows 的 cmd 不认这种写法，得先 set 再执行，分成两行：

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

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

这是 shell 层面的通用差异，README 给的是前者那种写法，没有专门附 Windows 版本。同样的分叉也适用于其它环境变量，比如控制分布式的 FORCE_TORCHRUN、NNODES、MASTER_PORT，以及下一节要提的 USE_V1——它们全都吃这套写法差异。至于这些变量各自的默认值和触发条件，我们另有一篇专门讲。

顺带一提，src/llamafactory/cli.py 的入口里调了 multiprocessing.freeze_support()，这个调用正是打包成可执行文件时 Windows 侧需要的。

短名指向的入口，其实还有一层

值得知道的是：不管你敲 lmf 还是 llamafactory-cli，进去之后并不一定是同一套实现。

src/llamafactory/cli.py 除许可证头之外的全部逻辑就这么几行：

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()


if __name__ == "__main__":
    from multiprocessing import freeze_support

    freeze_support()
    main()

也就是说，环境变量 USE_V1 决定加载的是 llamafactory.v1.launcher 还是 llamafactory.launcher。仓库里确实同时存在旧实现和一套 v1/ 重写，两条轨道并存，靠这一个开关切换。

这套 v1 重写的完成度、稳定性、是否推荐使用，我们一概没有依据，不做任何判断——只是提醒你：如果你在某个封装脚本或者容器里发现 USE_V1 被设过，那么同一个 lmf 打出来的东西可能和你在文档上看到的不完全对得上。关于 USE_V1 这条双轨，我们另有一篇专门讲。

还有个名字上的小坑

launch() 里除了 USAGE，还构造了一个欢迎横幅，格式化后包含这两行：

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

注意这里写的是带连字符的旧名 LLaMA-Factory，而仓库当前的真实路径是 hiyouga/LlamaFactory，PyPI 包名是 llamafactory，命令行是 llamafactory-cli，短名是 lmf。README 正文里两种写法也是混用的。

新旧写法在仓库里并存，这是可核实的差异，如实说到这儿就够了——改名时间、原因、有没有重定向，我们都没有核实过，不做推断。对你的实际影响只有一条：搜资料、翻 issue 的时候两种拼法都试一遍。

什么时候用短名，什么时候老老实实写长名

按你当下在干什么来选，比按「哪个更酷」来选靠谱：

• 你在自己的终端里手敲、反复试：用 lmf，这正是它存在的理由；
• 你在写 CI 脚本、Dockerfile、Makefile，或者给同事写交接文档：写长名 llamafactory-cli。理由不是短名有什么问题，而是 README 的 Quickstart 与 GUI、API 示例命令用的都是长名，别人拿你的脚本去比对文档时不用多做一次翻译；
• 你在提 issue 或者搜索报错：写长名。搜索命中率这件事上，文档里出现频率高的那个写法占优。

至于短名到底在哪些安装方式下一定可用，Hint 那一行没有承诺，我们也不替它承诺——真要确认，回到上面那两步判定，一条 where / which 比任何推断都快。

---

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