数据集 Offline/Online 流程转测目标

1. 转测背景与总体目标

本次转测用于验证 HyperParallel LLM 数据集在 Offline 和 Online 两类数据处理流程下的接口可用性、
配置有效性以及训练接入能力。

两类流程分别通过以下对外入口构建训练数据集：

from hyper_parallel.auto_models.components.datasets.llm import (
    build_indexed_text_dataset,
    build_online_text_dataset,
)

• build_indexed_text_dataset：进入离线 Indexed Dataset 读取流程。
• build_online_text_dataset：进入在线 Hugging Face Dataset 读取流程。
• Online 根据 data_config.dataset_type 继续区分 mapping 和 iterable。
• Online 完成数据源读取后进入 apply_llm_data_transform，输出训练所需的 ModelSample。
• Online 原始样本通过 plaintext 或 conversation transform 动态完成 Tokenize。
• Offline 数据在预处理阶段完成 Tokenize，训练阶段读取 .bin/.idx 数据。

整体调用链如下：

build_indexed_text_dataset
└── 读取预处理生成的 .bin/.idx

build_online_text_dataset
└── build_online_dataset
    ├── dataset_type=mapping  → load_dataset(streaming=False)
    └── dataset_type=iterable → load_dataset(streaming=True)
        ↓
    apply_llm_data_transform
        ├── plaintext transform
        └── conversation transform

本期总体转测目标如下：

1. 验证 Offline 数据下载、预处理、分片、Tokenize、产物合并及训练读取流程。
2. 验证 Online 数据通过 Hugging Face 在线下载、缓存或流式读取并接入训练。
3. 验证 Online plaintext 主流程；conversation 不纳入本期转测。
4. 验证 mapping、iterable 两类 Online Dataset。
5. 验证训练 YAML 中 Dataset、Tokenizer 和 DataTransform 等本期涉及的对外配置接口。
6. 验证非法配置能够返回明确异常，不出现静默降级或错误读取。

本期统一限制如下：

• Tokenizer 仅支持 Hugging Face Tokenizer，其他类型 Tokenizer 不纳入转测。
• Offline 同时验证默认不定长 document 流程和启用 pack_to_seq_len 的定长 packing 流程。
• Offline 和 Online Plaintext 数据均只验证单文本列 text。
• Offline 不验证 Conversation、ChatTemplate、多模态及预先 Tokenize 的输入。
• 动态选择最优 Worker 数不纳入转测。

2. Offline 数据集流程

2.1 功能范围

Offline 流程负责将 Hugging Face Dataset 或本地 JSON/JSONL 数据提前完成 Tokenize，生成
Megatron-compatible Indexed Dataset：

<output-prefix>_text_document.bin
<output-prefix>_text_document.idx

本期 Offline 转测范围如下：

• 支持从 Hugging Face Hub 在线下载公开数据集。
• 支持 Hugging Face Dataset 的 subset、split 和缓存复用。
• 支持本地 JSON、JSONL、JSON/JSONL gzip 压缩文件、目录及非递归 glob 输入。
• 支持将输入记录划分为多个 partition 并行处理。
• 支持合并多个 partition 产生的 .bin/.idx 文件。
• 输入格式仅支持单文本字段 text，CLI 统一使用 --json-keys text。
• Tokenizer 仅支持 Hugging Face Tokenizer ID 或本地 Hugging Face Tokenizer 目录。
• Offline 构建 Tokenizer 时会输出仅支持 Hugging Face AutoTokenizer 的 UserWarning，该提示不代表处理失败。
• 支持固定 Worker 数及 keep_sequential_samples。
• 支持在非空文档尾部追加 EOD。
• 支持通过 pack_to_seq_len 生成长度为 seq_len + 1 的定长 document，并丢弃每个 partition 最后的不足一条的残余样本。
• 支持处理完成后的 Indexed Dataset 被训练流程正常读取。

本期 Offline 不测试：

• 多文本字段；
• Conversation/ChatTemplate；
• NLTK 分句；
• 自定义特殊 Token；
• 动态 Worker 数选择；
• 递归目录和递归 glob；
• CSV、Parquet、Arrow 及多模态输入。

2.2 Offline CLI 对外接口

