LLaMA-Factory加载ShareGPT数据集的微调配置指南

在使用LLaMA-Factory进行模型微调时，如果加载ShareGPT格式的数据集遇到解析失败、字段缺失或转换报错，问题通常源于数据结构本身不规范或配置文件未能正确适配。不必担心，这往往只是几个关键配置点没有对齐导致的。下面我们逐一梳理，确保你的数据能够被框架顺利“消化”。

一、标准ShareGPT数据结构校验与补全

首先需要明确，LLaMA-Factory对ShareGPT格式有着严格的要求：每条数据必须同时包含 conversations 数组和 system 字段，二者缺一不可。如果缺少 system，框架在转换数据时就会直接抛出 ValueError: Failed to convert pandas DataFrame to Arrow Table from file 这类错误。

因此，第一步就是检查你的 data.json 文件：

1. 打开文件，逐条检查每个JSON对象是否都包含 system 这个键。如果没有，就统一补充一个默认的系统提示，例如 "system": "You are a helpful, respectful assistant."。

2. 确认 conversations 数组里的每条消息，至少应包含 from（值应为 human 或 gpt）和 value 这两个键。

3. 最后，使用Python的 json.loads() 简单验证一下，确保整个文件能够被无错加载。这一步可以提前排除大量语法层面的低级失误。

二、dataset_info.json中ShareGPT格式的完整配置项

数据本身无误后，接下来需要关注框架如何“识别”它。LLaMA-Factory通过 dataset_info.json 这个配置文件来识别数据格式以及字段映射关系。如果你采用了ShareGPT格式，却没有明确告知框架，它就会默认按 alpaca 格式去解析，结果自然是字段错位，加载失败。

关键配置点如下：

1. 在你数据集对应的配置条目里，必须设置 "formatting": "sharegpt"。

2. 在 "tags" 对象里，要明确定义字段映射。通常，"role_tag" 对应数据里的 "from"，"content_tag" 对应 "value"。

3. 如果你的数据里角色标识使用的是 "user" 和 "assistant"，而非 "human"/"gpt"，则需要额外设置 "user_tag" 和 "assistant_tag"。

4. 同样地，如果系统提示的字段名不是 "system" 而是 "sys"，记得添加 "system_tag": "sys"。

一个完整的配置示例如下：{"formatting":"sharegpt","tags":{"role_tag":"from","content_tag":"value","user_tag":"human","assistant_tag":"gpt","system_tag":"system"}}。参照这个模板核对你的配置，基本就不会出现问题了。

三、本地ShareGPT数据集的路径与加载方式配置

如果你的数据集存放在本地，而非Hugging Face这类远程平台，路径配置就变得极为关键。路径错误或权限不足，都会导致“File not found”或数据集列表为空。

标准的做法是：

1. 将你的 data.json 文件放置在 data/your_dataset_name/ 目录下，例如 data/websec_sharegpt/data.json。

2. 在 dataset_info.json 中，设置 "file_name": "websec_sharegpt/data.json"。

3. 启动LLaMA-Factory时，务必确认终端的工作目录是项目的根目录（即能找到 llamafactory-cli 命令的那个目录）。

4. 如果使用Web UI，在“Data dir”输入框里通常只需填入 data（这是相对路径），框架会自动结合你的启动位置来寻找数据。

验证是否成功的方法很简单：在Web UI的Dataset下拉菜单里，如果能看见你的数据集名称，并且点开后显示的样本数量不是零，就说明路径配置正确了。

四、多角色/嵌套system字段的兼容性处理

有些ShareGPT格式的变体会把系统提示（system）放在 conversations 数组的第一条消息里（例如 {"from":"system","value":"..."}）。这种结构LLaMA-Factory原生并不支持，会导致系统提示被当作普通对话处理，从而影响指令微调的效果。

遇到这种情况，需要对数据进行一次预处理：

1. 遍历所有数据的 conversations 数组，找到 "from": "system" 的消息。

2. 把这条消息的 value 内容提取出来，作为一个独立的 system 字段，放到与 conversations 同级的位置。

3. 从 conversations 数组中移除这条系统消息。

4. 确保处理后的 conversations 里只包含 human 和 gpt 这两种角色的对话。

最终，每条数据都应符合这个结构：system字段与conversations字段同级，且conversations内部不再包含任何from为system的条目。

五、ShareGPT数据集切分与子集控制配置

最后一个容易踩坑的地方是数据切分（split）。LLaMA-Factory默认加载的是 split: "train"。但如果你的数据集文件包含了验证集（validation）或测试集（test），或者数据来自一个拥有多个子集（subset）的仓库，就需要精确指定，否则可能加载不到数据，或者加载了错误的集合。

具体来说：

1. 如果你的 sharegpt_zh.json 文件内部已经划分了 train 和 test，建议将其转换为Hugging Face Dataset格式，或者使用 script_url 自定义加载逻辑。

2. 更简单的做法是，提前用脚本将其拆分成独立的 train.json、test.json 文件。

3. 在 dataset_info.json 中，为训练集配置 "split": "train"，如果需要测试集，就新建一个配置条目并设置 "split": "test"。

4. 如果数据来自像 Open-Orca/Open-Orca 这样的Hugging Face数据集，并且它包含多个子集（如 preference），那么你需要同时指定 "subset": "preference" 和 "split": "train"。

这里有个关键点需要注意：配置中的 num_samples 参数只控制采样数量，不会改变 split 的语义。如果指定的 split 值在你的数据中根本不存在，那么返回的将是一个空数据集。