LlamaFactory 的 `trust_remote_code`：源码默认 `False`，示例 YAML 全写 `true`

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

在 LlamaFactory 里，trust_remote_code 属于「你不写它也有值、你照着 Quickstart 那三份示例抄就一定会带上它」的参数。而这两条路径给出的取值不一样：源码里的默认值是 False，那三份官方示例 YAML 里显式写的是 true。

这不是什么隐藏彩蛋，两处都是公开可读的。但它容易被漏掉，因为大多数人从来不会主动去看某个参数的默认值——照着 examples/ 复制一份 YAML，改改路径就跑起来了。于是”我的配置里为什么有这一行”这个问题，往往到出问题那天才第一次被问出来。

这篇只做一件事：把这处差异钉死，并给出你自己确认现状的动作。至于该取哪个值，后面会专门说明为什么我们不回答。

先把两处口径原样摆出来

第一处，源码默认值。 它定义在 src/llamafactory/hparams/model_args.py 里，field(default=...) 读出来是：

参数	源码默认值
trust_remote_code	False

第二处，官方示例配置。 README 的 Quickstart 抬出来的那条完整闭环，一共三份 YAML，每一份里都显式写着这一行：

• examples/train_lora/qwen3_lora_sft.yaml（训练）
• examples/inference/qwen3_lora_sft.yaml（推理）
• examples/merge_lora/qwen3_lora_sft.yaml（合并导出）

以推理那份为例，它总共只有 5 行，逐行照抄是这样：

model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft
template: qwen3_nothink
infer_backend: huggingface  # choices: [huggingface, vllm, sglang, ktransformers]
trust_remote_code: true

五行里就有一行是它。训练那份和合并那份同样带着 trust_remote_code: true。

所以准确的说法是：代码默认保守，示例配置显式打开，两处口径不一致。 到这儿就停——为什么会这样、哪一处”才是对的”、有没有人忘了同步，我们一概不推断，也不拿这个差异去评价这个项目。仓库当前状态就是这样，以你实际使用的那份配置为准。

它住在哪一层，同层还有谁

LlamaFactory 把超参按用途拆进了 src/llamafactory/hparams/ 下的 8 个文件：data_args.py、model_args.py、finetuning_args.py、generating_args.py、evaluation_args.py、training_args.py、megatron_bridge_args.py，外加一个 parser.py。

trust_remote_code 属于 model_args.py，也就是模型加载这一层，而不是微调方法层。跟它同住在”基础加载”这一组的还有这些（都是源码实读的默认值）：

参数	默认值
model_name_or_path	None
adapter_name_or_path	None
model_revision	"main"
cache_dir	None
low_cpu_mem_usage	True
use_fast_tokenizer	True
trust_remote_code	False

知道它在哪一层，有一个很实际的好处：**它跟 finetuning_type、stage 这些字段根本不在同一组里。**后两个的默认值（"lora" 与 "sft"）写在 finetuning_args.py，而 trust_remote_code 写在 model_args.py，是”模型加载”这一组的邻居。这是文件归属层面的客观事实；至于运行时各层参数如何被解析和覆盖，写在 parser.py 里，那个文件我们没有读过，不做任何断言。

至于这个字段的字面含义，名字本身已经说明它关乎是否信任模型仓库自带的代码。我们没有读过 LlamaFactory 里对这个字段的处理逻辑，也没有跑过任何一次加载，所以它在执行层面具体做了什么，请以 Transformers 官方文档和该字段在上游的定义为准，这篇不代为解释。

一个容易被忽略的细节：它在链路上出现了三次

Quickstart 那条闭环对应的三条命令是：

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

三份 YAML 的字段是严格对齐的：同一个基座 Qwen/Qwen3-4B-Instruct-2507、同一个 template qwen3_nothink、训练的 output_dir: saves/qwen3-4b/lora/sft 正好是后两份的 adapter_name_or_path。而 trust_remote_code 也在这三份里各写了一次。

