`dataset_info.json` 全字段：十一个顶层键与两组子字典

2026-08-09

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

在 LlamaFactory 里加一个自己的数据集，第一件事不是写训练配置，而是往 dataset_info.json 里加一段描述。data/README.md 开头把这条写成硬要求：使用自定义数据集时，必须在 dataset_info.json 里加一段 dataset description，并在训练前指定 dataset: dataset_name。

这份描述的字段规格就摆在 data/README.md 最开头，连标题都没有，翻页时很容易滑过去。它一共约定了十三个顶层键，其中十一个是标量键，另外两个——columns 和 tags——是嵌套字典。这篇就把这三层拆开对一遍。

先把这份文件的四条总规则钉住

data/README.md 开头给的规则只有四条，但每一条都能省掉一次返工：

dataset_info.json 包含所有可用数据集；用自定义数据集时必须在里面加一段描述，训练前用 dataset: dataset_name 指定。
dataset_info.json 必须放在 dataset_dir 目录下。dataset_dir 可以改成别的目录，默认值是 ./data。
目前支持 alpaca 和 sharegpt 两种格式。
允许的文件类型是 json、jsonl、csv、parquet、arrow 这五种。

第 2 条读起来像废话，实际信息量最大：dataset_info.json 和数据文件本身是绑在同一个目录语义上的，不是”配置文件放哪儿都行、数据文件写绝对路径”那种关系。我们实读 data/dataset_info.json，里面共有 104 个数据集条目，前几个键名依次是 identity、alpaca_en_demo、alpaca_zh_demo、glaive_toolcall_en_demo、glaive_toolcall_zh_demo、mllm_demo 这些。你自己加的那一段，就是并列插在这 104 个条目旁边的第 105 个键。

十一个顶层标量键

按”它们各自在回答什么问题”分组，比按文件里的顺序背要好记得多：

键名	官方说明要点	默认值
`hf_hub_url`	Hugging Face hub 上的数据集仓库名	无
`ms_hub_url`	Model Scope hub 上的数据集仓库名	无
`script_url`	含数据集加载脚本的目录名	无
`cloud_file_name`	s3/gcs 云存储里的数据集文件名	无
`file_name`	本目录下的数据集文件夹名或文件名	无（上面几个都没指定时必填）
`formatting`	数据集格式	`alpaca`，可选 `{alpaca, sharegpt}`
`ranking`	是否是偏好数据集	`False`
`subset`	子集名	`None`
`split`	使用哪个 split	`train`
`folder`	Hugging Face hub 上仓库里的文件夹名	`None`
`num_samples`	使用的样本数	`None`

前五个键回答的是”数据从哪儿来”。 它们之间不是并列关系，而是有一条明确的覆盖链：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 是必填的。这条链单独就够写一篇，我们另有一篇专门讲，这里只需要记住一个后果：你以为改了 file_name 却没生效，八成是上游还留着一个 hub 字段没删掉。

formatting 和 ranking 回答的是”这份数据是干什么用的”。 这两个键的默认值方向是相反的：formatting 默认 alpaca，也就是不写就当 alpaca 处理；ranking 默认 False，偏好数据集必须显式写 "ranking": true。官方在偏好数据集那一节给的示例 description 里，"ranking": true 是和 file_name、columns 并列写在顶层的一行。做 DPO、ORPO、SimPO 或者奖励建模时漏掉这一行，这段描述在 JSON 语法上依然是合法的，ranking 只会按文档写的默认值 False 处理——至于框架此时具体会怎么走，官方这份文档没写，我们也没跑过，不猜。

subset、split、folder、num_samples 回答的是”取其中哪一部分”。 四个里只有 split 有非空默认值 train，另外三个默认都是 None。

`columns`：把你的列名翻译成框架的语义

columns 是第一组子字典，官方规格里这个键写作 "columns (optional)"，实际用的键名就是 columns——从示例 dataset description 里 "columns": { ... } 的写法可以直接看出来。它一共十三个字段：

字段	含义	默认列名
`prompt`	提示词所在列	`instruction`
`query`	查询所在列	`input`
`response`	响应所在列	`output`
`messages`	消息所在列	`conversations`
`history`	历史消息所在列	`None`
`system`	system prompt 所在列	`None`
`tools`	工具描述所在列	`None`
`images`	图像输入所在列	`None`
`videos`	视频输入所在列	`None`
`audios`	音频输入所在列	`None`
`chosen`	更优答案所在列	`None`
`rejected`	更差答案所在列	`None`
`kto_tag`	KTO 标签所在列	`None`

这张表要横着读：左边是框架内部的语义槽位，右边是它默认去哪个列名里找。 十三个字段里只有四个有非 None 默认值——prompt → instruction、query → input、response → output、messages → conversations，其余九个不写就是没有。

这个设计有个直接推论：如果你的数据文件正好用的是默认列名，columns 整个可以不写。 官方那段 alpaca 监督微调的示例 description 里，prompt、query、response 三行填的就是 instruction、input、output，与文档给出的默认值逐个相同（这是把两段原文对着读就能看出来的，官方没解释为什么把它们写出来）：

"dataset_name": {
  "file_name": "data.json",
  "columns": {
    "prompt": "instruction",
    "query": "input",
    "response": "output",
    "system": "system",
    "history": "history"
  }
}

