`cutoff_len` 2048、`val_size` 0.0：数据侧 28 个参数的默认值
本文所有事实以
hiyouga/LlamaFactory官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中数字均为仓库源码与文档里写着的值。
看别人的 YAML 学微调有个隐蔽的坑：那份 YAML 里通常只写了三五个数据侧参数，你照抄过来能跑，但你并不知道剩下二十多个参数此刻取的是什么值。 LlamaFactory 的数据侧参数集中定义在 src/llamafactory/hparams/data_args.py，我们实读这一份文件，一共 28 个参数。这篇不讲该调成多少——那取决于你的数据和硬件，官方也没给通用值——只把 28 个默认值摆齐，再讲清楚这张表该怎么读。
先把 28 个默认值放在一起
按功能分了组，参数名与默认值逐个照抄自 hparams/data_args.py：
| 组 | 参数 | 默认值 |
|---|---|---|
| 数据来源 | dataset | None |
| 数据来源 | eval_dataset | None |
| 数据来源 | dataset_dir | "data" |
| 数据来源 | media_dir | None |
| 模板与系统提示 | template | None |
| 模板与系统提示 | default_system | None |
| 模板与系统提示 | tool_format | None |
| 长度与采样 | cutoff_len | 2048 |
| 长度与采样 | max_samples | None |
| 损失范围 | train_on_prompt | False |
| 损失范围 | mask_history | False |
| 损失范围 | ignore_pad_token_for_loss | True |
| 思维链 | enable_thinking | True |
| 思维链 | preserve_thinking | False |
| 验证与评估 | val_size | 0.0 |
| 验证与评估 | eval_on_each_dataset | False |
| 验证与评估 | eval_num_beams | None |
| 打包 | packing | None |
| 打包 | neat_packing | False |
| 流式与混合 | streaming | False |
| 流式与混合 | buffer_size | 16384 |
| 流式与混合 | mix_strategy | "concat" |
| 流式与混合 | interleave_probs | None |
| 预处理与缓存 | overwrite_cache | False |
| 预处理与缓存 | preprocessing_batch_size | 1000 |
| 预处理与缓存 | preprocessing_num_workers | None |
| 预处理与缓存 | tokenized_path | None |
| 预处理与缓存 | data_shared_file_system | False |
分组是我们为了好读加的，源码里没有这层分类。
先看这张表的整体形状，比逐条抠更有用：28 个参数里有 12 个默认是 None，10 个是布尔量，剩下 6 个是有具体数值或字符串的（dataset_dir 的 "data"、cutoff_len 的 2048、buffer_size 的 16384、mix_strategy 的 "concat"、preprocessing_batch_size 的 1000、val_size 的 0.0）。
10 个布尔量里，默认为 True 的只有两个：ignore_pad_token_for_loss 和 enable_thinking。其余八个（train_on_prompt、mask_history、streaming、overwrite_cache、eval_on_each_dataset、neat_packing、preserve_thinking、data_shared_file_system）默认全是 False。也就是说，这一层的默认姿态是几乎所有开关都关着，你不主动打开就不会生效。这个观察是我们照着上表数出来的，不是文档里的现成结论。
这些参数在哪一层，跨层口径对得上吗
data_args.py 是参数定义的其中一份，与模型侧、微调方法侧的参数文件并列。本文只核了数据这一份，别的层里相关的参数我们在这篇不下结论。
跨层对照有两处值得说：
一处对得上。 data/README.md 的 TIP 里写 enable_thinking 为 True 是「慢思考」且是默认值，data_args.py 里 enable_thinking 的默认值也确实是 True。文档口径和源码口径一致，这在参数文档里不算理所当然，能对上就记一笔。
一处写法不同。 data/README.md 说 dataset_info.json 必须放在 dataset_dir 目录下，可以改 dataset_dir 用别的目录，默认值是 ./data；而 data_args.py 里 dataset_dir 的默认值是字符串 "data"。两处指的是同一个相对目录，但字面写法一处带 ./ 一处不带。这是仓库里能核实到的差异，如实说到这儿就够了，哪一处「更对」、为什么不一致，我们不推断。
顺带一提，data/README.md 那条 TIP 的原文用的还是带连字符的旧名 LLaMA-Factory，而仓库当前路径是 hiyouga/LlamaFactory。新旧写法在仓库里并存，搜资料时两种拼法都试一遍即可。
数据来源那四个：默认全是「你不说我就不动」
dataset 默认 None，这和 data/README.md 开头的要求是同一件事的两面——使用自定义数据集时，必须在 dataset_info.json 里加一段 dataset description，并在训练前指定 dataset: dataset_name。默认值是 None 意味着这一项没有兜底，不写就是没有。
dataset_dir 的默认值是一个相对路径（源码里写作 "data"，data/README.md 里写作 ./data）。相对路径要落到哪个绝对位置，取决于运行时怎么解析它——这一层我们没有读过实现，不下结论。能说的是：默认值不是绝对路径，所以「我明明把 dataset_info.json 放对了位置却读不到」这类情况，值得先把 dataset_dir 显式写成你确定的那个目录，再看问题还在不在。
Windows 和 Linux/macOS 在写这个值时形态不同：Linux/macOS 的绝对路径是 /path/to/data 这类形式；Windows 的路径分隔符是反斜杠，写进 YAML 时容易和转义规则撞车，常见做法是改用正斜杠或给整个值加引号。这一条属于通用的 YAML 与路径书写习惯，不是 LlamaFactory 文档里的内容——官方文档没有专门讲 Windows 路径怎么写。
eval_dataset 和 media_dir 同样默认 None。
cutoff_len 2048：最常被改的那个值
data_args.py 里 cutoff_len 的默认值是 2048，也是数据侧最常被改的一个值。
到这里我必须停住，不给建议。很多文章会顺势说「显存不够就把 cutoff_len 调小」——这一步推理在本文的证据范围之外。README 里的显存表原文标了 * estimated（估算），不是实测占用；我们也没有跑过任何一次训练。既然连显存基线都是官方标注的估算值，就更不能拿它反推「你把 cutoff_len 从 2048 改到 4096，你那张卡够不够」。
能确定的只有这一句：cutoff_len 默认是 2048，你不写它就是 2048。该设多少取决于你的数据长度分布和硬件，官方没给通用值。
同组的 max_samples 默认 None，即默认不额外限制样本数。
「哪部分参与损失」是这张表里最值得先看懂的一块
这块由两处共同决定：一半在数据格式里，一半在这几个开关里。
先说格式那一半，data/README.md 有两条硬规则：
- Alpaca 格式的
history列，是历史消息里的 prompt-response 对；原文明确写着，监督微调时历史里的 response 也会被模型学习。 - ShareGPT 格式里，
gpt和function会被模型学习。
也就是说，你往 history 里塞的多轮上下文不是白送的上下文，它是训练目标的一部分。这一点不看 data/README.md 很难猜到。
再看开关这一半：train_on_prompt 默认 False、mask_history 默认 False，两个都是与「哪部分参与损失」相关的开关，默认都关着。ignore_pad_token_for_loss 默认 True，是这张表里默认为真的两个之一。这三个具体如何作用于损失计算的实现细节，我们没有逐行读过，不展开。
enable_thinking 的三态，以及那句「必须一致」
enable_thinking 默认 True，preserve_thinking 默认 False。前者的行为在 data/README.md 的 TIP 里写得很完整，照原文转述：
若模型有推理能力（例如 Qwen3）但数据集不含 CoT，会自动补一个空 CoT。enable_thinking 为 True（慢思考，默认值）时，空 CoT 会被加到模型响应里，并计入损失计算；否则（快思考）空 CoT 会被加到用户提示词里，损失计算会忽略它。
第三态是 None：想让含 CoT 的数据走慢思考、不含 CoT 的数据走快思考，可以把 enable_thinking 设为 None；但原文同时提醒，这个特性相对复杂，使用需谨慎（should be used with caution）。
最后一句是整张表里少见的、官方给了明确约束的地方：训练与推理时 enable_thinking 必须保持一致。 这也是这个参数与别的参数最不一样的地方——大多数数据侧参数只影响训练侧，它却牵着推理侧。你在训练 YAML 里改了它，推理那边就得跟着改。
val_size 0.0：默认压根不切验证集
val_size 默认 0.0，含义是默认不切验证集。同组的 eval_dataset 默认 None、eval_on_each_dataset 默认 False、eval_num_beams 默认 None。
这四个默认值合在一起是一个挺重要的事实：照抄一份没写这几项的 YAML，你这次训练就是没有验证集的。如果你打算靠某条曲线判断有没有过拟合，得先确认自己显式设过其中之一。至于 val_size 该切多少，同样取决于你的数据规模，官方没给通用值，本文不编一个。
打包、流式、缓存：剩下九个的默认姿态
packing 默认 None、neat_packing 默认 False，是两个与序列打包相关的开关。
streaming 默认 False，配套的 buffer_size 默认 16384；多数据集混合由 mix_strategy（默认 "concat"）与 interleave_probs（默认 None）控制。默认是不流式、按 concat 混合。
预处理与缓存这一组：overwrite_cache 默认 False、preprocessing_batch_size 默认 1000、preprocessing_num_workers 默认 None、data_shared_file_system 默认 False。tokenized_path 默认 None，用于预处理产物，仓库里对应的示例是 examples/train_lora/qwen3_preprocess.yaml。
读这张表的三条纪律
第一，默认值不是推荐值。 这张表回答的是「我没写它的时候它是多少」，不是「我该写多少」。这两个问题的答案在这个仓库里没有被绑定过。
第二，先确认默认姿态，再决定改哪一个。 默认姿态可以概括成一句：数据来源全空、模板全空、开关几乎全关、不切验证集、截断 2048。你的多数「怎么和预期不一样」，第一步应该回来对一遍这张表，而不是先怀疑算法。
第三，参数会随版本变。 这 28 个是我们在 2026-08-09 这天读到的 data_args.py 的内容。真要落到你的环境上，以 llamafactory-cli train -h 的实际输出为准。
template 默认 None 这一条，本文只交代到「默认是空的、必须自己指定」这一层；每个模型该填哪个 template 名、为什么训练和推理两侧要对齐，我们另有一篇专门讲。dataset_info.json 的完整字段规格、两种数据格式各自的写法，也各有专篇，这篇不重复搬。
本文依据 LlamaFactory 官方仓库（github.com/hiyouga/LlamaFactory）的 README、data/README.md、examples/ 下的配置与 src/llamafactory/hparams/ 的参数定义整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装、训练或部署过任何模型，文中显存数字均为官方标注的估算值（README 原文标 * estimated）而非实测占用。参数与默认值随版本变动，请以 llamafactory-cli train -h 的实际输出为准。