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

# 实验数据集

> 为 Fetch Hive 实验创建 CSV 数据集

# 实验数据集

使用 **Datasets** 为实验存储可复用的测试用例。

每个数据集可以拥有一个或多个不可变版本。运行实验时,Fetch Hive 使用特定的数据集版本,以保证该次运行可重复。

## 如何创建数据集？ <a href="#create-dataset" id="create-dataset" />

打开 **Experiments**，然后在次级导航中选择 **Datasets**。

点击 **Add Dataset**。

输入名称和可选描述。

上传 CSV 文件。你可以点击上传区域,或将 CSV 拖入其中。

检查列映射。Fetch Hive 会自动映射：

* 普通列到输入值
* `expected_output` 到期望输出
* `metadata.*` 列到行元数据

点击 **Add Dataset** 创建数据集及其第一个版本。

{/* Add screenshot: CSV mapping preview after upload */}

## 如何查看数据集版本？ <a href="#view-versions" id="view-versions" />

打开 **Experiments**，然后选择 **Datasets**。

点击数据集行打开数据集详情页。

使用页头的版本选择器在版本间切换。版本以 `v1`、`v2` 或 `v4` 等标签形式显示。

页面 URL 包含所选版本：

```text theme={null}
/experiments/datasets/:datasetId/v/:versionId
```

打开数据集时若未指定版本,会自动选择最新版本。

运行总是存储其使用的精确数据集版本,因此即使存在更新版本,旧运行仍然可复现。

## CSV 文件格式 <a href="#csv-format" id="csv-format" />

第一行必须包含列标题。

CSV 导入器支持带引号的值、引号内的逗号、转义引号、引号内的多行值以及空单元。

上传限制：

| 限制          | 值      |
| ----------- | ------ |
| 文件类型        | CSV    |
| 最大文件大小      | 5 MB   |
| 最大行数        | 10,000 |
| 对话框中显示的预览行数 | 50     |

## CSV 列 <a href="#csv-columns" id="csv-columns" />

实验数据集有三种列：

* 输入列
* 一个可选的期望输出列
* 可选的元数据列

只有输入列是运行候选项所必需的。期望输出和元数据是可选的。

### 输入列

输入列是 Fetch Hive 在该行中传入候选项的值。

对于提示词实验,它们没有固定的名称。`question`、`context` 和 `customer_message` 仅作为示例,并非必需的列名。

使用与你要测试的候选项相匹配的列名。

| 候选项类型            | CSV 输入列应当匹配什么   | 示例列                                             |
| ---------------- | --------------- | ----------------------------------------------- |
| Dashboard Prompt | 提示词编辑器中的提示词变量   | `question`、`context`、`input_url`、`input_scrape` |
| Deployed Prompt  | 所选部署版本中捕获的提示词变量 | `question`、`context`、`input_url`、`input_scrape` |
| Agent            | 智能体用户消息         | `message`                                       |

建议至少有一个输入列。没有输入列时,该次运行就没有特定于行的输入可发送给候选项。

对于提示词实验,CSV 输入列应与提示词变量匹配。如果你的提示词包含 `{{question}}` 和 `{{context}}`，你的 CSV 应包含 `question` 和 `context`。

如果你的提示词包含 `{{input_url}}` 和 `{{input_scrape}}`，你的 CSV 应改为包含 `input_url` 和 `input_scrape`。

对于智能体实验,请使用 `message` 输入列作为用户消息。如果没有 `message` 列,Fetch Hive 可以使用唯一一个非元数据输入列作为消息。包含多个含义不明确输入列的行会失败,以便你修正数据集。

### 期望输出列

当某一行有参考答案时,使用 `expected_output`。

| 列名                | 是否必填 | 存储为                     | 说明                  |
| ----------------- | ---- | ----------------------- | ------------------- |
| `expected_output` | 否    | `expected_output.value` | 目前用于人工审阅,未来用于评估器打分。 |

评估器执行尚未启用。这意味着 `expected_output` 目前不会自动将结果标记为正确或错误。

### 元数据列

使用 `metadata.*` 列作为可选的行标签。

元数据列在今天不会触发内置行为。它们不会改变运行顺序、模型设置、locale、路由或候选项执行。Fetch Hive 将其与行一同存储,以便你识别用例、筛选结果、比较分组,或将结果与你自己的系统关联起来。

