一、框架概述

LLaMA-Factory 框架通过Alpaca/Sharegpt双格式体系实现多任务适配，其中Alpaca专注结构化指令微调（含SFT/DPO/预训练），Sharegpt支持多角色对话及多模态数据集成。核心配置依托 dataset_info.json 实现数据源映射、格式定义（formatting）、列名绑定（columns）及角色标签（tags）设置，需特别注意多模态路径与文本标记的严格匹配。优先级规则遵循：云端仓库 > 本地脚本 > 文件直读，配置时须规避角色标签冲突和路径验证疏漏等常见误区。

二、数据集配置规范

"数据集名称": {"hf_hub_url": "Hugging Face 的数据集仓库地址（若指定，则忽略 script_url 和 file_name）","ms_hub_url": "ModelScope 的数据集仓库地址（若指定，则忽略 script_url 和 file_name）","script_url": "包含数据加载脚本的本地文件夹名称（若指定，则忽略 file_name）","file_name": "该目录下数据集文件夹或文件的名称（若上述参数未指定，则此项必需）","formatting": "数据集格式（可选，默认：alpaca，可以为 alpaca 或 sharegpt）","ranking": "是否为偏好数据集（可选，默认：False）","subset": "数据集子集的名称（可选，默认：None）","split": "所使用的数据集切分（可选，默认：train）","folder": "Hugging Face 仓库的文件夹名称（可选，默认：None）","num_samples": "该数据集所使用的样本数量。（可选，默认：None）","columns（可选）": {"prompt": "数据集代表提示词的表头名称（默认：instruction）","query": "数据集代表请求的表头名称（默认：input）","response": "数据集代表回答的表头名称（默认：output）","history": "数据集代表历史对话的表头名称（默认：None）","messages": "数据集代表消息列表的表头名称（默认：conversations）","system": "数据集代表系统提示的表头名称（默认：None）","tools": "数据集代表工具描述的表头名称（默认：None）","images": "数据集代表图像输入的表头名称（默认：None）","videos": "数据集代表视频输入的表头名称（默认：None）","audios": "数据集代表音频输入的表头名称（默认：None）","chosen": "数据集代表更优回答的表头名称（默认：None）","rejected": "数据集代表更差回答的表头名称（默认：None）","kto_tag": "数据集代表 KTO 标签的表头名称（默认：None）"},"tags（可选，用于 sharegpt 格式）": {"role_tag": "消息中代表发送者身份的键名（默认：from）","content_tag": "消息中代表文本内容的键名（默认：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，会覆盖 system column）"}
}

Alpaca 格式

指令监督微调数据集

• 样例数据集

在指令监督微调时，instruction 列对应的内容会与 input 列对应的内容拼接后作为人类指令，即人类指令为 instruction\ninput。而 output 列对应的内容为模型回答。

如果指定，system 列对应的内容将被作为系统提示词。

history 列是由多个字符串二元组构成的列表，分别代表历史消息中每轮对话的指令和回答。注意在指令监督微调时，历史消息中的回答内容也会被用于模型学习。

[{"instruction": "人类指令（必填）","input": "人类输入（选填）","output": "模型回答（必填）","system": "系统提示词（选填）","history": [["第一轮指令（选填）", "第一轮回答（选填）"],["第二轮指令（选填）", "第二轮回答（选填）"]]}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","columns": {"prompt": "instruction","query": "input","response": "output","system": "system","history": "history"}
}

预训练数据集

• 样例数据集

在预训练时，只有 text 列中的内容会用于模型学习。

[{"text": "document"},{"text": "document"}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","columns": {"prompt": "text"}
}

偏好数据集

偏好数据集用于奖励模型训练、DPO 训练、ORPO 训练和 SimPO 训练。

它需要在 chosen 列中提供更优的回答，并在 rejected 列中提供更差的回答。

[{"instruction": "人类指令（必填）","input": "人类输入（选填）","chosen": "优质回答（必填）","rejected": "劣质回答（必填）"}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","ranking": true,"columns": {"prompt": "instruction","query": "input","chosen": "chosen","rejected": "rejected"}
}

KTO 数据集

KTO 数据集需要提供额外的 kto_tag 列。详情请参阅 sharegpt。

多模态图像数据集

多模态图像数据集需要提供额外的 images 列。详情请参阅 sharegpt。

多模态视频数据集

多模态视频数据集需要提供额外的 videos 列。详情请参阅 sharegpt。

多模态音频数据集

多模态音频数据集需要提供额外的 audios 列。详情请参阅 sharegpt。

Sharegpt 格式

指令监督微调数据集

• 样例数据集