Offline 数据制备提供两个 CLI 入口：

1. Hugging Face 数据集入口：从 Hugging Face Hub 下载数据并转换为 Offline Indexed Dataset。
2. 本地数据集入口：读取本地 JSON/JSONL 文件、目录或 glob，并转换为 Offline Indexed Dataset。

两个入口最终进入统一的 Offline 预处理流程，完成数据分区、Tokenize、可选定长 packing、partition 产物合并及
.bin/.idx 文件生成。本期两个入口均验证默认不定长模式和 pack_to_seq_len 定长模式。

2.3 Hugging Face 数据集 CLI

命令入口：

python -m hyper_parallel.auto_models.components.datasets.tools.huggingface_offline

使用示例：

python -m hyper_parallel.auto_models.components.datasets.tools.huggingface_offline \
    --dataset Salesforce/wikitext \
    --dataset-subset wikitext-103-raw-v1 \
    --dataset-split train \
    --json-keys text \
    --output-prefix ./offline_datasets/wikitext/train \
    --tokenizer gpt2 \
    --workers 8 \
    --partitions 2 \
    --keep-sequential-samples \
    --append-eod true \
    --pack-to-seq-len 4096

处理流程：

Hugging Face Dataset
→ datasets.load_dataset()
→ 选择并校验 text 字段
→ 导出为本地规范化 JSONL
→ 划分 partition
→ 多 Worker Tokenize
→ 按 seq_len + 1 切分定长 document
→ 丢弃每个 partition 的最后一个不完整 document
→ 合并 partition 产物
→ 生成最终 .bin/.idx

2.3.1 Hugging Face CLI 参数

CLI 参数	必填	默认值	接口说明	本期转测要求
--dataset	是	无	Hugging Face Dataset ID	验证 Hugging Face Hub 公开数据集在线下载
--dataset-subset	否	None	Dataset 的 subset/config	验证目标数据集所需的 subset
--dataset-split	否	train	Dataset split	验证有效 split；无效 split 应明确报错
--revision	否	None	Dataset revision、tag、branch 或 commit SHA	不作为本期转测目标
--cache-dir	否	None	Hugging Face Dataset 缓存目录	验证首次下载和缓存复用
--data-dir	否	None	Dataset 仓库内部的数据子目录	不作为本期转测目标
--data-files	否	None	传递给 load_dataset() 的源文件	不作为本期转测目标
--num-proc	否	None	Hugging Face 数据准备阶段的进程数	不作为本期转测目标
--json-keys	否	text	需要读取和 Tokenize 的字段	仅验证单文本字段 text
--output-prefix	是	无	Offline 产物的输出前缀	验证生成 <prefix>_text_document.bin/.idx
--download-dir	否	自动生成	规范化 JSONL 的保存目录	验证目录及规范化 JSONL 生成
--tokenizer	是	无	Hugging Face Tokenizer ID 或本地目录	仅验证 Hugging Face Tokenizer
--tokenizer-use-fast	否	True	是否使用 Fast Tokenizer	使用模型默认配置，不单独转测
--trust-remote-code	否	False	是否允许执行 Tokenizer 仓库代码	仅在目标 Tokenizer 需要时开启，不单独转测
--append-eod	否	True	是否在非空文档末尾追加 EOS，必要时回退 SEP；使用 true 或 false	本期转测只验证开启eod
--workers	否	8	Tokenize 使用的 Worker 总数	验证固定 Worker 数
--partitions	否	1	并行处理分区数	验证单 partition 和多 partition
--keep-sequential-samples	否	False	是否按连续记录区间划分 partition	验证开启后的顺序保持
--pack-to-seq-len	否	None	定长 packing 的训练序列长度；输出 document 长度为该值加一	验证定长切分
--keep-partition-files	否	False	是否保留临时 JSON partition 文件	验证临时 JSON 的保留和清理；不影响 .bin/.idx 产物

2.4 本地数据集 CLI

命令入口：

python -m hyper_parallel.auto_models.components.datasets.tools.offline_preparation

使用示例：

