> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据集和格式

> 如何构建您的训练数据

# 数据集和格式

您的模型的好坏取决于您的数据。以下是如何正确格式化它。

## 支持的文件格式

AITraining 支持多种数据源：

| 格式               | 如何加载                           | 用例            |
| ---------------- | ------------------------------ | ------------- |
| JSONL            | `pandas.read_json(lines=True)` | LLM 训练、对话     |
| CSV              | `pandas.read_csv()`            | 分类、表格数据       |
| HF Dataset ID    | `datasets.load_dataset()`      | 来自 Hub 的远程数据集 |
| Local HF Dataset | `load_from_disk()`             | 预处理的数据集       |

<Note>
  Parquet 文件通过暴露 Parquet 格式的 HuggingFace 数据集间接支持。
</Note>

## 常见格式

### CSV（最常见）

简单且通用。适用于分类、回归和基本任务。

```csv theme={null}
text,label
"This product is amazing",positive
"Terrible experience",negative
"Average quality",neutral
```

### JSON/JSONL

更适合复杂数据、对话和嵌套结构。

```json theme={null}
{"messages": [
  {"role": "user", "content": "What is Python?"},
  {"role": "assistant", "content": "Python is a programming language"}
]}
```

### 图像文件夹

按类别组织图像：

```
dataset/
  cats/
    cat1.jpg
    cat2.jpg
  dogs/
    dog1.jpg
    dog2.jpg
```

## 数据质量基础

### 平衡您的类别

不好：

* 1000 个积极示例
* 50 个消极示例

好：

* 500 个积极示例
* 500 个消极示例

### 清理您的数据

删除：

* 重复项
* 空值
* 明显错误
* 不一致的格式

### 大小指南

| 任务类型                 | 最少  | 良好    | 优秀      |
| -------------------- | --- | ----- | ------- |
| Text Classification  | 100 | 1,000 | 10,000+ |
| Image Classification | 200 | 2,000 | 20,000+ |
| Language Generation  | 50  | 500   | 5,000+  |

## 按训练器要求的列

不同的训练器需要特定的列：

| 训练器               | 必需列                            | 可选 |
| ----------------- | ------------------------------ | -- |
| `sft` / `default` | `text`（或 `messages`）           | -  |
| `dpo`             | `prompt`, `chosen`, `rejected` | -  |
| `orpo`            | `prompt`, `chosen`, `rejected` | -  |
| `reward`          | `text` (chosen), `rejected`    | -  |

<Warning>
  如果缺少必需的列，您将收到一个清晰的验证错误，列出缺少和可用的列。
</Warning>

## 特殊格式

### DPO/ORPO（偏好数据）

```json theme={null}
{
  "prompt": "Explain gravity",
  "chosen": "Gravity is a force that attracts objects...",
  "rejected": "gravity is thing that make stuff fall"
}
```

### Token Classification

```
John    B-PERSON
Smith   I-PERSON
visited O
Paris   B-LOCATION
```

### 对话格式

对话期望 `{role, content}` 对象列表：

```json theme={null}
{"messages": [
  {"role": "user", "content": "Hello"},
  {"role": "assistant", "content": "Hi there!"}
]}
```

或 ShareGPT 格式（自动检测和转换）：

```json theme={null}
{"conversations": [
  {"from": "human", "value": "Hello"},
  {"from": "assistant", "value": "Hi there!"}
]}
```

#### Tool 角色支持

AITraining 支持 `tool` 角色用于函数调用训练数据：

```json theme={null}
{"messages": [
  {"role": "user", "content": "2+2等于多少？"},
  {"role": "assistant", "content": "让我计算一下。"},
  {"role": "tool", "content": "4"},
  {"role": "assistant", "content": "答案是4。"}
]}
```

<Note>
  **自动兼容性**：对于不原生支持 `tool` 角色的模型（如 Gemma），AITraining 会自动将 `tool` 消息转换为带有 `[Tool Result]` 前缀的 `user` 消息。具有原生 tool 支持的模型（Llama 3.1+、Qwen 等）使用其原生格式。
</Note>

<Note>
  **旧版格式支持**：旧版 OpenAI `function` 角色（在引入 `tool` 之前使用）也受支持，处理方式与 `tool` 角色相同。
</Note>

#### Tool Calls（函数调用）

AITraining 还支持 `tool_calls` 字段用于训练模型进行函数调用：

```json theme={null}
{"messages": [
  {"role": "user", "content": "巴黎的天气怎么样？"},
  {
    "role": "assistant",
    "content": "让我查一下。",
    "tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\": \"Paris\"}"}}]
  },
  {"role": "tool", "content": "晴天，20度"},
  {"role": "assistant", "content": "巴黎是晴天，20度。"}
]}
```

<Note>
  **智能格式检测**：AITraining 会检测您的模型是否原生支持 `tool_calls`：

  * **Qwen、Llama 3.1+**：使用原生 `<tool_call>` 格式
  * **Gemma、旧模型**：将工具调用序列化为内容中的 OpenAI 格式 JSON

  在推理时，从助手输出中解析 JSON 以提取工具调用。
</Note>

#### Tool Call 格式转换

对于没有原生工具支持的模型，AITraining 将工具调用序列化为 OpenAI 格式 JSON 并附加到助手内容中：