真正非写不可的是 system 和 history 这两行，因为它们默认是 None：不写，这两列的数据就不会被用上。同理，做偏好数据集时 chosen / rejected 必须写，做多模态时 images / videos / audios 必须写。

`tags`：只在 sharegpt 格式下生效的第二组子字典

tags 是第二组子字典，规格里写作 "tags (optional, used for the sharegpt format)"——限定语就在键名的括号里，它只服务于 sharegpt 格式。 七个字段的默认值如下：

字段	含义	默认值
`role_tag`	消息里表示身份的 key	`from`
`content_tag`	消息里表示内容的 key	`value`
`user_tag`	`role_tag` 取什么值代表用户	`human`
`assistant_tag`	`role_tag` 取什么值代表助手	`gpt`
`observation_tag`	`role_tag` 取什么值代表工具结果	`observation`
`function_tag`	`role_tag` 取什么值代表函数调用	`function_call`
`system_tag`	`role_tag` 取什么值代表 system prompt	`system`

注意这七个字段分成两类：role_tag 和 content_tag 说的是消息对象里的 key 名，另外五个说的是**role_tag 那个 key 的取值**。层级不同，别混着改。

还有一处细节值得单独标出来：system_tag 的官方说明里多了一句 can override system column。也就是说 system prompt 在 sharegpt 格式下有两条可能的来路——columns.system 指的那一列，和消息列表里 role_tag 值为 system 的那条消息——而后者可以覆盖前者。两处都配了却发现结果不是你想的那样，先回来核对这一句。

至于 tags 到底能做到什么程度，官方给的最好例子是 OpenAI 格式：那种格式之所以被支持，靠的就是把 role_tag 从 from 改成 role、content_tag 从 value 改成 content。这一点我们另有一篇专门讲。

一份 sharegpt 描述长什么样

对照着看会更清楚，官方 sharegpt 监督微调那段的 description 是这样的：

"dataset_name": {
  "file_name": "data.json",
  "formatting": "sharegpt",
  "columns": {
    "messages": "conversations",
    "system": "system",
    "tools": "tools"
  }
}

和前面那段 alpaca 的对比着读，两处差别很说明问题：多了一行 "formatting": "sharegpt"（因为默认是 alpaca，不写就走错分支），columns 里换成了 messages（alpaca 那套 prompt / query / response 在这里不用）。而 tags 这一段这里压根没出现——因为这份数据用的就是默认的 from / value / human / gpt。

改这些字段会牵动什么

只说事实卡覆盖得到的关联，其余不猜：

改 formatting，tags 的生效范围跟着变。 tags 只用于 sharegpt；把 formatting 从 sharegpt 改回默认的 alpaca，那段 tags 就没有落脚点了。
改 ranking，训练方法的适配范围跟着变。 ranking: true 对应的是奖励建模、DPO、ORPO 与 SimPO 这一类用途，字段本身只是个开关。
改数据来源字段，可能什么都不会发生。 见前面那条覆盖链——被上游字段忽略掉的字段，改了也是白改。
改 columns 里的列名，只是改映射关系。 它改的是”去哪一列取数”，不改数据本身。

至于 cutoff_len、val_size 这类真正会影响训练行为的数据侧参数，它们不在 dataset_info.json 这一层，而在 hparams/data_args.py 定义的命令行/YAML 参数里，我们另有一篇专门讲这批默认值。这两层最容易被混着谈：dataset_info.json 描述的是”这份数据长什么样”，data_args 描述的是”这次训练怎么用它”。

顺带说一个两层之间对得上的点：dataset_dir 在 data/README.md 里写的默认值是 ./data，在 hparams/data_args.py 里读到的默认值是 "data"，指的是同一个位置的两种写法。而 dataset 和 template 在 data_args.py 里的默认值都是 None——也就是说框架不会替你猜用哪个数据集、用哪个模板，这两个必须自己给。

路径与平台

这一篇通篇是 JSON 字段，没有需要区分 Windows 与 Linux/macOS 的命令。唯一和平台相关的是路径写法：官方在这份文档里只规定了 dataset_info.json 必须放在 dataset_dir 下，并给了默认值 ./data，没有给 Windows 下的绝对路径示例。所以别照抄别人文章里那种带盘符的完整路径，自己的目录用 <你的项目目录> 这种占位思路去替换就行。

一处新旧写法并存

data/README.md 讲 enable_thinking 的那条 TIP 里，主语写的是 LLaMA-Factory（带连字符的旧写法），而仓库的当前路径是 hiyouga/LlamaFactory，PyPI 包名是 llamafactory。README 正文里两种拼法都出现过。这是仓库里能核实到的新旧写法并存，如实说到这儿就够——改名时间、原因、有没有重定向，我们都没有核实过，不做推断。对你的实际影响只有一条：搜资料、翻 issue 时两种拼法都试一遍。

最后：不要问”该填多少”

这份规格里的字段几乎都是结构性的——它们回答”你的数据长什么样”，而不是”你想训得多狠”。formatting 填什么取决于你的文件是哪种结构，columns 填什么取决于你的列名，ranking 填什么取决于你要不要做偏好训练。这几个字段没有”推荐值”这回事，官方也没给。

真正需要权衡取舍的那些值不在这个文件里。哪怕是 num_samples 这种看起来可以调的字段，该取多少也取决于你的数据规模和硬件，官方没给通用值，我们也没有跑过任何一次训练来给你一个数。

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