`llamafactory-cli webui` 与 LlamaBoard：它在这套体系里的位置

2026-08-09

本文所有事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，也没有打开过它的任何界面，文中所有说法都来自仓库里写着的源码与文档。

几乎所有人第一次听说 LlamaFactory 的 Web UI，脑子里都会默认它是一个”独立的图形化工具”。翻一遍 src/llamafactory/launcher.py 就会发现，它没那么独立——它是 llamafactory-cli 这一个入口下的一条子命令，和 train、chat、export 是平级的兄弟，共用同一套解析逻辑、同一套环境变量。

这篇不讲界面长什么样（我们没打开过，也不会去描述），只回答一个位置问题：这条子命令在整套体系里坐在哪，它和 CLI、和 webchat、和 API 服务分别是什么关系，以及启动它之前有哪几件事必须已经落地。

先把 USAGE 里那一行原样摆出来

launcher.py 里有一段 USAGE 常量，llamafactory-cli 的全部子命令都写在里面。与本篇直接相关的是这两行原文：

|   llamafactory-cli webchat -h: launch a chat interface in Web UI   |
|   llamafactory-cli webui: launch LlamaBoard                        |

以及 USAGE 末尾的那条 Hint 行：

| Hint: You can use `lmf` as a shortcut for `llamafactory-cli`.      |

有三个能直接读出来的细节值得记住。

第一，lmf 是官方给的短别名，写在 Hint 行里，不是社区自己起的。也就是说 lmf webui 和 llamafactory-cli webui 走的是同一条路。

第二，USAGE 一共 8 条子命令，其中 api / chat / export / train / webchat 这 5 条都写成了带 -h 的形式，而 webui / env / version 这 3 条没有带。这是 USAGE 文本里能直接看到的差别，至于为什么这么写、这三条到底接不接受参数，我们没有依据，不做推断——真要确认，以你本地 --help 的实际输出为准。

第三，命令解析那一行是 command = sys.argv.pop(1) if len(sys.argv) > 1 else "help"。翻译过来就是：不带任何参数直接敲 llamafactory-cli，默认走的是 help 分支。所以你会先看到这张 USAGE 表，而不是报错。

名字：LlamaBoard 还是 LLaMA Board

这里有一处仓库内部的写法差异，先说明白，免得你搜资料时以为是两个东西。

USAGE 行里写的是 launch LlamaBoard；README 里对应那一节的标题写的是 LLaMA Board GUI；README 的 Features 八条里，实验跟踪那一条列的又是 LlamaBoard。同一个东西，仓库里至少有这两种写法并存。

这不是孤例。launcher.py 的 WELCOME 横幅里，项目主页那行写的仍是带连字符的旧仓库名 https://github.com/hiyouga/LLaMA-Factory，而仓库当前的真实路径是 hiyouga/LlamaFactory。README 正文里 LLaMA-Factory 和 LlamaFactory 两种拼法也是混用的。

新旧写法并存这件事本身，是可以核实的；至于改名时间、原因、有没有重定向，我们一概没核实，不推断也不评价。对你的实际影响只有一条：搜 issue、翻博客时两种拼法都试一遍。

它在体系里的三个位置

第一个位置：入口层的另一半。 README 大标题下那句定位原文是 “Easily fine-tune 100+ large language models with zero-code CLI and Web UI”。这句话里的 “CLI and Web UI” 是并列的两条入口，Web UI 就是 webui 这条子命令。所谓”零代码”，准确含义是不用自己写训练脚本，不是”不用理解参数”——template、数据格式、显存约束这些东西，走哪条入口都躲不掉。

第二个位置：实验跟踪的一个选项。 README 的 Features 里，Experiment monitors 那一条把 LlamaBoard 和 TensorBoard、Wandb、MLflow、SwanLab 并列在一起。也就是说在官方的分类法里，它同时承担”配参数的界面”和”看训练过程的面板”两种角色。配置里 report_to 的可选值写在 examples/train_lora/qwen3_lora_sft.yaml 的注释里，是 [none, wandb, tensorboard, swanlab, mlflow]——注意这个枚举里没有 LlamaBoard 这一项：Features 那条把它和另外四个并列着写，而 report_to 的枚举里只有那四个。差异就陈述到这里，至于 LlamaBoard 的训练记录走的是哪条路径、要不要另配 report_to，我们没有依据，不推断。你自己那次训练到底往哪儿写日志，以你实际配置里 report_to 的取值为准。

第三个位置：技术栈上它是个网页服务。 README 那一节的标题写明它由 Gradio 驱动，实现目录是 src/llamafactory/webui/。既然是网页服务，它对外是否可达、要不要加访问控制，就是你自己环境里的事——这属于通用运维范畴，USAGE 那一行和 README 那一节都没有涉及，我们也不替它给方案。

`webui` 和 `webchat` 不是一回事

这两条子命令都会开一个浏览器界面，最容易混。回到 USAGE 原文的措辞：webchat 是 “launch a chat interface in Web UI”，webui 是 “launch LlamaBoard”。前者是对话界面，后者是 LlamaBoard。

