四个数据来源字段的覆盖链：谁指定了就忽略谁

2026-08-09

本文所有事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准，主要出处是 data/README.md（共 475 行）与 data/dataset_info.json。我们没有安装、训练或部署过任何模型，文中所有值都是仓库文档与源码里写着的。

有一类配置问题的答案，就写在官方字段说明的括号里：数据集明明换了、file_name 也改成了新文件，读到的却还是原来那份。按 data/README.md 的原文，同一段 dataset description 里只要还留着一个档位更高的来源字段，你改的 file_name 就是被声明忽略的——原文用的词就是 “ignore”。

这条覆盖链本身不长：五个字段、四个档位，全藏在 dataset_info.json 那一大段字段规格的最前面五行里，很容易被当成”五个可选的数据来源，填哪个都行”扫过去。这篇只讲这五行，别的字段（列名映射 columns、sharegpt 的 tags、formatting 的两种取值细则）我们另有专门篇目讲，这里不重复搬那张全字段表。

先把这五行原文摆出来

data/README.md 开头那段 JSON 规格里，与”数据从哪来”直接相关的就是这五行，逐字照抄：

"dataset_name": {
  "hf_hub_url": "the name of the dataset repository on the Hugging Face hub. (if specified, ignore script_url, file_name and cloud_file_name)",
  "ms_hub_url": "the name of the dataset repository on the Model Scope hub. (if specified, ignore script_url, file_name and cloud_file_name)",
  "script_url": "the name of the directory containing a dataset loading script. (if specified, ignore file_name and cloud_file_name)",
  "cloud_file_name": "the name of the dataset file in s3/gcs cloud storage. (if specified, ignore file_name)",
  "file_name": "the name of the dataset folder or dataset file in this directory. (required if above are not specified)"
}

之所以要把这五行单独拎出来，是因为它们的括号说明结构完全一致：每一行都在声明”我出现了，谁就作废”。把括号里的内容排成阶梯，链条就清楚了。

档位	字段	原文声明的被忽略者
第一档	`hf_hub_url` / `ms_hub_url`	`script_url`、`file_name`、`cloud_file_name`
第二档	`script_url`	`file_name`、`cloud_file_name`
第三档	`cloud_file_name`	`file_name`
第四档	`file_name`	前面都没指定时，它是 required

读这张表要注意两点。第一，hf_hub_url 和 ms_hub_url 在原文里的括号说明一字不差，都是”ignore script_url, file_name and cloud_file_name”——也就是说这两个字段处在同一档，谁都没被声明为压过对方。那么两个 hub 字段同时写上会怎样？原文没写。我们没有跑过任何一次训练，也不据此推断实现里谁赢，只能说这一档的仲裁规则不在这段文档里——同一段 description 里同时填这两个字段，行为在文档层面是没有定义的，这一点你自己权衡。

第二，file_name 的”必填”是有前提的：原文是 required if above are not specified。它不是无条件必填字段，而是这条链的兜底档。它容易被记成”数据集必须有 file_name”，于是在已经写了 hf_hub_url 的条目里又补一个 file_name——按原文，那个 file_name 是被忽略的，本地文件改了也不会有反应。

`file_name` 里还有一个被忽略的细节

原文写的是 “the name of the dataset folder or dataset file in this directory”。也就是说它接受的不只是一个文件名，也可以是一个数据集文件夹。这一点在文档里只是一个词的差别，但它决定了你把数据切成多个分片时该怎么填。

“in this directory” 里的 this directory，指的是 dataset_dir。这里有一处仓库内部的口径差异，如实说清楚：data/README.md 的正文写的是 dataset_dir 的默认值是 ./data，而 src/llamafactory/hparams/data_args.py 里这个参数的默认值实读是字符串 "data"。两处写法不同，以仓库当前状态为准；我们不推断原因，也不据此评价什么。实际使用时记住一条就够：dataset_info.json 必须放在 dataset_dir 这个目录下，你可以改 dataset_dir 指向别的目录，但那份索引文件要跟着走。

顺带把文件类型这条边界也放这儿：README 原文允许的文件类型是 json、jsonl、csv、parquet、arrow 五种。不在这个列表里的格式，先转换再谈别的。

