懒加载数据集

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 一致。