`report_to` 的五个取值与 SwanLab 的九个字段

2026-08-09

本文事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中所有名字与默认值都是从仓库文档与源码里读出来的。

实验跟踪是那种”不配也能跑起来，出问题时才发现没记”的配置。LlamaFactory 把它分在了两个不同的层：一个是示例 YAML 里的枚举 report_to，一个是 src/llamafactory/hparams/finetuning_args.py 里成组出现的 SwanLab 字段。这两处名字不一样、粒度不一样、写的位置也不一样，混着看很容易把它们当成同一件事的两种写法。

这篇只做一件事：把这五个取值和这九个字段的确切拼写、默认值、所在层级逐个核对一遍，顺便说清哪些地方我们查到了、哪些地方我们没查过所以不猜。

先分清楚：一个是枚举，一个是字段组

report_to 是一个取值受限的配置项，它出现在示例配置里，五选一。

SwanLab 那九个是一组独立的超参字段，定义在 finetuning_args.py 里，每一个都有自己的名字和默认值，可以单独设。

从名字上看，前者写的是”往哪儿报”，后者写的是”报到 SwanLab 的时候，落在哪个项目、哪个工作区、用什么模式”。粒度不在一个层面上。这两处各自的运行时行为、以及它们之间怎么联动，我们没有读过对应的实现代码，所以这篇只核对名字、取值和默认值本身，不替你预测配错之后会发生什么。

`report_to` 的五个取值

这个枚举我们是在 examples/train_lora/qwen3_lora_sft.yaml 里核对的，注释行原文写明可选值是：

[none, wandb, tensorboard, swanlab, mlflow]

五个取值逐个念一遍：none、wandb、tensorboard、swanlab、mlflow。

有两点值得单独指出来。

第一，none 本身就是枚举里的一个取值，和另外四个并列写在同一行注释里，而不是靠留空表达。注释给的是”可选值有哪五个”这一层信息；至于不写这一项时配置解析会取什么、none 与留空是不是等价，注释里没写，我们也没有去读解析这项配置的代码，因此不做断言。你要确认的话，去看 llamafactory-cli train -h 里这一项的帮助文本。

第二，这五个取值都是小写单词。注释里写的是 wandb、tensorboard、mlflow、swanlab，而 README 的 Features 那一条里，同样这几个工具写的是 TensorBoard、Wandb、MLflow、SwanLab——两处大小写并不一致，配置侧是全小写标识符。抄配置的时候按配置里的写法抄，别按 README 的品牌写法抄。

至于示例文件里那一行实际写的是哪个取值，我们核对的是注释里的取值清单本身，不替你复述示例的具体写法——直接打开 examples/train_lora/qwen3_lora_sft.yaml 那一行看原文，比任何二手文章都准。

这五个取值，和 README 那条 Features 不完全重合

README 的 Features 里有一条叫 Experiment monitors，列的是 LlamaBoard、TensorBoard、Wandb、MLflow、SwanLab 等。

把它和 report_to 的五个取值摆在一起看：

README Features 的 Experiment monitors	`report_to` 枚举
LlamaBoard	——
TensorBoard	`tensorboard`
Wandb	`wandb`
MLflow	`mlflow`
SwanLab	`swanlab`
——	`none`

**LlamaBoard 出现在 Features 那一条里，但不在 report_to 的五个取值里；none 在枚举里，自然也不会出现在 Features 的工具列表里。**两处清单不完全重合，这是从两份原文直接比出来的差异，如实说到这儿就够了——为什么这么分、LlamaBoard 走的是不是另一条路，我们没有核实过，不做推断，也不拿这个去评价什么。

对你的实际影响只有一条：照着 README 的 Features 记名单，去填 report_to 的时候可能会填出一个不在枚举里的值。填之前回那份示例 YAML 的注释行对一遍。

SwanLab 的九个字段

finetuning_args.py 里 SwanLab 相关的字段一共九个，名字和默认值逐个抄如下：

字段	默认值
`use_swanlab`	`False`
`swanlab_project`	`"llamafactory"`
`swanlab_workspace`	`None`
`swanlab_run_name`	`None`
`swanlab_mode`	`"cloud"`
`swanlab_api_key`	`None`
`swanlab_logdir`	`None`
`swanlab_lark_webhook_url`	`None`
`swanlab_lark_secret`	`None`

这张表最值得看的是默认值的分布：九个字段里只有两个有非空默认——swanlab_project 是字符串 "llamafactory"，swanlab_mode 是字符串 "cloud"。剩下七个全是 None 或 False。

这是从 field(default=...) 直接读出来的，不是推断。它给你的判断依据是：九个字段里，只有 swanlab_project 这一个你不填也会拿到一个具体字符串值，而且这个字符串对所有不改它的人都是同一个 llamafactory；工作区、运行名、日志目录、密钥、飞书那两项，你不写就是空。所以”要不要显式写”这个问题，在这九个字段里的答案并不一致：前者是”默认值已经替你选了一个名字”，后者是”默认值什么都没选”。至于这个项目名在平台侧最终会怎么呈现，属于 SwanLab 那边的行为，不在我们核对范围内。要不要改、改成什么，取决于你们团队怎么组织实验，官方没给通用值，我们也不替你定。

按用途把九个字段分四组

九个平铺着看没结构，按名字前缀归一下就清楚了：

开关（1 个）：use_swanlab，默认 False。九个字段里唯一的布尔字段，从名字看是这一组的开关位，具体它控制什么，属于我们没读过的实现部分。