python -m hyper_parallel.auto_models.components.datasets.tools.offline_preparation \
    --dataset-name-or-path ./dataset/train.jsonl \
    --json-keys text \
    --output-prefix ./offline_datasets/train \
    --tokenizer-name-or-path gpt2 \
    --workers 8 \
    --partitions 2 \
    --keep-sequential-samples \
    --append-eod true \
    --pack-to-seq-len 4096

处理流程：

本地 JSON/JSONL 文件、目录或非递归 glob
→ 解析并排序输入文件
→ 划分 partition
→ 多 Worker Tokenize
→ 按 seq_len + 1 切分定长 document
→ 丢弃每个 partition 的最后一个不完整 document
→ 合并 partition 产物
→ 生成最终 .bin/.idx

2.4.1 本地数据集 CLI 参数

CLI 参数	必填	默认值	接口说明	本期转测要求
--dataset-name-or-path	是	无	JSON/JSONL 文件、目录或非递归 glob	验证单文件、目录和 glob 多文件输入
--json-keys	否	text	从每条记录读取和 Tokenize 的字段	仅验证单文本字段 text
--output-prefix	是	无	Offline 产物的输出前缀	验证生成 <prefix>_text_document.bin/.idx
--tokenizer-name-or-path	是	无	Hugging Face Tokenizer ID 或本地目录	仅验证 Hugging Face Tokenizer
--tokenizer-use-fast	否	True	是否使用 Fast Tokenizer	使用模型默认配置，不单独转测
--trust-remote-code	否	False	是否允许执行 Tokenizer 仓库代码	仅在目标 Tokenizer 需要时开启，不单独转测
--chat-template	否	None	Tokenizer ChatTemplate	Offline 本期不配置、不转测
--add-special-tokens	否	None	增加额外特殊 Token	不作为本期转测目标
--split-sentences	否	False	Tokenize 前通过 NLTK 分句	不作为本期转测目标
--keep-newlines	否	False	分句时保留连续换行	不作为本期转测目标
--lang	否	english	NLTK Punkt 分句语言	不作为本期转测目标
--append-eod	否	True	是否在非空文档末尾追加 EOS，必要时回退 SEP；使用 true 或 false	本期转测只验证开启eod
--workers	否	8	Tokenize 使用的 Worker 总数	验证固定 Worker 数
--partitions	否	1	并行处理分区数	验证单 partition 和多 partition
--keep-sequential-samples	否	False	是否按连续记录区间划分 partition	验证开启后的顺序保持
--pack-to-seq-len	否	None	定长 packing 的训练序列长度；输出 document 长度为该值加一	验证定长切分
--keep-partition-files	否	False	是否保留临时 JSON partition 文件	验证临时 JSON 的保留和清理；不影响 .bin/.idx 产物
--log-interval	否	1000	处理进度日志间隔	不影响数据结果，本期不单独转测

2.4.2 本地多文件输入

本地入口不使用 --data-files。多个输入文件通过目录或非递归 glob 指定。

目录方式：

python -m hyper_parallel.auto_models.components.datasets.tools.offline_preparation \
    --dataset-name-or-path ./dataset/train \
    --json-keys text \
    --output-prefix ./offline_datasets/train \
    --tokenizer-name-or-path gpt2

glob 方式：

python -m hyper_parallel.auto_models.components.datasets.tools.offline_preparation \
    --dataset-name-or-path "./dataset/train-*.jsonl" \
    --json-keys text \
    --output-prefix ./offline_datasets/train \
    --tokenizer-name-or-path gpt2

转测要求：

• 支持 .json、.jsonl、.json.gz 和 .jsonl.gz。
• 目录只扫描当前层级，不递归扫描子目录。
• glob 不验证 ** 递归匹配。
• 匹配到的文件按路径排序后处理。
• 多文件记录无遗漏、无异常重复。
• 路径不存在或未匹配到有效文件时明确报错。
• 原始输入文件不能被修改或删除。

2.5 两个 Offline CLI 的接口差异

