数据集 | Twinkle

基本数据集组件

Mon, 01 Jan 0001 00:00:00 +0000

DatasetMeta

开源社区的数据集可以由三个字段定义：

数据集名称：代表了数据集 ID，例如 swift/self-cognition。
子数据集名称：一个数据集可能包含了多个子数据集，而且每个子数据集格式可能不同。
子数据集分片：常见分片有 train/test 等，用于训练、验证等。

使用 Hugging Face 社区的 datasets 库可以看到一个加载数据集的例子：

from datasets import load_dataset
train_data = load_dataset("glue", "mrpc", split="train")

在 Twinkle 的数据集输入中，使用 DatasetMeta 类来表达输入数据格式。该类包含：

@dataclass
class DatasetMeta:
 dataset_id: str
 subset_name: str = 'default'
 split: str = 'train'
 data_slice: Iterable = None

前三个字段分别对应了数据集名称、子数据集名称、split，第四个字段 data_slice 是需要选择的数据范围，例如：

dataset_meta = DatasetMeta(..., data_slice=range(100))

使用该类时开发者无需担心 data_slice 越界。Twinkle 会针对数据集长度进行重复取样。

注意：data_slice 对流式数据集是没有效果的。

Dataset

Twinkle 的 Dataset 是实际数据集的浅封装，包含了下载、加载、混合、预处理、encode 等操作。

数据集的加载

from twinkle.dataset import Dataset, DatasetMeta

dataset = Dataset(DatasetMeta(dataset_id='ms://swift/self-cognition', data_slice=range(1500)))

数据集的 ms:// 前缀代表了从 ModelScope 社区下载，如果替换为 hf:// 会从 Hugging Face 社区下载。如果没有前缀则默认从 Hugging Face 社区下载。你也可以传递一个本地路径：

from twinkle.dataset import Dataset, DatasetMeta

dataset = Dataset(DatasetMeta(dataset_id='my/custom/dataset.jsonl', data_slice=range(1500)))

如果使用本地路径或本地文件，请遵循以下说明：

如果使用的是本地数据集文件，请传入单个文件路径（最好使用绝对路径以避免相对路径错误），不支持传入列表。
如果使用的是本地目录，请确保目录中的文件具有相同的数据结构和文件扩展名。
我们使用 datasets 库进行数据加载，支持的扩展名请查看。
设置 template

Template 组件是负责将字符串/图片多模态原始数据转换为模型输入 token 的组件。数据集可以设置一个 Template 来完成 encode 过程。

dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B', max_length=512)

set_template 方法支持传入 kwargs（例如例子中的 max_length），作为 Template 的构造参数使用。

增加数据集

dataset.add_dataset(DatasetMeta(dataset_id='ms://xxx/xxx', data_slice=range(1000)))

add_dataset 可以在已有数据集基础上增加其他数据集，并在后续调用 mix_dataset 将它们混合起来。

预处理数据

预处理数据（ETL）过程是数据清洗和标准化的重要流程。例如：

{
 "query": "some query here",
 "response": "some response with extra info",
}

这个原始数据中，response 可能包含了不规范的信息，在开始训练前需要对 response 进行过滤和修复，并更换为 Twinkle 标准的格式。于是可以编写一个方法处理对应的数据：

from twinkle.data_format import Trajectory, Message
from twinkle.dataset import DatasetMeta
def preprocess_row(row):
 query = row['query']
 response = row['response']
 if not query or not response:
 return None
 # Fix response
 response = _do_some_fix_on_response(response)
 return Trajectory(
 messages=[
 Message(role='user', content=query),
 Message(role='assistant', content=response)
 ]
 )

dataset.map(preprocess_row, dataset_meta=DatasetMeta(dataset_id='ms://xxx/xxx'))

提示：

目前 Dataset 的 map 接口不支持 batched=True 方式

如果某个 row 有问题，返回 None，dataset.map 会自动过滤空行

不同的数据集预处理方式可能不同，因此需要额外传递 dataset_meta 参数。如果没有调用过 add_dataset 方法，即 Dataset 中只有一个数据集的时候，本参数可以省略

同理，Dataset 提供了 filter 方法：

def filter_row(row):
 if ...:
 return False
 else:
 return True

dataset.filter(filter_row, dataset_meta=DatasetMeta(dataset_id='ms://xxx/xxx'))

混合数据集

当你在 Dataset 中增加了多个数据集之后，需要使用 mix_dataset 来混合它们。

dataset.mix_dataset()

编码数据集

数据集在输入模型前，一定会经过分词和编码过程转换为 token。这个过程通常由 tokenizer 组件完成。但在现在大模型训练过程中，一般不会直接使用 tokenizer，这是因为模型的训练需要额外的字段准备，仅进行 tokenizer.encode 过程不足以完成。在 Twinkle 中，编码数据集由 Template 组件来完成。上面已经讲述了如何设置 Template，下面可以直接进行 encode：

dataset.encode()

Dataset 的 map、encode、filter 等方法均使用 datasets 的 map 方式进行，因此在对应方法的 kwargs 中均可以使用对应的参数

load_from_cache_file 参数默认为 False，因为该参数设置为 True 时会引发一些数据集改变但训练仍然使用缓存的头疼问题。如果你的数据集较大而且更新不频繁，可以直接置为 True

encode 不需要指定 DatasetMeta，因为预处理过后所有数据集格式都是相同的

encode 默认使用单进程分词。数据量较大时可通过 num_proc 开启多进程并行加速，例如 dataset.encode(num_proc=8)

获取数据

同普通数据集一样，Twinkle 的 Dataset 可以通过索引来使用数据。