归属与命名（3 个）：swanlab_project（默认 "llamafactory"）、swanlab_workspace（默认 None）、swanlab_run_name（默认 None）。从名字看是”项目 / 工作区 / 本次运行”三个层次的命名，三个里只有 swanlab_project 有非空默认，另外两个默认都是空的。

运行模式与落盘（2 个）：swanlab_mode（默认 "cloud"）、swanlab_logdir（默认 None）。前者字面就是模式，后者字面是日志目录。我们没有读过处理这两个字段的实现代码，所以只说字段名义，不描述它们各自会导致什么行为。

凭证（1 个）：swanlab_api_key，默认 None。

飞书通知（2 个）：swanlab_lark_webhook_url 和 swanlab_lark_secret，默认都是 None。这两个是成对出现的，一个 URL 一个 secret。同样，我们没读过它们的实现，不描述通知会长什么样、什么时候触发。

分完组以后，一个直观的判断依据是：你要动的是哪一组？ 按字段名归属来看，命名相关的是前三个，mode 与 logdir 是一组，lark 那两个是一组。这四组在配置层面是九个各自独立、各自带默认值的字段，改其中一个不要求你把另外八个也填上。至于每一组具体触发什么行为，前面说过，我们没读过实现，只按名字归类。

`swanlab_api_key` 这一格要单独说

swanlab_api_key 是这九个字段里唯一的密钥类字段，默认 None。

写文档、贴示例、往仓库里提配置的时候，这一格的处理方式和其它八个不一样。本文所有涉及它的地方一律写成 <YOUR_API_KEY> 这样的占位符，不给任何真实密钥样式。

需要明确区分的是：“把密钥写进会进版本控制的 YAML 里是否合适”属于通用运维层面的考量，不是 LlamaFactory 官方文档的内容。这个字段在源码里就是一个默认为 None 的普通字符串字段，官方文档里推荐怎么传、有没有别的入口，我们没有核对到，所以这里不替它编一套做法出来。你自己那套密钥管理方案怎么落，按你所在环境的规范来。

两处开关的关系，我们没读过

现在把前后两段接起来看，一个很自然的问题是：report_to: swanlab 和 use_swanlab: True 是什么关系？两个都要设，还是设一个就够？

诚实的回答是：我们核对到的是”这两处各自存在、各自的名字和取值是什么”，没有读过把它们串起来的那段逻辑，所以不推断、不给结论。

但可以给一个可执行的确认动作：跑 llamafactory-cli train -h，在输出里同时搜 report_to 和 use_swanlab，看它们各自的帮助文本怎么写；再回 examples/ 下的示例配置，看同一份文件里是不是两处都出现了。以你手上那个版本的实际输出为准，比任何推断都可靠——包括比本文可靠。

这里也顺带说一句结构：仓库把超参按数据、模型、微调、生成、评测、训练、Megatron 桥接分在了 src/llamafactory/hparams/ 下的八个文件里。SwanLab 这九个字段落在 finetuning_args.py，而 report_to 是在示例 YAML 里出现的。同一个主题的配置项被放在不同层，是这个仓库里常见的情形——所以核对的时候，两层都要各自打开看一遍，别只认其中一处。

顺带说一句 W&B

README 里给了 W&B Logger 与 SwanLab Logger 两节使用说明，两者是并列出现的。但在配置字段这一层，我们核对到的是 SwanLab 有九个专属字段这件事；W&B 侧有没有对称的一组字段，不在我们这次核对的范围里，因此不做”两边对称”或”两边不对称”的任何断言。要用 W&B 的话，直接看 README 那一节的原文。

环境变量：Windows 和 Linux/macOS 别混着抄

这一节和实验跟踪没有直接关系，但同属”一行配置抄错就白跑”的范畴，而且 README 在这里罕见地把两个平台的写法都给了原文，值得在这儿提一次。

README 在讲下载源切换时给的两个环境变量，两个平台写法不同：

# Linux / macOS
export USE_MODELSCOPE_HUB=1

:: Windows
set USE_MODELSCOPE_HUB=1

切到 Modelers Hub 是同一套写法，变量换成 USE_OPENMIND_HUB=1。

要点是那个 export：README 给的是两种写法，Linux/macOS 侧用 export，Windows 侧用 set，两者不能互相替换。本站读者以 Windows 居多，抄命令的时候看清楚你抄的是哪一栏。

去哪儿核对

三个查证入口，按可靠程度排：

llamafactory-cli train -h 的实际输出——你那个版本的真实情况，优先级最高。
src/llamafactory/hparams/finetuning_args.py——九个 SwanLab 字段的定义处。
examples/train_lora/qwen3_lora_sft.yaml——report_to 那行注释里的取值清单。

搜 issue 的时候还有个小坑：这个仓库里新旧写法并存，src/llamafactory/launcher.py 的欢迎语里写的项目主页仍是带连字符的旧名 LLaMA-Factory，README 正文里两种拼法也都出现过。搜不到结果时，把 LlamaFactory 和 LLaMA-Factory 都试一遍，别因为拼法不同就以为搜的是另一个项目。

参数与默认值都会随版本变，本文只是给你一份 2026-08-09 那天的快照和一套核对路径。关于 finetuning_args.py 里其它几组参数、以及示例 YAML 与源码默认值对不上的那几处，我们另有专门篇目在讲。

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