对比项	Hugging Face CLI	本地数据集 CLI
命令入口	huggingface_offline	offline_preparation
主要用途	从 Hugging Face 下载并转换数据	转换已有本地 JSON/JSONL 数据
输入参数	--dataset	--dataset-name-or-path
Tokenizer 参数	--tokenizer	--tokenizer-name-or-path
多文件方式	本期不验证 --data-files	目录或非递归 glob
Dataset subset/split	支持	不涉及
Hugging Face 缓存	支持 --cache-dir	不涉及 Dataset 下载缓存
规范化 JSONL	下载后生成规范化 JSONL	直接读取已有本地文件
Tokenize	仅支持 Hugging Face Tokenizer	仅支持 Hugging Face Tokenizer
多 partition	支持	支持
keep_sequential_samples	支持	支持
pack_to_seq_len	支持并转测	支持并转测
最终输出	.bin/.idx	.bin/.idx

2.6 Offline 单文本输入格式

本期 Offline 仅转测以下格式：

{"text": "This is the first document."}
{"text": "This is the second document."}

统一配置：

--json-keys text

转测要求：

• text 字段存在且为字符串时能够正常 Tokenize。
• 缺少 text 字段时明确报错。
• 空文本不会产生非法 Token 序列。
• 多文件、多 partition 场景下记录无遗漏、无异常重复。
• 最终产物为 <output-prefix>_text_document.bin/.idx。

多字段、嵌套对象、messages、prompt/response、多模态及预先 Tokenize 的输入不纳入转测。

2.7 多分片及顺序保持

Offline 多分片通过以下参数控制：

--partitions N
--workers M

约束如下：

workers % partitions == 0
workers_per_partition = workers / partitions

转测要求：

• 验证 partitions=1 和 partitions>1。
• workers、partitions 必须为正整数。
• Worker 数不能被 partition 数整除时返回 ValueError。
• 多 partition 产物能够正确合并为最终 .bin/.idx。
• 文档数、Token 数和样本顺序符合预期。
• 开启 --keep-sequential-samples 后，各 partition 获得连续记录区间。
• 最终合并产物的全局样本顺序与输入顺序一致。
• 原始输入文件不能被删除或修改。

动态 Worker 数选择及相关参数 --find-optimal-num-workers、--workers-to-check、
--max-documents 不作为本期转测目标。

2.8 pack_to_seq_len

本期验证 pack_to_seq_len=None 的默认不定长流程，以及显式配置序列长度后的定长 packing 流程。

例如：

--pack-to-seq-len 4096

启用后，处理语义如下：

1. chunk_size = pack_to_seq_len + 1，例如配置 4096 时，每个输出 document 长度为 4097。
2. 每个 partition 内的文档 Token 按输入顺序追加到连续 Token buffer。
3. Token buffer 中的完整 chunk 按 4097 个 Token 写入 Indexed Dataset。
4. 每个 partition 结束时，如果仍有非空且不足 4097 的 Token buffer，则直接丢弃。
5. 丢弃的残余 Token 不再通过 pad_token_id 或 eos_token_id 补齐写入。
6. pack_to_seq_len<=0 时返回 ValueError。
7. 启用 pack_to_seq_len 且设置 --append-eod false 时仍可生成产物，但代码会输出 UserWarning，提示原始文档边界不包含 EOD。

转测要求：

• 验证 pack_to_seq_len=None 时按原始不定长 document 写入。
• 验证 pack_to_seq_len=4096 时所有输出 document 长度均为 4097。
• 验证跨原始 document 的 Token 能够在同一 partition 内连续 packing。
• 验证每个 partition 的最后一个非空残余 buffer 均被丢弃，而不是补齐后写入。
• 验证非法序列长度及关闭 EOD 时的错误或 Warning 行为。
• 验证定长 .bin/.idx 产物能够被训练侧正常读取。

3. Online 数据集流程

3.1 功能范围

Online 流程在训练期间读取原始数据，并动态完成格式转换和 Tokenize。本期范围如下：

• Tokenizer 仅支持 Hugging Face Tokenizer。
• 支持 Hugging Face Hub 在线下载及缓存目录。
• 支持 mapping 和 iterable 两种 Dataset 类型。
• Plaintext 为重点转测格式，输入仅验证 text 列。
• Conversation 数据格式及 ChatTemplate 不纳入本期转测。
• 支持 Mapping 数据集首次下载、缓存生成和缓存复用。
• 支持 Iterable 数据集流式读取、Buffer Shuffle 及 DP 分片。
• 支持 DynamicBatchDataLoader 在 token budget 内动态选择 K 条样本并完成 Online packing。
• 验证 Online 数据能够进入 DataLoader 和基础训练流程。