这意味着什么？**这个开关不是”训练时设一次就一路生效”的东西，它是每份配置各自声明的。**你完全可能训练那份改过了、推理那份还留着示例里的原值，反过来也一样。链路上有三个独立的落点，改一处不会自动传导到另外两处。

顺带把合并那份 YAML 的另一条硬约束摘出来，免得混在一起排查。它的首行是一句全大写的原文注释：

### Note: DO NOT use quantized model or quantization_bit when merging lora adapters

即：合并 LoRA 适配器时不要使用量化模型或 quantization_bit。这是一条明确的操作禁令，跟 trust_remote_code 是两回事，只是恰好写在同一个文件里。

怎么确认你现在跑的是哪一种

判定动作很简单，只有两步。

**第一步，看你自己的配置。**在你的配置目录下把这个字段找出来：

grep -rn "trust_remote_code" <你的项目目录>

Windows 下如果没装 git-bash，用 CMD 自带的：

findstr /s /n "trust_remote_code" <你的项目目录>\*.yaml

搜得到，说明这份配置把它写死了；一行都搜不到，说明你没有在 YAML 这一层动过它，源码里给它准备的值是 False。这也正是这处差异值得知道的原因：“没写”不等于”没有值”。（命令行还能不能再覆盖一次、覆盖的优先级怎么排，写在 parser.py 里，我们没读过，所以第二步比第一步更权威。）

**第二步，以命令行的实际输出为准。**参数与默认值会随版本变动，仓库里读到的值和你装的那个版本未必一致，最终以 llamafactory-cli train -h 打印出来的为准。

这两步之外，还有一件事值得顺手做：如果你的 YAML 是从 examples/ 复制来的，把整份文件从头到尾读一遍，而不是只改你关心的那几行。示例配置是演示用的——同一份训练 YAML 里还写着 max_samples: 1000，只取 1000 条样本，### eval 那一整块也是被注释掉的。这些都是随手复制会一起带走的东西。

一处长得像、但性质不同的差异

仓库里还有一个经常和它被放在一起说的参数：double_quantization。它的源码默认值是 True，而 README 在 Ascend NPU 那一节让用户在配置里设 double_quantization: false。

看起来也是”两处不一样”，但性质不同：那是默认开着，所以特定场景需要一条提示让你显式关掉——文档和默认值在这里是配合关系，不是口径冲突。而 trust_remote_code 是同一件事在源码默认与官方示例两层给出了不同取值。

区分这两类，比记住任何一个具体的值都有用。读一个陌生参数时，值得问的是两个问题：**源码默认是什么？我手上这份配置有没有把它写死？**两个答案对上了，才算真的知道自己在跑什么。

为什么这篇不告诉你该设成什么

因为我们没有依据。

我们没有安装过 LlamaFactory，没有加载过任何一个模型，也没有读过它对这个字段的处理逻辑。更重要的是，这个取值取决于你打算加载谁的模型、模型来自哪个来源、你所在环境有什么合规要求——这些我们一概不知道，官方也没有给出一条通用规则。

所以这篇只交付两件事：一是这两处口径确实不同，二是你可以用上面那两步确认自己当前是哪一种。至于”这样配就安全了”这类结论，本文不提供，也请你警惕任何提供这类结论的文章。

什么情况说明你遇到的不是这个问题

最后补一条反向判定，免得把它当成万能嫌疑人。

如果你的配置里根本没有出现过这个字段，而你也从未从 examples/ 复制过任何一份 YAML，那这处差异对你的运行结果就没有影响——你一直跑在源码默认值上，问题多半在别处。同样地，如果你换过模型下载源、动过 template、或者在合并阶段带上了量化设置，那各自有各自的排查路径，跟这个开关不是一条线。关于换源那几个环境变量、template 为什么必须训练推理两侧对齐，我们另有专门篇目讲。

---

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