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

# sf dataset

> 数据集：本地预处理、版本化上传、可见性管理

工作流讲解见[数据集管理](/zh-Hans/guides/datasets)。

## sf dataset prepare

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset prepare              # 不带参数：列出可用的预处理脚本
sf dataset prepare <名称>       # 运行 common/data/prepare_<名称>.py
```

按约定发现 `common/data/prepare_*.py`，本地执行产出数据目录。

## sf dataset push

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset push <DATASET> <VERSION> <PATH> [--public] [--readme README.md]
```

| 参数         | 说明                                             |
| ---------- | ---------------------------------------------- |
| `DATASET`  | 数据集名（归到自己命名空间）；admin 可用 `<owner>/<name>` 跨命名空间 |
| `VERSION`  | 版本号，如 `v1` / `20260812`；**不可变**，同名版本不能覆盖       |
| `PATH`     | 本地目录                                           |
| `--public` | 首次创建时设为公开（全平台可引用）                              |
| `--readme` | 指定说明文件；不传时自动用 `<PATH>/README.md`（有就发）          |

上传特性：流式分片、逐文件 SHA256、**断点续传**（中断后重跑自动跳过已传文件）。

目录里放一个 `README.md`，push 会把它一并发成**数据集说明**（见下）。

## sf dataset card

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset card <DATASET>                     # 打印当前说明
sf dataset card <DATASET> -f README.md        # 用这份 markdown 更新说明
```

说明是数据集的属性，不属于某一个版本：改说明不用重推一版数据。首段会被摘成一句话，
显示在 `sf dataset ls` 与控制台列表的每一行上。

## sf dataset check —— 推送前先查污染

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset check ./out/my-train --against ./eval/gsm8k-test.jsonl
sf dataset check ./out/my-train --against ./eval/test.jsonl --fields question
```

要挡住的是**无意中把测试题训进去了**：从同一个公开数据集切 train/test、拿别人清洗过的
混合语料（里面正好含 GSM8K）。后果是分数虚高且无人察觉——模型在背过的题上考了 90 分，
你据此上线，线上表现对不上。

查出来的是**具体哪几条**，因为你要做的动作是「把这几条删掉」：

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  !  3 / 12000 条训练数据与评测集重合（0.0%）
     · Natalia sold clips to 48 of her friends in April, and then she sold…
  →  这些条目会让评测分数虚高。删掉它们，或换一个评测集。
```

有重合时退出码是 1——放进 CI 就能拦住一次带污染的推送。

`--fields` 限定只看题干：答案里恰好出现同一个词不该报警。

判定按归一化后的 13-gram（GPT-3 / PaLM 的污染分析用的窗口）。大小写、标点、全角半角
不影响判定；中文按字切分，否则一整句会变成一个 token、永远查不出重合。

## sf dataset quality —— 这份数据自己干不干净

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset quality ./out/my-train
```

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
12000 条记录
  重复      842 条（7.0%），其中逐字相同 310 条
  空记录    0 条（0.0%）
  文本长度  中位 180 · p95 1400 · 最长 9000 字符
  字段      answer, prompt
  !  重复率 7.0% 偏高
  →  模型会过拟合到重复样本上。去重后再推，或确认这是有意的采样权重。
```

`sf dataset push` 会自动算一份随版本存，控制台数据集详情页顶部直接显示。这个命令用于推送之前先看看。

四个数各自防一类问题：

| 指标         | 它防什么                                                           |
| ---------- | -------------------------------------------------------------- |
| **重复率**    | 训练集里 30% 是重复样本，模型会过拟合到那些样本上，而这件事今天在平台上完全看不见                    |
| **长度 p95** | 判断 `max_seq_len` 够不够的是 p95，不是平均值——平均值会被一堆短样本拉下来，然后 5% 的样本被静默截断 |
| **空记录**    | 整条为空的样本会稀释梯度信号                                                 |
| **字段漂移**   | 一半记录有 `answer` 字段、另一半没有，训练时那一半会读到 None                         |

只统计**机器能确定数出来**的量。「这条回答好不好」是人或模型的判断，不在这里——那是[人工偏好标注](/zh-Hans/guides/annotation)的范畴。

近重复用 MinHash 的小型版本：模板生成的数据（50 条只差一个数字）会被判成重复——**那不是误报**，它正是这份报告最该说出来的一类问题。

## 污染指纹（跨端比对）

`sf dataset push` 会顺带算一份 **n-gram 指纹**（抽样后的哈希集合，几百 KB）随版本上传。
推送时每个文件本来就要读一遍算 sha256，切 n-gram 几乎不额外花钱；而事后再算要把几 GB
数据拉回来，那件事贵到没人会做。

有了指纹，平台侧比对两个数据集只是两个小集合求交：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 控制台或 API：训练集与评测集重合多少
GET /api/datasets/<owner>/<name>/contamination?against=<owner>/<eval-name>
```