覆盖链的邻居：三个只在特定档位才有意义的字段

同一段规格里还有几个字段经常和这条链一起被填错，值得连着看：

subset：the name of the subset，可选，默认 None
split：the name of dataset split to be used，可选，默认 train
folder：原文写死了 the name of the folder of the dataset repository on the Hugging Face hub，可选，默认 None
num_samples：the number of samples in the dataset to be used，可选，默认 None

folder 这一条的限定语是原文自带的——它描述的对象是 Hugging Face hub 上的仓库目录。换句话说，它属于第一档那一侧的配套字段，你在一个纯本地 file_name 的条目里填它，逻辑上就对不上。split 默认 train 这一条也常被忽略：如果你的数据集有多个 split，不显式写就是走 train。

改了没生效时，按这个顺序查

这是本篇最实用的部分，按”现象 → 判定 → 处置 → 验证 → 排除”走一遍。

现象：改了数据文件或换了数据路径，训练读到的数据看起来没变，或者报的是”找不到某个 hub 仓库”这类与本地文件无关的错。

怎么确认是这条链的问题：打开 dataset_dir 下的 dataset_info.json，找到你在训练配置里 dataset: 指定的那个键名，只看这一段，然后按上面那张表从第一档往下扫：这段里有没有 hf_hub_url 或 ms_hub_url？有没有 script_url？有没有 cloud_file_name？只要更高档位的字段存在，你改的 file_name 按原文就是被忽略的。这一步是纯文本比对，不需要跑任何命令。

处置：让这段 description 里只保留你真正想用的那一档。想读本地数据，就把上面三档的字段从这段里删掉，留 file_name；想读 hub，就别在同一段里留本地字段给自己制造歧义。

怎么验证：验证动作还是回到这份 JSON——确认这段里只剩一个数据来源字段，且 dataset: 里写的键名与这段的键名完全一致。这份索引文件是唯一的入口，data/dataset_info.json 里实读共有 104 个数据集条目，键名重复或写错一个字符，命中的就是另一段配置。

什么情况说明不是这个原因：如果这段 description 里本来就只有一个来源字段，那问题多半在别处——比如你压根没在 dataset_info.json 里加这段 description（原文对自定义数据集的要求是 make sure 要加，并在训练前指定 dataset: dataset_name），比如 formatting 填的档跟你的数据结构对不上（默认是 alpaca，可选值只有 {alpaca, sharegpt}），比如偏好数据集忘了显式写 "ranking": true（默认是 False），又或者是列名映射没配对。这几类都不属于覆盖链，按各自的规则去查，别在这条链上继续绕。

ModelScope 那两处，别混成一件事

这里有两处名字相近、层面完全不同的东西，值得分清：ms_hub_url 是 dataset_info.json 里的字段，按原文指的是 Model Scope hub 上的数据集仓库名；而 README 的下载来源切换一节另外给了环境变量，用于 Hugging Face 下载有问题时切换下载源。一个写在 JSON 里、一个写在 shell 环境里，改错地方自然不起作用。

环境变量的写法两边不一样，Windows 侧尤其别照抄 Linux 的命令：

# Linux / macOS
export USE_MODELSCOPE_HUB=1

:: Windows
set USE_MODELSCOPE_HUB=1

以上两行按官方 README 的写法照抄，我们没有实际执行过，以官方文档的实际说明为准。至于该走本地文件还是走某个 hub，取决于你的网络环境和数据存放方式，官方没给通用建议，我们也不替你定。

最后一句提醒

这条覆盖链的价值不在于记住四个档位的顺序，而在于建立一个习惯：排查数据问题时，先把 dataset_info.json 里对应的那一段完整看一遍，再去看训练配置。这段 JSON 是所有数据行为的唯一声明处，字段之间存在明确的互相作废关系，不是”填得越全越保险”。

另外补一句边界：data/dataset_info.json 里那 104 个条目的具体内容、条数、语言分布和各自的许可，我们一条都没有核实过，本文不描述任何一个数据集的内容。至于 alpaca 与 sharegpt 两种格式各自的字段细则、enable_thinking 的三态行为、tags 如何把 sharegpt 适配成 OpenAI 格式，我们另有专门篇目讲。

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