处理好的训练数据怎么离线复用？用 Datasets 保存、重载并核对结构

用 Datasets 处理完训练数据后，可通过 save_to_disk() 保存整个 DatasetDict，再用 load_from_disk() 恢复划分、样本和字段定义。保存成功之后还要在新进程核对数据，才能确认后续离线运行用的是期望版本。

保存目录与普通 JSON 文件的区别

官方处理文档介绍 save_to_disk()/load_from_disk() 配对使用；接口参考说明保存数据集字典会保留各个 split，load_from_disk() 返回 Dataset 或 DatasetDict。它读取的是该接口产生的目录，不是任意 CSV、JSONL 或一个手工拼出的 Arrow 文件。

示例于 2026-10-01 在 Windows、Python 3.11.15、Datasets 4.8.3 环境实际执行通过；数据全部人为构造，只验证数据处理接口，没有训练模型或测量业务效果。安装可参考 Datasets 官方安装说明。先在新的练习目录建立环境：

python -m venv .venv
# Windows 使用 .venv\Scripts\python.exe；macOS/Linux 使用 .venv/bin/python
.venv\Scripts\python.exe -m pip install "datasets==4.8.3"

下文运行命令按 Windows 写法给出。使用 macOS 或 Linux 时，把解释器路径换为 .venv/bin/python；后续版本请先用同一份玩具数据复核，再替换生产数据。

示例只包含本地文本和整数标签。需要先安装好依赖，把完整保存目录复制到离线机器，并核对环境；“数据已保存”不会自动打包 Python 包、模型权重或远程音视频文件。

第一步：保存数据与处理记录

在新练习目录保存为 save_demo.py，运行 .venv\Scripts\python.exe save_demo.py。本例用明确指定的三个训练样本与一个验证样本演示持久化，不用这个微型划分估计模型质量。

import json
from pathlib import Path
from datasets import Dataset, DatasetDict, ClassLabel

ds = Dataset.from_list([
    {'id': 1, 'text': '样本甲', 'label': 0},
    {'id': 2, 'text': '样本乙', 'label': 1},
    {'id': 3, 'text': '样本丙', 'label': 0},
    {'id': 4, 'text': '样本丁', 'label': 1},
]).cast_column('label', ClassLabel(names=['negative', 'positive']))
parts = DatasetDict({
    'train': ds.select([0, 1, 2]),
    'validation': ds.select([3]),
})
target = Path('processed-demo-v1')
if target.exists():
    raise FileExistsError('请使用新目录，避免覆盖已有数据')
parts.save_to_disk(str(target))
record = {
    'source': '本教程自建虚构样本',
    'datasets_version': '4.8.3',
    'label_names': ['negative', 'positive'],
    'expected_ids': {'train': [1, 2, 3], 'validation': [4]},
}
(target / 'processing-record.json').write_text(
    json.dumps(record, ensure_ascii=False, indent=2), encoding='utf-8'
)
print('saved:', target.resolve())

processing-record.json 是本例自行写入的处理记录，不能假定 Datasets 会自动替你记录真实源文件、清洗规则或许可。生产记录还应补上源文件摘要、处理脚本版本、标签定义和数据使用限制。

第二步：在新进程重载并核对

将以下代码另存为 load_demo.py，关闭刚才的进程后执行 .venv\Scripts\python.exe load_demo.py。路径按当前工作目录解析；换电脑时使用完整的已复制目录路径。

import json
from pathlib import Path
from datasets import load_from_disk, DatasetDict, ClassLabel

target = Path('processed-demo-v1')
record = json.loads((target / 'processing-record.json').read_text(encoding='utf-8'))
restored = load_from_disk(str(target), keep_in_memory=False)
assert isinstance(restored, DatasetDict)
assert set(restored) == {'train', 'validation'}
for name, ids in record['expected_ids'].items():
    part = restored[name]
    assert list(part['id']) == ids
    assert part.column_names == ['id', 'text', 'label']
    assert isinstance(part.features['label'], ClassLabel)
    assert part.features['label'].names == record['label_names']
    print(name, len(part), part[0])
assert restored['train'][0]['text'] == '样本甲'
print('splits, IDs, text and ClassLabel: passed')

在实际执行中，训练部分恢复 3 条、首条是 id=1 且 text 为“样本甲”；验证部分恢复 1 条、首条是 id=4 且 text 为“样本丁”。断言检查两个 split、完整 ID 顺序、列名和 ClassLabel 名称均符合处理记录。

这两段程序在 Hub 离线模式下执行通过，且第二段使用独立 Python 进程。没有做物理断网或跨电脑迁移测试；离线可用性仍以全部依赖和本地文件已到位为前提。

复制到其他机器时如何检查

1. 复制整个 processed-demo-v1 目录，包含各 split 子目录、数据分片和元数据；不要只挑一个 .arrow 文件。
2. 记录并核对复制前后各文件的摘要或使用可靠传输校验；处理记录可用来核对业务预期，但不是文件完整性的签名。
3. 在目标机器执行重载程序，核对行数、列类型、标签名称和几个指定 ID 的内容。
4. 正式训练前固定数据路径与版本名，避免同一个目录被后台处理覆盖。

keep_in_memory=False 表示不要求把数据集复制进内存，不代表后续读取、批处理或训练不耗内存。程序里的 FileExistsError 是保护已有保存目录；换新版本目录后再保存。

问答：什么时候导出 JSONL 或 Parquet？

要给别的系统使用时，可以选择 to_json() 或 to_parquet()；要快速恢复 Datasets 的结构化处理结果，可优先 save_to_disk()。普通导出文件不自动保留整个 DatasetDict 的 split 结构及 ClassLabel 名称映射，需另存这些信息。官方处理文档还指出 Arrow 较适合磁盘处理与缓存，长期归档和跨工具传输可考虑 Parquet；无论选哪种格式，都要核对恢复结果。

若出现路径不存在、缺失 state 文件或字段类型不符，先检查目录是否复制完整、是否把普通导出误当成 save_to_disk 目录，以及使用的版本；不要跳过断言继续训练。