| 列模式                 | 是否必填 | 存储为                               | 示例            |
| ------------------- | ---- | --------------------------------- | ------------- |
| `metadata.case_id`  | 否    | `metadata.case_id` 变为 `case_id`   | `geo-001`     |
| `metadata.topic`    | 否    | `metadata.topic` 变为 `topic`       | `geography`   |
| `metadata.priority` | 否    | `metadata.priority` 变为 `priority` | `high`        |
| `metadata.source`   | 否    | `metadata.source` 变为 `source`     | `support_faq` |
| `metadata.language` | 否    | `metadata.language` 变为 `language` | `en`          |

这些名称仅为示例。你可以使用任何有助于团队审阅结果的 `metadata.*` 名称。

对于新数据集,请勿使用 `meta_` 前缀。请使用 `metadata.*`，使映射更清晰。

### 常见的 CSV 结构

包含 `{{question}}` 的提示词：

```csv theme={null}
question,expected_output,metadata.case_id,metadata.topic
"What is the capital of France?","Paris","geo-001","geography"
```

包含 `{{question}}` 和 `{{context}}` 的提示词：

```csv theme={null}
question,context,expected_output,metadata.case_id,metadata.topic
"What is the refund window?","Customers can request a refund within 30 days.","30 days","policy-001","support"
```

包含 `{{input_url}}` 和 `{{input_scrape}}` 的提示词：

```csv theme={null}
input_url,input_scrape,expected_output,metadata.case_id,metadata.topic
"https://example.com/pricing","The pricing page lists Starter, Pro, and Enterprise plans.","Summarize the three available plans.","scrape-001","pricing"
```

## 示例 CSV <a href="#example-csv" id="example-csv" />

你可以从 **Add Dataset** 对话框下载示例 CSV。

```csv theme={null}
question,context,expected_output,metadata.case_id,metadata.topic
"What is the capital of France?","Use only the provided context. France's capital city is Paris.","Paris","geo-001","geography"
"Who wrote Pride and Prejudice?","Jane Austen published Pride and Prejudice in 1813.","Jane Austen","lit-001","literature"
"What is 18 multiplied by 7?","Calculate the product exactly.","126","math-001","math"
"Which planet is known as the Red Planet?","Mars is often called the Red Planet because of iron oxide on its surface.","Mars","space-001","science"
"What HTTP status code means Not Found?","Common HTTP status codes include 200 OK, 404 Not Found, and 500 Internal Server Error.","404","web-001","web"
"Summarize the refund policy in one sentence.","Customers can request a refund within 30 days of purchase if they provide the original receipt.","Customers can request a refund within 30 days with the original receipt.","policy-001","support"
"Return the country code for Japan.","Use ISO 3166-1 alpha-2 country codes. Japan is JP.","JP","locale-001","localization"
"What color do you get by mixing blue and yellow?","In subtractive color mixing, blue and yellow make green.","Green","art-001","art"
"Extract the invoice total.","Invoice INV-1042 lists subtotal $90, tax $9, and total $99.","$99","invoice-001","finance"
"Classify the sentiment as positive, neutral, or negative.","The customer wrote: The setup was quick and the support team was helpful.","positive","sentiment-001","classification"
```

## 数据集版本 <a href="#dataset-versions" id="dataset-versions" />

数据集版本是不可变的。

如果以后需要更改行,请创建新的数据集版本,而不是编辑已被某次运行使用的版本。这能让旧的实验运行保持可复现。

## 导入行 <a href="#importing-rows" id="importing-rows" />

在数据集详情页使用 **Import** 向数据集追加行。

导入行不会编辑当前版本。Fetch Hive 会创建一个新的不可变版本,包含：

* 来自最新数据集版本的所有行
* 上传的 CSV 中的任何新行

重复行会被跳过。重复检测会比较行的输入值。行位置、期望输出和元数据不会让相同的输入行在导入时被视作唯一。

导入后,Fetch Hive 会显示：

* 已导入的行数
* 跳过的重复行数
* 新的最新数据集版本

示例：

如果 `v3` 有 100 行,你导入了包含 20 行（其中 5 行重复）的 CSV，Fetch Hive 会创建包含 115 行的 `v4`。

导入前创建的运行仍指向其原始数据集版本。新的运行可以使用最新版本。

另请参阅：[构建实验](./building-experiments)和[查看结果](./results)