和它们平级的还有 chat（“launch a chat interface in CLI”，命令行里的对话）和 api（“launch an OpenAI-style API server”，OpenAI 风格的 API 服务）。四条命令覆盖了”图形对话 / 命令行对话 / 服务化接口 / 面板”这四种用法。你要的是哪一种，先照 USAGE 的原文措辞对一遍，比看别人的教程截图靠谱。

启动之前必须已经落地的几件事

装是硬前提。 README 用 > [!IMPORTANT] 强调了一句 Installation is mandatory.，依赖表里 python 一行写的是 Minimum 3.11、Recommend >=3.11——下限就是 3.11。环境不达标的话，先解决版本，别急着启动界面。

如果你走 uv 建隔离环境，README 折叠块里给的那行示例本身就是启动 Web UI：

uv run llamafactory-cli webui

从源码装的四行照抄如下：

git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt

走官方镜像的话，README 给的是这一条：

docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest

README 原文写明这个镜像基于 Ubuntu 22.04 (x86_64)、CUDA 12.4、Python 3.11、PyTorch 2.6.0、Flash-attn 2.7.4。需要说明的是，这条命令原文里没有涉及任何端口或网络相关的写法，在容器里跑网页服务该怎么配，我们不替它发明。

环境变量要设在同一个终端里。 LlamaFactory 有相当一部分行为是靠环境变量控制的，Windows 和 Linux/macOS 的写法不一样，别混着抄。Hugging Face 下载有问题时切到 ModelScope Hub：

# Linux / macOS
export USE_MODELSCOPE_HUB=1

:: Windows
set USE_MODELSCOPE_HUB=1

然后把 model_name_or_path 填成 ModelScope 的 model ID，README 给的例子是 LLM-Research/Meta-Llama-3-8B-Instruct。切 Modelers Hub 是同一套写法，变量换成 USE_OPENMIND_HUB=1，model ID 示例是 TeleAI/TeleChat-7B-pt。环境变量是进程级的，在哪个终端里设就得在哪个终端里启动 llamafactory-cli webui——这是环境变量的一般行为，不是这个项目的文档条文，写在这里只是提醒新开一个终端窗口就得重设。

还有一个更前置的开关。 src/llamafactory/cli.py 的 main() 里，先判断环境变量 USE_V1 是否启用，再决定从 .v1 还是从当前包导入 launcher，最后才调 launcher.launch()。也就是说，入口切换发生在子命令解析之前——你敲的是 webui，但先被选中的是哪一套 launcher，取决于 USE_V1。仓库里确实同时存在旧实现和一套 v1/ 重写，两边的 webui 行为是否一致、v1 完成度如何，我们没有核实，别默认一样。

一个不该套过来的口径：`API_PORT`

这是很容易踩的一脚。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 里的字段可以在命令行上被盖掉。

但 API_PORT 是 api 这条子命令的口径。webui 那一行 USAGE 里没有写任何端口相关内容，我们也没有在事实范围内看到它的对应变量，所以不要把 API_PORT 想当然地套到 webui 上。真要确认，以 llamafactory-cli webui 在你本地的实际行为和 --help 输出为准。

界面不会替你判断硬件

最后提醒一句选型层面的事。Web UI 把方法选项摆在界面上让你挑，但挑得动不等于跑得起来。

README 有一张 Hardware Requirement 表，跟这件事直接相关的是 7B 那一列的两格：Full（bf16 或 fp16，32）标 120GB，Freeze/LoRA/GaLore/APOLLO/BAdam/OFT（16）标 16GB，相差 7.5 倍。同一列里差的是量级，不是几个百分点——这一行的名字（GaLore、APOLLO、BAdam、OFT）在这里只是表格里的行标签，它们各自是什么原理、收敛得快不快，我们没读过实现，不谈。

必须带上的限定是：这张表在表头上方被 README 自己标了 * estimated（估算），它不是实测占用，我们更没有跑过任何一次训练。所以这里只陈述”表里写的量级差是 7.5 倍”，不推导”你那张卡够不够”。这张表还有一处内部对不上的格子，我们另有一篇专门讲。

什么时候用它，什么时候别用

按你的处境倒推，比按功能表挑更准：

你不确定哪些参数是必填的，Web UI 解决的正是这个问题，它把配置项摆出来让你选；
你要的是可复现、能进版本控制、能进 CI 的流程，那就走 YAML 加 llamafactory-cli train——Quickstart 那三条命令的形式就是「命令 + 一个 YAML 路径」，YAML 本身是文件，天然能提交、能 diff、能在命令行上用 key=value 覆盖字段（api 那条追加 infer_backend=vllm 就是这个写法）。至于界面里选出来的配置以什么形式落盘、能不能导出成同样一份 YAML，我们没有依据，别默认它等价；
你只想开个对话界面试试模型，那要的是 webchat 或 chat，不是 webui；
你要的是给别的程序调的接口，那是 api 那条，端口走 API_PORT。

至于 8 条子命令各自的分工、USE_V1 背后的双轨、弹性启动那组变量、Quickstart 那三条命令的闭环，我们各有专门篇目讲，这篇只负责把 Web UI 这条子命令的位置放正。

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