相比 alpaca 格式的数据集，sharegpt 格式支持更多的角色种类，例如 human、gpt、observation、function 等等。它们构成一个对象列表呈现在 conversations 列中。

注意其中 human 和 observation 必须出现在奇数位置，gpt 和 function 必须出现在偶数位置。

[{"conversations": [{"from": "human","value": "人类指令"},{"from": "function_call","value": "工具参数"},{"from": "observation","value": "工具结果"},{"from": "gpt","value": "模型回答"}],"system": "系统提示词（选填）","tools": "工具描述（选填）"}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","system": "system","tools": "tools"}
}

预训练数据集

尚不支持，请使用 alpaca 格式。

偏好数据集

• 样例数据集

Sharegpt 格式的偏好数据集同样需要在 chosen 列中提供更优的消息，并在 rejected 列中提供更差的消息。

[{"conversations": [{"from": "human","value": "人类指令"},{"from": "gpt","value": "模型回答"},{"from": "human","value": "人类指令"}],"chosen": {"from": "gpt","value": "优质回答"},"rejected": {"from": "gpt","value": "劣质回答"}}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","formatting": "sharegpt","ranking": true,"columns": {"messages": "conversations","chosen": "chosen","rejected": "rejected"}
}

KTO 数据集

• 样例数据集

KTO 数据集需要额外添加一个 kto_tag 列，包含 bool 类型的人类反馈。

[{"conversations": [{"from": "human","value": "人类指令"},{"from": "gpt","value": "模型回答"}],"kto_tag": "人类反馈 [true/false]（必填）"}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","kto_tag": "kto_tag"}
}

多模态图像数据集

• 样例数据集

多模态图像数据集需要额外添加一个 images 列，包含输入图像的路径。

注意图片的数量必须与文本中所有 <image> 标记的数量严格一致。

[{"conversations": [{"from": "human","value": "<image>人类指令"},{"from": "gpt","value": "模型回答"}],"images": ["图像路径（必填）"]}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","images": "images"}
}

多模态视频数据集

• 样例数据集

多模态视频数据集需要额外添加一个 videos 列，包含输入视频的路径。

注意视频的数量必须与文本中所有 <video> 标记的数量严格一致。

[{"conversations": [{"from": "human","value": "<video>人类指令"},{"from": "gpt","value": "模型回答"}],"videos": ["视频路径（必填）"]}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","videos": "videos"}
}

多模态音频数据集

• 样例数据集

多模态音频数据集需要额外添加一个 audios 列，包含输入音频的路径。

注意音频的数量必须与文本中所有 <audio> 标记的数量严格一致。

[{"conversations": [{"from": "human","value": "<audio>人类指令"},{"from": "gpt","value": "模型回答"}],"audios": ["音频路径（必填）"]}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "conversations","audios": "audios"}
}

OpenAI 格式

OpenAI 格式仅仅是 sharegpt 格式的一种特殊情况，其中第一条消息可能是系统提示词。

[{"messages": [{"role": "system","content": "系统提示词（选填）"},{"role": "user","content": "人类指令"},{"role": "assistant","content": "模型回答"}]}
]

对于上述格式的数据，dataset_info.json 中的数据集描述应为：

"数据集名称": {"file_name": "data.json","formatting": "sharegpt","columns": {"messages": "messages"},"tags": {"role_tag": "role","content_tag": "content","user_tag": "user","assistant_tag": "assistant","system_tag": "system"}
}

三、常见问题排查

问题：dataset_info.json 中 hf_hub_url、ms_hub_url、script_url、file_name 的优先级关系是什么？

答案：

优先级为 hf_hub_url/ms_hub_url > script_url > file_name。若指定了 hf_hub_url 或 ms_hub_url，系统会直接从 Hugging Face 或 ModelScope 加载数据集，忽略 script_url 和 file_name；若未指定，则依次检查 script_url 和 file_name。

误区举例：用户可能同时填写多个字段（如同时指定 hf_hub_url 和 file_name），导致实际加载数据集时忽略本地文件，引发数据路径错误。

问题：偏好数据集（DPO/ORPO）的配置中，Alpaca 格式和 Sharegpt 格式的 columns 字段有何差异？

答案：

• Alpaca 格式需指定 chosen 和 rejected 列，对应优质和劣质回答，并设置 "ranking": true。
• Sharegpt 格式需将 chosen 和 rejected 配置为消息对象（如 {"from": "gpt", "value": "回答"}），并同样设置 "ranking": true。

误区举例：用户可能误将 Sharegpt 格式的 chosen/rejected 配置为纯文本（而非消息对象），导致解析失败；或在 Alpaca 格式中遗漏 "ranking": true，导致数据集未被识别为偏好类型。