给平台外的数据（比如某个基准的测试集）也能单独算：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset fingerprint ./gsm8k-test.jsonl -o gsm8k.fingerprint.json
```

<Note>
  指纹比对给的是**估算**：抽样只允许假阴性，很小的数据集可能一条都没抽中。
  小数据集用 `sf dataset check` 精确查——它给条目，指纹只给比例。
  推送时还没有这个功能的老版本没有指纹，接口会明说「比不了」，而不是回一个
  假的「没有污染」。
</Note>

## sf dataset ls / visibility

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset ls                              # 可见数据集（公开 + 自己的）
sf dataset ls <DATASET> [-v <VERSION>]     # 某一版的文件清单
sf dataset visibility <DATASET> --public   # 改可见性（owner 或 admin）
sf dataset visibility <DATASET> --private
```

`ls` 每行给出最新版本、文件数、体积、格式与更新时间：

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
alice/gsm8k-zh                   [公开] v2 · 3 个文件 · 39.1 MB · parquet · 3 天前 · 共 2 版
                                 从 GSM8K 改写的中文数学题，已去重。
```

## 在训练中引用

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf submit my-exp --train-dataset alice/gsm8k-zh@v2 --train-data train.parquet
```

作业启动自动分发到集群共享缓存并注入 `<NAME>_DATA_DIR`；推荐把引用固化在实验 config 的 `data.train.dataset`。

## `sf dataset`

Manage datasets

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset <subcommand>
```

| 命令                       | 说明                                             |
| ------------------------ | ---------------------------------------------- |
| `sf dataset card`        | Show/update a dataset description (README.md)  |
| `sf dataset check`       | Check training data for evaluation overlap     |
| `sf dataset fingerprint` | Compute a dataset fingerprint                  |
| `sf dataset ls`          | List the visible datasets                      |
| `sf dataset prepare`     | Preprocess a dataset locally                   |
| `sf dataset push`        | Upload one dataset version                     |
| `sf dataset quality`     | Produce a dataset quality report               |
| `sf dataset visibility`  | Change a dataset's visibility (owner or admin) |

### `sf dataset card`

Show/update a dataset description (README.md)

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset card <DATASET> [options]
```

| 参数        | 说明                                     |
| --------- | -------------------------------------- |
| `DATASET` | Dataset id (\<owner>/\<name>) (**必填**) |

| 选项             | 说明                                                                            |
| -------------- | ----------------------------------------------------------------------------- |
| `--file`, `-f` | Update the description from this markdown file; omit to print the current one |

### `sf dataset check`

Check training data for evaluation overlap

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset check <PATH> [options]
```

| 参数     | 说明                                                                      |
| ------ | ----------------------------------------------------------------------- |
| `PATH` | Training data directory or file (jsonl / json / csv / parquet) (**必填**) |

| 选项                | 说明                                                                                                    |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| `--against`, `-a` | Evaluation set directory or file; the question is whether its questions leaked into training (**必填**) |
| `--fields`        | Only these fields (comma separated), e.g. question,prompt. Defaults to every string field             |

### `sf dataset fingerprint`

Compute a dataset fingerprint

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset fingerprint <PATH> [options]
```

| 参数     | 说明                              |
| ------ | ------------------------------- |
| `PATH` | Data directory or file (**必填**) |

| 选项            | 说明                                             |
| ------------- | ---------------------------------------------- |
| `--out`, `-o` | Write it to this file; omit to print a summary |
| `--fields`    | Only these fields (comma separated)            |

### `sf dataset ls`

List the visible datasets

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset ls [DATASET] [options]
```

| 参数        | 说明                                                             |
| --------- | -------------------------------------------------------------- |
| `DATASET` | Dataset id (\<owner>/\<name>); omit to list everything visible |

| 选项                | 说明                                                   |
| ----------------- | ---------------------------------------------------- |
| `--version`, `-v` | Show one version's file list; defaults to the latest |

### `sf dataset prepare`

Preprocess a dataset locally

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset prepare [DATASET]
```

| 参数        | 说明                                            |
| --------- | --------------------------------------------- |
| `DATASET` | Dataset name; leave empty to list the options |

除 `--help` 外没有其他选项。

### `sf dataset push`

Upload one dataset version

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset push <DATASET> <VERSION> <PATH> [options]
```

| 参数        | 说明                                                                                                              |
| --------- | --------------------------------------------------------------------------------------------------------------- |
| `DATASET` | Dataset name (lands in your own namespace), or a full \<owner>/\<name> (an admin can cross namespaces) (**必填**) |
| `VERSION` | Version, e.g. v1 / 20260812 (**必填**)                                                                            |
| `PATH`    | Local directory (**必填**)                                                                                        |

| 选项         | 说明                                                                         |
| ---------- | -------------------------------------------------------------------------- |
| `--public` | Make it public on first creation (anyone can reference it in training)     |
| `--readme` | Dataset description (markdown); defaults to the README.md in the directory |

### `sf dataset quality`

Produce a dataset quality report

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset quality <PATH> [options]
```

| 参数     | 说明                              |
| ------ | ------------------------------- |
| `PATH` | Data directory or file (**必填**) |

| 选项         | 说明                                  |
| ---------- | ----------------------------------- |
| `--fields` | Only these fields (comma separated) |

### `sf dataset visibility`

Change a dataset's visibility (owner or admin)

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf dataset visibility <DATASET> [options]
```

| 参数        | 说明                                     |
| --------- | -------------------------------------- |
| `DATASET` | Dataset id (\<owner>/\<name>) (**必填**) |

| 选项          | 说明              |
| ----------- | --------------- |
| `--public`  | Make it public  |
| `--private` | Make it private |