非 Hugging Face Tokenizer、自定义 Tokenizer、多文本字段、复杂字段映射、多模态输入和私有数据集鉴权不纳入转测。

3.2 Online 统一 YAML 接口

当前 Mapping + 动态 batching 端到端实验从仓库根目录运行：

bash examples/training_demo/run_parallel_online.sh --training.train_iters=3

验收要求为至少完成 3 个训练 step，进程退出码为 0，日志无 ERROR 或 Traceback，loss 不为
NaN 或 Inf。

dataset:
  _target_: hyper_parallel.auto_models.components.datasets.llm.build_online_text_dataset
  data_path: null
  data_config:
    dataset_type: mapping
    hf_dataset_name: Salesforce/wikitext
    hf_config_name: wikitext-2-raw-v1
    cache_dir: ./dataset_cache

YAML 配置项	类型	默认值	说明
dataset._target_	str	无	hyper_parallel.auto_models.components.datasets.llm.build_online_text_dataset
dataset.data_path	str/list/null	None	本地文件、目录或文件列表
data_config.dataset_type	str	mapping	支持 mapping、iterable
data_config.hf_dataset_name	str/null	None	Hugging Face Dataset ID
data_config.hf_config_name	str/null	None	Hugging Face Dataset subset/config
data_config.cache_dir	str/null	None	Hugging Face 缓存目录
data_config.shuffle	bool	True	Iterable 是否启用 Buffer Shuffle
data_config.shuffle_buffer_size	int	10000	Iterable Shuffle Buffer 大小
data_config.split_by_data_parallel	bool	True	Iterable 是否按照 DP Rank 分片

当 hf_dataset_name 和 data_path 同时配置时，优先使用 hf_dataset_name。当前 Online 数据固定读取
train split；Iterable Shuffle 使用 training.seed。

3.3 Plaintext 流程

输入格式：

{"text": "This is an online training sample."}

dataset:
  model_assets:
    chat_template: null
    tokenizer:
      _target_: hyper_parallel.auto_models.components.datasets.llm.build_tokenizer.AutoTokenizer.from_pretrained
      pretrained_model_name_or_path: ./qwen3-model
      use_fast: true

  data_transform:
    _target_: hyper_parallel.auto_models.components.datasets.llm.build_data_transform.build_llm_data_transform
    data_type: plaintext
    text_keys: text
    max_seq_len: 2048

  _target_: hyper_parallel.auto_models.components.datasets.llm.build_online_text_dataset
  data_path: null
  data_config:
    dataset_type: mapping
    hf_dataset_name: Salesforce/wikitext
    hf_config_name: wikitext-2-raw-v1
    cache_dir: ./dataset_cache

dataloader:
  _target_: hyper_parallel.auto_models.components.datasets.DynamicBatchDataLoader
  min_buffered_samples: 200

  collate_fn:
    _target_: hyper_parallel.auto_models.components.datasets.build_online_text_collate_fn

  get_batch:
    _target_: hyper_parallel.auto_models.components.datasets.ParallelBatch
    source_type: online
    attention_mode: dense

转测要求：

• text_keys=text 能够正确读取文本列。
• 使用模型对应的 Hugging Face Tokenizer 完成 Tokenize。
• transform 输出 input_ids 和相同内容的 labels，causal label shift 由模型完成。
• 输出长度不超过 max_seq_len。
• DataLoader 在 token budget 内动态选择 K 条样本，packing 后由 ParallelBatch 构建训练字段。
• Mapping 和 Iterable 均能使用 Plaintext transform。

3.4 Conversation 流程

Online 代码支持 conversation 数据格式及 ChatTemplate 转换，但本期不进行 Conversation 转测，包括：

• messages 字段输入；
• Qwen3 ChatML 模板；
• 多轮对话及 Role 组合；
• Tool Calling；
• loss_mask 和 Label Mask；
• Conversation 的 Mapping/Iterable 数据加载；
• Conversation 的 DataLoader 及训练跑通。

3.5 Mapping Dataset

Mapping 模式使用 load_dataset(streaming=False)。

