LlamaFactory 模型微调
* estimated，本专题引用它时一律照此口径，
不会据此给出「你的卡够不够」的结论。
第二，本专题不给调参建议。
文中所有参数值都是源码里的 field(default=...)，
该调成多少取决于你的数据与硬件，官方没有给出通用值，我们也没有实测依据去补。
另外，仓库当前路径是 hiyouga/LlamaFactory，
但内部 launcher.py 的欢迎语等处仍残留旧名 LLaMA-Factory，
本专题只陈述这个差异、不推断原因。核对日 2026-08-09。
本专题共 50 篇。内容依据
官方仓库
的 README、data/README.md、examples/ 下的配置与
src/llamafactory/hparams/ 的参数定义整理。本专题内容为仓库源码与文档口径，
我们没有安装、训练或部署过任何模型，
因此不涉及训练耗时、显存实际占用与模型效果的任何描述。
参数随版本变动，请以 llamafactory-cli train -h 的实际输出为准。
LlamaFactory 到底是什么：零代码 CLI + Web UI 的微调工厂
LlamaFactory 常被当成一个微调脚本合集，它实际提供的是一层统一入口，把模型、数据格式、训练方法、实验跟踪和推理服务收进同一套命令行与界面。本文按官方仓库当前内容，讲清它的身份坐标、零代码具体指什么、八条特性各自收敛哪一层、三条免装环境的云端试用路径，以及它明确外包出去、不替你做的那几件事。
装起来：依赖、显存与三条安装路径
八个必需依赖各自卡在哪个版本、官方镜像里到底装了什么、下不动 Hugging Face 时用哪两个环境变量切源。这一组还专门拆那张显存表怎么读——README 自己标了 estimated，它是估算不是实测，表里还有一格与通用公式对不上。
八个必需依赖与五个可选依赖：版本下限和推荐值分别卡在哪
LlamaFactory 的 README 里有两张 Requirement 表，八条 Mandatory、五条 Optional，每条都分 Minimum 与 Recommend 两列。这篇逐格摊开这十三行，讲清哪一行是硬下限、哪几条只在你用到对应功能时才需要，以及为什么官方没给版本组合矩阵。
★ 显存表怎么读：`* estimated` 这四个字与那个对不上的格子
LlamaFactory 的 Hardware Requirement 表被当成选卡依据，但表头上方那行 `* estimated` 说明它是官方标注的估算而非实测占用。本文逐格照抄这张表，讲清它的四个坐标轴怎么读、行为什么是「方法加精度」的组合、通用列的系数是什么意思，并如实指出 2-bit 那一格与通用列公式对不上的地方。
源码、Docker、uv：三条安装路径分别适合谁
LlamaFactory 的 README 把安装拆成源码、Docker 镜像、uv 隔离环境三条路，还外加三条免装环境的云端入口。这篇按仓库当前文档逐条抄清每条路的命令、前置条件和它各自照顾的处境，讲清 Python 3.11 这条下限卡在哪、官方镜像里预置了什么、Windows 换下载源为什么要单写一行，以及为什么装法不改变显存那张估算表。
官方镜像里到底装了什么：Ubuntu 22.04 + CUDA 12.4 + PyTorch 2.6.0
LlamaFactory 官方 Docker 镜像的 README 只用一句话交代了里面装的五个版本号。本文把这句原文拆开，逐项对照 README 的 Requirement 依赖表，说清镜像锁住了哪几层、哪几格与 Recommend 对不上、镜像不负责什么，以及自建镜像与 Windows 侧环境变量该怎么写。
下不动 Hugging Face：两个环境变量切到 ModelScope 与 Modelers
LlamaFactory 的 README 为「Hugging Face 下载有问题」这个场景准备了两个环境变量。本文按仓库当前内容讲清两个变量的写法、Windows 与 Linux/macOS 的差别、光设变量为什么不够、还要同步改哪个字段、三个 Hub token 各叫什么，以及什么情况说明你的问题不在下载源。
`report_to` 的五个取值与 SwanLab 的九个字段
LlamaFactory 的实验跟踪配置分散在两层：示例 YAML 注释里的 `report_to` 五个取值，和 `finetuning_args.py` 里成组的九个 SwanLab 字段。本文逐个核对它们的确切拼写、默认值与所在层级，讲清哪两个字段有非空默认、密钥字段怎么脱敏，以及哪些联动逻辑我们没读过因此不做推断。
Day 0 / Day 1 支持表与更新日志：怎么读才不会读成承诺
LlamaFactory 的 Day 0 / Day 1 支持表和 README 更新日志常被当成路线图，于是「日志里写了支持 X」被理解成「我现在就能跑 X」。本文按官方仓库当前内容，讲清这两块记录的到底是什么、一条日志怎么落到可核查的字段与环境变量上、「支持」覆盖不到的三件事，以及该以仓库里的哪些位置为准。
跑起来：CLI、启动器与分布式默认值
八个子命令各干什么、官方藏在 USAGE 里的短别名 lmf、什么时候会自动走分布式（launcher.py 里那九个环境变量的默认值决定的）、弹性启动那组变量，以及一个 USE_V1 开关背后并存的两套实现。
`llamafactory-cli` 的八个子命令：一张表说清各自干什么
LlamaFactory 对外只暴露一个命令行入口，八个子命令分别管训练、推理、导出、两种 Web 界面和两条排查路径。本文照抄 launcher.py 里的 USAGE 原文表，讲清这八条各自对应什么、api 的端口为什么走环境变量、train 为什么是唯一会自己改写启动方式的那一条。
官方藏在 USAGE 里的短别名 `lmf`，以及不带参数时默认走 help
LlamaFactory 的 USAGE 帮助文本里有一句 Hint：`lmf` 是 `llamafactory-cli` 的短别名，但照 README 的 Quickstart 走一遍基本碰不到它。本文按源码讲清 Hint 在哪、`launcher.py` 里默认走 help 那行怎么读、短名不生效时怎么两步判定。
什么时候会自动走分布式：`launcher.py` 里的九个环境变量默认值
同一条 llamafactory-cli train 命令，在单卡和多卡机器上走的是两条启动路径，决定它的不是 YAML，而是 launcher.py 里的一段判断和九个只从环境变量读的值。本文按源码列出触发条件、九个默认值、Windows 与 Linux 的设法差异和判定方法。
`MAX_RESTARTS` / `RDZV_ID` / `MIN_NNODES`：被标为弹性启动的那组变量
LlamaFactory 的分布式行为不写在命令行参数里，而写在 launcher.py 读的一串环境变量里。本文逐个核对这组变量在源码中的确切名字与默认值，说清其中哪三个压根没有默认值、分布式路径要满足什么条件才会被触发、怎么从日志确认自己走的是哪条分支，以及为什么这篇不给任何推荐值。
一个 `USE_V1` 环境变量背后：仓库里并存的两套实现
LlamaFactory 的入口文件 cli.py 除许可证头外只有十几行，核心是一个 if：环境变量 USE_V1 决定加载 v1 目录下的 launcher 还是旧的 launcher。本文逐行拆这段代码，实读 v1/ 的目录结构与配套的 tests_v1/、examples/v1/，说清双轨并存对查资料、对齐文件路径意味着什么。
训练、推理、合并三条命令：README 唯一抬进 Quickstart 的闭环
README 只把 train、chat、export 三条命令抬进了 Quickstart，它们不是三个独立 demo，而是字段严格对齐的一条链。本文逐行对照三份 YAML，讲清靠哪几个标识串起来、哪些字段必须两侧一致、合并那步的大写禁令原文写的是什么，以及 Windows 侧的写法差异。
`llamafactory-cli webui` 与 LlamaBoard：它在这套体系里的位置
很多人把 LlamaFactory 的 Web UI 当成"另一个产品"，其实它只是同一个 CLI 入口下的一条子命令。本文按官方仓库当前内容，讲清 USAGE 里那一行原文写了什么、LlamaBoard 与 webchat 的分工、启动前必须先落地的安装与环境变量、以及为什么 API 那条的端口口径不能套到它头上。
选对模型与 template
53 行模型表为什么不等于「100+ 模型」、训练和推理必须用同一个 template 这条最容易翻车的规则、_nothink 后缀在区分什么、base 与 instruct 的取值差异，以及那张 8×6 全打勾的训练矩阵能读出什么、不能读出什么。
53 行模型表怎么读：为什么它不等于「100+ 模型」
LlamaFactory 的 README 顶部写着支持 100+ 模型，而 Supported Models 那张表实读只有 53 行，两个数字说的不是同一件事。本文讲清这张表三列各自的语义、第三列 template 才是要抄进 YAML 的值、表下六条注解里哪几条是硬规则，以及 `-`、`empty`、斜杠、`_nothink` 几种写法怎么读。
训练和推理必须用同一个 `template`，这是 LlamaFactory 最容易翻车的一条
LlamaFactory 的 README 在模型表下方用一句全大写的注解要求训练与推理使用同一个 template，但这个参数分散在训练、推理、合并导出三份不同目录的 YAML 里。本文按仓库当前内容说明它出现在哪几层、三份示例配置怎么严格对齐、怎么逐项比对确认自己是不是踩了这条，以及哪些情况可以把这条排除掉。
`_nothink` 后缀出现在哪三处，它在区分什么
LlamaFactory 的支持模型表里，Template 列有三个取值带 `_nothink` 后缀。这篇把这三行逐一找出来，讲清后缀在区分什么、它和 `enable_thinking` 参数分别坐在哪一层、为什么训练侧和推理侧必须填同一个值，以及表里那两处不成对的格子该怎么看待。
表里 template 写 `-` 的四个模型：base 与 instruct 的取值规则
LlamaFactory 的支持模型表里有四行的 Template 列写着一个横杠，很多人把它当成「还没适配」。它其实对应表下注解里的一条规则：base 模型的 template 可以从通用取值里选，instruct/chat 模型必须用对应的那个。本文讲清这四行是哪四行、横杠与名字就叫 empty 的 template 有什么区别、判断依据在哪个源码文件里，以及为什么这条规则没法给出「推荐值」。
视觉、音频、全模态：十几个独立命名的多模态 template
LlamaFactory 的多模态支持不是一个开关，而是模型表 Template 列里十几个各自独立命名的字符串。本文按官方仓库当前内容，把视觉、视频、音频、全模态这几类的 template 名逐类摘出来，讲清斜杠分档怎么读、抄错会牵动哪些配置，以及 template 之外那组多模态输入参数的源码默认值。
8 × 6 全打勾的训练方法矩阵：这张满表能读出什么、不能读出什么
LlamaFactory 的 README 里有一张 8 行训练阶段乘 6 列微调方式的矩阵，48 格全是对勾。这篇不复述那张表，而是讲清楚「全勾」这个声明的准确边界：它说的是可组合，不是同样成熟；并用 train/ 的目录结构、examples/ 的配方章节分布、显存表和 template 规则这三处可核实的旁证，说明这张表读不出来的东西该去哪里找。
`train/` 下没有 orpo 和 simpo 目录：它们是怎么被表达的
LlamaFactory 的训练方法矩阵列了 ORPO Training 和 SimPO Training 两行，但 src/llamafactory/train/ 下只有六个阶段目录，没有 orpo 和 simpo。本文按目录结构与 finetuning_args.py 的字段默认值，说清这两个名字落在哪一层、该去哪儿找代码。
喂对数据：格式、字段与那些暗坑
dataset_info.json 全字段与四个数据来源字段的覆盖链、Alpaca 的 history 里历史回复也会被学习、enable_thinking 的三态行为、ShareGPT 里 human 必须在奇数位、OpenAI 格式其实只是 sharegpt 加一组 tags。
`dataset_info.json` 全字段：十一个顶层键与两组子字典
想在 LlamaFactory 里挂上自己的数据集，绕不开 dataset_info.json 这份描述文件。顶层键、columns 子字典、tags 子字典分属三层语义，填错一层就是白改。本文按官方 data/README.md 原文，把十一个顶层标量键和两组嵌套字典逐个对上默认值，说清哪些字段不写就不生效。
四个数据来源字段的覆盖链：谁指定了就忽略谁
LlamaFactory 的 dataset_info.json 里有五个字段都能指定数据从哪来，它们不是并列关系，而是官方字段说明里写死的四档覆盖链：上游一旦填了，下游几个字段按原文直接被忽略。本文按 data/README.md 原文逐档拆开这条链，讲清 file_name 什么时候才是必填、数据改了没生效该先看哪一行、验证时看什么，以及哪些问题根本不属于这条链。
Alpaca 格式：`instruction\ninput` 是怎么拼出用户提示词的
照着 alpaca 样例填了 instruction 和 input，却说不清它们最后变成了什么？本文按 LlamaFactory 的 data/README.md 原文，讲清监督微调数据各列角色、两列怎么拼成用户提示词、列名与 dataset_info.json 里 columns 映射的关系，以及它何时不够用。
`history` 里的历史回复也会被模型学习
很多人把 Alpaca 格式的 history 列当成"给模型看的上下文"，但 LlamaFactory 的 data/README.md 原文写得很清楚：监督微调时历史里的 response 也会被模型学习。本文按仓库当前文档与源码默认值，讲清这句话的准确范围、ShareGPT 侧对应的学习口径、同一条轴上的几个损失开关，以及一套可执行的自查动作。
★★ `enable_thinking` 的三态：True、False 与那个「须谨慎」的 None
LlamaFactory 的 enable_thinking 不是一个开关而是三态字段，True、False 决定自动补出来的空 CoT 落在模型响应还是用户提示词、算不算损失，None 则让含 CoT 与不含 CoT 的数据走不同路径且官方明写「须谨慎」。本文按 data/README.md 与 data_args.py 的原文讲清三态各自的语义、那条训练推理必须一致的硬约束，以及怎么先确认自己的数据到底含不含 CoT。
LlamaFactory 预训练数据：只用 `text` 列，以及 sharegpt 为什么不支持预训练
LlamaFactory 的预训练数据格式是 data/README.md 里最短的一节，一个 text 列就是全部；而 sharegpt 那侧的同名小节只有一句「尚不支持，请用 alpaca 格式」。本文按仓库当前文档讲清预训练数据长什么样、dataset description 怎么写、这条能力边界意味着什么。
偏好数据集：`chosen` / `rejected` 与那个必须显式打开的 `ranking`
偏好数据集和监督微调数据集在 LlamaFactory 里的差别不只是多两列，还有一个默认关闭、必须手写打开的顶层开关 ranking。本文按 data/README.md 原文讲清 chosen 与 rejected 两列的默认值状态、ranking 字段所在的层级、alpaca 与 sharegpt 两种写法的对应关系，以及配置写漏时可以怎样逐项比对着查。
★ human 在奇数位、gpt 在偶数位：ShareGPT 的位置约束
LlamaFactory 的 ShareGPT 格式在 data/README.md 正文里夹着一条位置约束：human 与 observation 在奇数位、gpt 与 function 在偶数位，且 gpt 与 function 会被模型学习。本文讲清这条规则的文档口径、怎么按下标自查、它与 tags 的关系。
OpenAI 格式只是 sharegpt 的特例：`tags` 机制怎么做到的
手上一堆 OpenAI 风格的 messages/role/content 对话数据想喂给 LlamaFactory，第一反应往往是写转换脚本或把 formatting 填成 openai，两条都不对。本文按官方 data/README.md 原文拆开 tags 七个字段的两层结构，讲清 openai 为什么只是 sharegpt 的特例、改哪几个键能接上任意命名的对话数据。
`cutoff_len` 2048、`val_size` 0.0：数据侧 28 个参数的默认值
LlamaFactory 的数据侧参数定义在 hparams/data_args.py，一共 28 个，大多数人只显式写了其中三四个，剩下的都在按默认值跑。本文按仓库当前源码把这 28 个默认值列全，按「数据从哪来、截多长、哪部分算损失、切不切验证集、怎么打包」分组解释怎么读这张表，并指出 dataset_dir 在两处文档里写法不同这一处差异。
调对参数：默认值与它们的层级
LoRA 与它的四个变体开关、OFT 与 QOFT、GaLore 与 APOLLO 的参数表对照、BAdam 的八个参数、偏好对齐与 PPO 那两组、多模态三个冻结默认值，以及 trust_remote_code 在源码与示例 YAML 里的两处不同口径。注意：这一组只讲参数名与默认值，不给调参建议——官方没有给通用值。
`pref_beta` 0.1、`pref_loss` sigmoid：偏好对齐那一组参数
偏好对齐这一组参数很少出现在示例 YAML 里，但它们在源码里都有确切的默认值。本文按 LlamaFactory 仓库当前源码，逐个列出 pref_beta、pref_loss、simpo_gamma 等九个字段的名字与默认值，说清它们住在超参目录的哪一层、命名前缀能读出什么、默认 None 与默认 0.0 的区别，以及为什么这篇不给任何调参建议。
量化五个参数，以及 NPU 场景为什么要关掉 `double_quantization`
LlamaFactory 的量化参数在 model_args 这一层只有五个，却常和导出侧那几个同前缀字段混为一谈。本文逐个照抄这五个字段的源码默认值，讲清它们坐在哪一层、和 export 前缀字段怎么分界，以及 README 在 Ascend NPU 那节让你写的 double_quantization false 与源码默认 True 的关系。
视觉塔冻结、投影层冻结、语言模型不冻结：LlamaFactory 多模态的三个默认值
LlamaFactory 里有三个名字很像的多模态冻结开关，默认值却不是一边倒。本文按源码实读，钉住这三个字段的确切写法与默认值，说清它们坐在哪个参数文件里、和另一组同样以 freeze_ 开头但完全不是一回事的字段怎么区分、为什么要连着输入侧那几行一起看，以及为什么这篇不给你任何"该设成多少"的建议。
BAdam 的八个参数：mode、switch_mode、update_ratio 与 mask_mode
LlamaFactory 里的 BAdam 不是一个独立训练阶段，而是 finetuning_args.py 中八个带 badam_ 前缀的字段。本文逐个交代它们的确切名字与源码默认值、所在的参数层、与 GaLore/APOLLO 在参数形状上的差别，以及为什么默认值不等于推荐值、该设成多少官方并没有给通用答案。
GaLore 与 APOLLO 的参数表对照：同 rank 同间隔，scale 差 16 倍
LlamaFactory 把 GaLore 和 APOLLO 两组字段放在同一个参数文件里，默认值长得高度相似又有一处显眼差异。本文只做一件窄事：把两组字段的确切名字与源码默认值并排摆出来，指出哪几项完全对得上、哪一项相差 16 倍、APOLLO 多出的三个旋钮是什么，以及这张对照表能支撑到什么结论、到哪里就必须停。
LlamaFactory 的 `trust_remote_code`：源码默认 `False`，示例 YAML 全写 `true`
同一个开关，在 LlamaFactory 的源码默认值和官方示例配置里给出的是两个不同的取值。本文按仓库当前内容把这处差异摆清楚：它写在哪个文件、和哪些参数同住一层、为什么在训练推理合并三份配置里各出现一次、你怎么用一条命令确认自己当前跑的是哪一种取值，以及为什么这篇不给你「该不该开」的结论。
LlamaFactory 的 LoRA 参数：`lora_rank` 8、`lora_target` all，以及默认是 `None` 的 `lora_alpha`
很多人照着示例 YAML 跑 LoRA，却说不清那几行值是自己写的还是本来就有的。本文按 LlamaFactory 仓库当前源码，把 LoRA 这一圈参数的确切名字、确切默认值、它们各自住在哪个 hparams 文件里讲清楚，重点说明 `lora_alpha` 默认为 `None` 意味着什么、示例配置与源码默认值在哪几处不一致，以及为什么这篇不给你任何推荐值。
LlamaFactory：PPO 的六个参数与四个参考/奖励模型字段
想在 LlamaFactory 里跑 PPO，先要搞清的不是算法，而是配置里有哪些字段、源码默认值是多少、分别住在哪一层。本文按 src/llamafactory/hparams/ 的实读结果，列出五个 ppo_ 前缀参数、stage 字段，以及参考模型与奖励模型那七个字段，并说清量化字段为什么在两个文件里各有一套。不给调参建议。
OFT 与 QOFT：三个参数与它们在训练矩阵里的位置
LlamaFactory 的训练方法矩阵里，OFT、QOFT 与 LoRA、QLoRA 并列成独立列头，但源码参数里 OFT 只有三个字段，且 oft_rank 默认值是 0 而不是 lora_rank 那样的 8。本文按仓库当前的参数定义，讲清这三个字段的名字、默认值、所在配置层，以及 QOFT 在参数表里对应到哪。
rsLoRA、DoRA、PiSSA、LoRA+：四个开关分别控制什么
LlamaFactory 把 rsLoRA、DoRA、PiSSA、LoRA+ 做成了同一个文件里的四组独立参数，默认全部关闭，且开关形态各不相同——有的是纯布尔，有的带配套数值，有的干脆没有 use_ 前缀的开关。本文按源码实读的默认值讲清这四组参数的确切名字、所在层次、彼此关系，以及为什么这篇不给你「该开哪个」的答案。
推出去：后端、生成参数与导出
四个推理后端、vLLM 与 SGLang 对称设计的参数、temperature 默认 0.95 而不是大家以为的那组、评测默认 5-shot、导出九个参数，以及合并 LoRA 时那句全大写的 DO NOT 到底在禁什么。
四个推理后端：huggingface、vllm、sglang、ktransformers
LlamaFactory 的 infer_backend 只有四个合法取值，它们散落在示例 YAML 的注释、model_args.py 的默认值和 README 的命令行示例里。本文把出处逐一钉死，讲清这个字段坐在哪一层、怎么在命令行覆盖它、四个后端各占几个专属参数，以及官方没给数据的维度我们为什么不比。
vLLM 与 SGLang 的参数是对称设计的，差异只有四个字段
LlamaFactory 的 vLLM 与 SGLang 后端参数在 model_args.py 里成对出现：最大长度都默认 4096、显存占比都默认 0.7、各有一个默认 None 的配置口子，真正不成对的只有四个字段。本文核对这十个字段的名字与源码默认值，说清它们住在哪一层、哪些跨层同名词根不是一回事。
LlamaFactory 生成参数默认值：`temperature` 是 0.95、`top_p` 是 0.7，不是你以为的那组
很多人凭印象记得的生成默认值是温度 0.7、top_p 0.9，而 LlamaFactory 的 generating_args.py 里源码默认写的是 temperature 0.95、top_p 0.7。本文把这一层十个字段的默认值逐个列出来，说清它们写在 hparams 的哪个文件、和推理后端那几个同样是 0.7 的参数不是一回事，以及为什么这类数字必须回源码核而不是靠记。
评测默认 5-shot、种子 42：LlamaFactory 的七个评测参数
LlamaFactory 把评测参数单独放在 evaluation_args.py 里，一共七个字段。本文按源码里读到的默认值逐个说清：task_dir 是裸目录名、batch_size 为 4、seed 固定 42、lang 默认 en、n_shot 默认 5、save_dir 为 None，以及这组参数不管的三件事。
导出九个参数：`export_size` 5、`export_device` cpu
LlamaFactory 的导出这一步只有九个参数，全部定义在 model_args.py 里，而官方示例配置只显式写了其中四个。本文把九个参数名与源码默认值逐个对上，说清它们住在哪一层、示例 YAML 与源码默认是否一致、四个 export_quantization_ 字段和合并 LoRA 时那条全大写禁令的关系，以及哪些语义我们没有核实、只能以 -h 输出为准。
合并 LoRA 时那句全大写的 DO NOT 到底在禁什么
LlamaFactory 的 merge_lora 示例配置第一行就是一句 DO NOT 注释，禁止在合并 LoRA 适配器时使用量化模型或 quantization_bit。本文拆开这条禁令的两个对象，说清加载侧与导出侧量化是两组不同参数名，给出撞上它的判定动作、处置后的验证路径，以及什么情况说明问题不在这里。
`examples/` 的配方矩阵：18 个 extras 目录与算法开关一一对应
LlamaFactory 的 examples 目录常被当成一堆散配置来翻，实际上它是按四条互不相同的轴切开的。本文实读目录树，把 13 个一级目录归到「微调方式 / 生命周期 / 后端 / 算法」四条轴上，重点核对 extras 下 18 个子目录与 finetuning_args 里算法开关的对应关系，说清哪些能对上、哪几个在我们抽取的参数范围内找不到同名开关，以及找配置时该从哪条轴入手。
三份 YAML 逐行对照：字段是怎么串成一条闭环的
LlamaFactory 的 Quickstart 给了三条命令、三份 YAML，很多人分别照抄却串不起来。本文把 examples 下训练、推理、合并导出这三份同名配置逐行摆在一起，看清哪些字段是三份共有、哪些只属于其中一份、四个标识符是怎么把它们锁成一条链路，以及首行那句全大写的禁令为什么写在合并那份里。
想把微调这件事真正跑通，而不只是复制一份 YAML？
从 AI 编程基础到 Agent 工程落地，站内有成体系的教程与课程。