trajectory = dataset[0]
length = len(dataset)

远程运行支持

Dataset 类标记了 @remote_class 装饰器，因此可以在 Ray 中运行：

dataset = Dataset(..., remote_group='actor_group')
# 下面的方法会运行在 Ray worker 上
dataset.map(...)

Dataset 组件的 Ray 运行都是 first 方式，即只有一个 worker 进程运行和加载。

整体数据集的使用流程是：

构造数据集，如果需要在 Ray worker 中运行则传入 remote_group 参数

设置 template

预处理数据

如果增加了多个数据集，混合数据

encode 数据

懒加载数据集

Mon, 01 Jan 0001 00:00:00 +0000

LazyDataset 是 Dataset 的变体，它将预处理、编码等开销较大的操作推迟到 __getitem__ 时执行，从而避免大规模或多模态数据集的内存溢出问题。

与 Dataset 的关键差异

操作	Dataset	LazyDataset
`map`	立即对所有数据执行	记录操作，在 `__getitem__` 中逐条执行
`filter`	立即执行	立即执行（与 Dataset 相同，需要构建索引映射）
`mix_dataset`	立即合并数据集	记录策略，延迟解析索引
`encode`	立即编码所有数据	记录标志，在 `__getitem__` 中逐条编码

懒加载 Map

调用 map 时，LazyDataset 会记录预处理函数而非立即执行：

from twinkle.dataset import LazyDataset, DatasetMeta

dataset = LazyDataset(DatasetMeta(dataset_id='ms://xxx/xxx'))
dataset.add_dataset(DatasetMeta(dataset_id='ms://yyy/yyy'))

# 按数据集的预处理（混合前）
dataset.map(preprocess_fn_a, dataset_meta=DatasetMeta(dataset_id='ms://xxx/xxx'))
dataset.map(preprocess_fn_b, dataset_meta=DatasetMeta(dataset_id='ms://yyy/yyy'))

dataset.mix_dataset()

# 全局预处理（混合后，对所有数据生效）
dataset.map(global_preprocess_fn)

混合前：map 按数据集记录，不同数据集可以有不同的预处理流程。
混合后：map 全局记录，对所有数据统一生效。
所有 map 操作在 __getitem__ 中按注册顺序依次执行。

懒加载 Mix

mix_dataset 支持两种策略：

dataset.mix_dataset(interleave=True) # 轮询交错（默认）
dataset.mix_dataset(interleave=False) # 顺序拼接

交错：按轮询顺序从各数据集中取数据，较短的数据集会循环。
拼接：按顺序访问——先取完数据集 A 的全部数据，再取数据集 B。

懒加载 Encode

调用 encode 仅标记需要编码，实际的 template.encode() 在 __getitem__ 中执行：

dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B', max_length=512)
dataset.encode()

注意：LazyDataset 不支持 truncation_strategy='split'，因为分割可能从单条数据产生多条输出。

即时 Filter

与其他操作不同，filter 会立即执行，因为它需要预先构建有效数据项的索引映射：

dataset.filter(filter_fn, dataset_meta=DatasetMeta(dataset_id='ms://xxx/xxx'))

远程执行

LazyDataset 拥有 @remote_class 装饰器，可以在 Ray Worker 中运行，与 Dataset 一致。

固定长度装箱数据集

Mon, 01 Jan 0001 00:00:00 +0000

装箱数据集用于将不定长的数据拼接到指定长度。例如：

数据集中包含4条长度为5的数据，而Template的组件max_length可接受长度为10，则装箱数据集会将数据预取出来，并拼接成为2条长度为10的样本。

ABCDE
FGHIJ
KLMNO
PQRST

会被转换为

ABCDEFGHIJ
KLMNOPQRST

注意这种拼接是在encode之后的，即实际的模型输入长度上。在流程中，数据集会进行如下操作：

取出buffer length个样本
对这些样本进行encode
根据每个样本的长度进行自动装箱算法计算，寻找一个最优解，使批数量最小，每个样本的长度最接近max_length
增加position_ids字段以区分不同样本。

最后形成的数据格式类似：

{
 "input_ids": [1,2,3,4,5,6,7,8,9,10],
 "position_ids": [0,1,2,3,4,0,1,2,3,4],
 ...
}

数据集的使用上和Dataset有以下区别：

必须设置Template
调用encode之后需要调用pack_dataset方法来进行最后的装箱

dataset.pack_dataset()

本数据集也有@remote_class装饰器，可以在ray的worker中运行。

流式数据集

Mon, 01 Jan 0001 00:00:00 +0000

流式数据集用于将数据集按照流的方式加载，一般用于超大规模数据集或者多模态数据集上用以节省内存使用。流式数据集没有索引和长度，只能通过迭代器访问。

twinkle的流式数据集和Dataset的方法都是相同的。但由于不提供__getitem__和__len__方法，因此流式数据集的使用需要使用next:

from twinkle.dataset import IterableDataset, DatasetMeta

dataset = IterableDataset(DatasetMeta(...))
trajectory = next(dataset)

流式数据集也有@remote_class装饰器，可以在ray的worker中运行。

流式固定长度装箱数据集

Mon, 01 Jan 0001 00:00:00 +0000

IterablePackingDataset和PackingDataset一样，同样用于数据集的自动拼接装箱。不同的是IterablePackingDataset适配于大数据集或多模态场景下的流式读取。

本数据集同样需要额外调用pack_dataset()来开启装箱过程。

dataset.pack_dataset()

本数据集也有@remote_class装饰器，可以在ray的worker中运行。