转测要求：

• 支持 len(dataset) 和 dataset[index]。
• 首次运行从 Hugging Face 下载并生成缓存。
• 再次运行能够复用已有缓存。
• 两次读取的数据条数和内容一致。
• 自定义 cache_dir 生效。
• hf_config_name 选择结果正确。
• 数据能够进入 DataLoader 和基础训练流程。

3.6 Iterable Dataset

Iterable 模式使用 load_dataset(streaming=True)，随后执行可选 Buffer Shuffle 和 DP 分片。

转测要求：

• 能够通过迭代方式持续产生样本。
• shuffle=true 时启用 Buffer Shuffle。
• 相同 Seed 和配置下顺序可复现。
• shuffle_buffer_size<=0 时返回 ValueError。
• split_by_data_parallel=true 时，各 DP Rank 获取对应数据分片。
• 数据能够进入 DataLoader 和基础训练流程。

Iterable 模式不要求完整数据集预先下载到本地缓存，也不验证随机索引和 len()。

4. YAML 接口一致性要求

4.1 Plaintext

• dataset._target_=hyper_parallel.auto_models.components.datasets.llm.build_online_text_dataset。
• dataset.data_transform.data_type=plaintext。
• dataset.model_assets.chat_template=null。
• dataset.model_assets.tokenizer 必须配置 Hugging Face Tokenizer。
• dataloader.collate_fn 使用 build_online_text_collate_fn。
• dataloader.get_batch.source_type=online。
• 原始数据必须包含 text 字段。

4.2 Conversation

Conversation 相关 YAML 配置一致性不纳入本期转测。

4.3 Offline Pretokenized

• model_assets.datasets_type=pretokenized。
• data_transform.data_type=pretokenized。
• data_config.source_type=offline。
• 必须提供 data_path。
• 不得再次对 input_ids 执行文本 Tokenize。

5. 非本期转测范围

• 非 Hugging Face Tokenizer。
• Offline 多文本字段、Conversation、ChatTemplate 和多模态输入。
• Offline NLTK 分句和自定义特殊 Token。
• 动态 Worker 数选择、性能基准和自动调优。
• 递归目录扫描和递归 glob。
• Offline CSV、Parquet 和 Arrow 输入。
• 对象存储或远程 Indexed Dataset 读取。
• Online 多文本字段及复杂字段映射。
• Online Conversation 数据格式及全部 ChatTemplate 能力。
• Conversation 的 messages、多轮对话、Role、Tool Calling、Label Mask、DataLoader 和训练接入。
• Hugging Face 私有数据集鉴权。
• 数据下载服务的性能、稳定性和大规模长稳测试。

6. 转测验收标准

1. Offline 能够从 Hugging Face 下载公开数据，并转换为可读取的 .bin/.idx。
2. Offline 能够读取本地单文件、目录和非递归 glob 匹配的多文件。
3. Offline 仅使用 Hugging Face Tokenizer，并正确处理单文本字段 text。
4. Offline 默认模式能够按原始不定长 document 生成产物。
5. pack_to_seq_len=N 时，每个输出 document 长度均为 N+1，每个 partition 最后的不足一条的残余样本被丢弃。
6. Offline 多文件和多 partition 处理无数据遗漏、异常重复或错误合并。
7. keep_sequential_samples=true 时，最终数据顺序与原始记录顺序一致。
8. Offline 不定长及定长产物均能够通过 build_indexed_text_dataset 接入训练。
9. Online Mapping 能够完成 Hugging Face 首次下载、缓存生成及缓存复用。
10. Online Iterable 能够完成流式读取、Buffer Shuffle 和 DP 分片。
11. Online Plaintext 能够读取 text 字段并使用 Hugging Face Tokenizer 动态编码。
12. Mapping 和 Iterable 均能够完成 Plaintext DataLoader 迭代，并至少完成 3 个训练 step。
13. YAML 中 Dataset target、data_type、dataset_type、DataLoader source_type 和 Tokenizer 配置关系正确。
14. 本期覆盖的必填项缺失、非法枚举值和非法数值能够返回明确异常。
15. Offline 和 Online Plaintext 均能完成至少一个端到端训练用例，退出码为 0 且 loss 正常。