**输入（带有 tool\_calls 字段的消息）：**

```json theme={null}
{
  "role": "assistant",
  "content": "让我搜索一下。",
  "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "search", "arguments": "{\"query\": \"weather\"}"}}]
}
```

**输出（序列化在内容中）：**

```json theme={null}
让我搜索一下。
{"content": "让我搜索一下。", "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "search", "arguments": "{\"query\": \"weather\"}"}}]}
```

<Note>
  序列化格式保留了完整的 OpenAI 结构，包括 `id`、`type` 和 `function` 字段。这与系统提示中描述的格式一致，有助于模型更好地学习。
</Note>

#### 消息交替处理

某些模型（Gemma、Mistral）要求严格的 user/assistant 交替。AITraining 会自动修复常见问题：

**连续相同角色的消息**会被合并：

```json theme={null}
// 之前（在 Gemma 上会失败）
[
  {"role": "assistant", "content": "你好！"},
  {"role": "assistant", "content": "有什么可以帮你的？"}
]

// 之后（自动修复）
[
  {"role": "assistant", "content": "你好！\n有什么可以帮你的？"}
]
```

**assistant 前缺少 user** 会添加占位符：

```json theme={null}
// 之前（system → assistant，没有 user）
[
  {"role": "system", "content": "你是一个有用的助手"},
  {"role": "assistant", "content": "你好！"}
]

// 之后（自动修复）
[
  {"role": "system", "content": "你是一个有用的助手"},
  {"role": "user", "content": "[Continued]"},
  {"role": "assistant", "content": "你好！"}
]
```

<Note>
  这些修复仅在 tokenizer 拒绝原始格式时应用。接受灵活消息顺序的模型会保持原始结构。
</Note>

## 自动数据集转换

AITraining 可以自动检测和转换常见的数据集格式。无需手动预处理。

### 支持的格式

| 格式             | 检测 | 示例列                                     |
| -------------- | -- | --------------------------------------- |
| Alpaca         | 自动 | `instruction`, `input`, `output`        |
| ShareGPT       | 自动 | `conversations` 带 `from`/`value`        |
| Messages       | 自动 | `messages` 带 `role`/`content`           |
| Q\&A           | 自动 | `question`/`answer`, `query`/`response` |
| User/Assistant | 自动 | `user`, `assistant`                     |
| DPO            | 自动 | `prompt`, `chosen`, `rejected`          |
| Plain Text     | 自动 | `text`                                  |

列映射是可选的 - 使用它将不同的列名转换为预期格式。

### 使用自动转换

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path tatsu-lab/alpaca \
  --auto-convert-dataset \
  --chat-template gemma3 \
  --trainer sft
```

### Chat Templates

Chat templates 将您的数据格式化为模型预期的对话结构。

| 选项          | 描述                                       |
| ----------- | ---------------------------------------- |
| `tokenizer` | 使用模型的内置 chat template（SFT/DPO/ORPO 的默认值） |
| `chatml`    | 标准 ChatML 格式                             |
| `zephyr`    | Zephyr/Mistral 格式                        |
| `none`      | 无模板（纯文本）                                 |

模板根据您的训练器自动选择，或手动指定：

```bash theme={null}
--chat-template tokenizer  # 使用模型的模板（推荐）
--chat-template chatml     # 强制 ChatML
--chat-template none       # 禁用纯文本
```

<Note>
  统一渲染器一致地应用模板。为了向后兼容，仍支持旧版模板路径。
</Note>

### 对话扩展

将单轮示例合并为多轮对话：

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./qa_pairs.jsonl \
  --auto-convert-dataset \
  --conversation-extension 3 \
  --trainer sft
```

## 处理后数据集输出

处理后，您的数据集将包含：

| 列                    | 描述              |
| -------------------- | --------------- |
| `text`               | 应用聊天模板后的格式化训练数据 |
| `_original_messages` | 原始消息列（保留用于检查）   |
| `_original_*`        | 其他原始列重命名为带前缀    |

<Note>
  原始列被重命名为 `_original_*`，以防止其他工具自动检测并错误使用未处理的数据。
</Note>

### 保存处理后的数据

使用 `--save-processed-data` 控制处理后数据的保存位置：

| 选项      | 行为                               |
| ------- | -------------------------------- |
| `auto`  | 本地保存；如果源自 Hub 则也推送到 Hub          |
| `local` | 仅保存到 `{project}/data_processed/` |
| `hub`   | 仅作为私有数据集推送到 Hub                  |
| `both`  | 本地保存并推送到 Hub                     |
| `none`  | 不保存处理后的数据                        |

## 快速提示

1. **从小开始** - 在扩展之前先用 100 个示例测试
2. **尽早验证** - 在收集数千个示例之前检查您的格式是否有效
3. **保持一致** - 在整个数据集中使用相同的格式
4. **记录一切** - 注意任何预处理或特殊规则
5. **使用自动转换** - 让 AITraining 自动检测和转换格式

## 下一步

<CardGroup cols={2}>
  <Card title="超参数" href="/foundations/hyperparameters">
    配置您的训练
  </Card>

  <Card title="训练任务" href="/foundations/training-tasks">
    选择您的任务类型
  </Card>
</CardGroup>