问题：多模态数据集（如图像）的配置中，images 列与文本中的 <image> 标记为何需严格数量一致？

答案：

images 列中的文件路径数量必须与文本中 <image> 标记的数量完全一致，以确保模型能正确关联图像输入与文本指令。例如，若文本中有 2 个 <image> 标记，则 images 列必须包含 2 个路径。

误区举例：用户可能在数据预处理时未检查标记数量与文件路径的匹配性，导致训练时因数据格式错误而中断。

问题：Sharegpt 格式的 tags 字段（如 role_tag、user_tag）有何作用？如何适配 OpenAI 格式数据？

答案：

• tags 字段用于自定义消息中角色和内容的键名。例如，OpenAI 格式的 role 和 content 需通过 tags 映射为 role_tag: "role" 和 content_tag: "content"。
• 适配 OpenAI 格式需额外设置 user_tag: "user"、assistant_tag: "assistant"、system_tag: "system"。

误区举例：用户可能未正确配置 tags，导致无法解析第三方格式（如 OpenAI）的消息结构，或因角色标签冲突（如 system 覆盖系统列）引发错误。

问题：KTO 数据集的 kto_tag 列在配置时需要注意什么？

答案：

kto_tag 列需包含布尔类型（True/False）的标签，表示人类对回答的反馈。在 dataset_info.json 中需显式声明 "kto_tag": "列名"，且数据集格式必须为 Sharegpt。

误区举例：用户可能误将 kto_tag 配置为字符串（如 "true" 而非布尔值 true），或忘记设置 "formatting": "sharegpt"，导致数据加载失败。

问题：在 Alpaca 格式中，history 列的作用是什么？如何正确配置它？

答案：

• 作用: history 列存储历史对话的指令和回答（二元组列表），用于多轮对话场景。模型会学习历史对话内容，而不仅是当前指令和回答。
• 配置: 需在 dataset_info.json 中明确指定 "history": "列名"，且数据格式应为 [["指令1", "回答1"], ["指令2", "回答2"]]。

误区举例: 用户可能忽略 history 列的存在，导致多轮对话数据未被利用；或错误配置为单字符串（如 "instruction,answer"），引发解析错误。

问题：预训练数据集的 Alpaca 格式为何只需 text 列？如何与指令微调数据集区分？

答案：

• 原因: 预训练目标是学习通用文本表示，因此仅需原始文本（text 列），无需指令或回答结构。
• 区分: 指令微调需 instruction/output 等列，而预训练只需 "columns": {"prompt": "text"}。若误用指令数据配置预训练，会导致模型忽略关键字段。

误区举例: 用户可能混淆预训练和微调的数据格式，错误地将指令数据用于预训练，浪费计算资源。

问题：Sharegpt 格式中，tools 列的作用是什么？是否必须与 function_call 角色配合使用？

答案：

• 作用: tools 列定义工具的描述（如 API 文档），供模型生成工具调用参数（function_call 角色）。
• 配合要求: 是。若数据包含 function_call 消息，则需提供 tools 列；若无工具调用，可省略。

误区举例: 用户可能遗漏 tools 列但保留 function_call 消息，导致模型无法理解工具定义；或反向误配，引发训练错误。

问题：如何正确处理多模态数据（如图像、视频）中的路径问题？

答案：

• 要求: 文件路径需为绝对路径或相对于数据集根目录的相对路径，且确保文件实际存在。
• 验证: 在加载数据集前，应检查 images/videos/audios 列中的路径是否有效，避免因路径错误导致训练中断。

误区举例: 用户可能使用错误路径格式（如未处理系统路径分隔符差异），或未验证文件是否存在，导致多模态数据加载失败。

问题：subset 和 split 字段在 dataset_info.json 中有何区别？

答案：

• subset: 指定 Hugging Face/ModelScope 数据集的子集名称（如 "zh" 表示中文子集）。
• split: 定义数据切分（如 train、test），默认为 train。两者可同时使用（如 "subset": "zh", "split": "test"）。

误区举例: 用户可能误将 subset 当作数据切分，或混淆两者优先级，导致加载错误的数据子集。

问题：如何为自定义数据集选择正确的 formatting 值（alpaca 或 sharegpt）？

答案：

• 关键判断点:
  1. 角色多样性: 若需多角色（如 human/gpt/function），选 sharegpt。
  2. 工具/多模态支持: 涉及工具调用或媒体输入时，必须用 sharegpt。
  3. 结构简化性: 若仅需 instruction-output 结构，用 alpaca。

误区举例: 用户可能因未全面评估数据复杂度而选错格式，导致后续配置无法适配。