Hugging Face Datasets save_to_disk 怎样在离线环境恢复数据集

如果训练机不能访问网络，但数据已经在另一台机器上整理好，最稳妥的做法是把 Dataset 或 DatasetDict 保存成一个完整目录，再把这个目录搬到离线环境，用 load_from_disk() 恢复。它和 Hub 缓存不是一回事：这里搬运的是由 save_to_disk() 生成的数据集目录。

官方地址：https://huggingface.co/docs/datasets/en/package_reference/main_classes

下面按“能加载、加载错、加载慢”三种现象排查，示例只使用演示数据，不代表已经在当前机器执行。

先确认保存对象和目录边界

Dataset.from_dict() 或 Dataset.from_pandas() 得到的对象可能只存在于内存中。save_to_disk() 会把它写成可恢复的数据集目录；load_from_disk() 只负责读取这个目录，不会替你从 Hub 重新下载。

保存单个 Dataset 或多个 split

单个数据集直接保存到目录，多 split 数据集则保存 DatasetDict。目录名应该是一个明确的搬运单元，不要把它和默认缓存目录混用。

from datasets import Dataset, DatasetDict, load_from_disk

rows = {"text": ["第一条", "第二条"], "label": [0, 1]}
ds = Dataset.from_dict(rows)

# 把内存对象写成独立目录，目录整体才是离线搬运单元。
ds.save_to_disk("artifacts/demo_dataset")

splits = DatasetDict({"train": ds, "validation": ds.select([0])})
# 大数据集可用 max_shard_size 控制单个 Arrow 分片的上限。
splits.save_to_disk("artifacts/demo_splits", max_shard_size="1GB")

# 离线机器只读取已保存目录，不把它当作 Hub 数据集名称。
restored = load_from_disk("artifacts/demo_splits")
print(type(restored).__name__, list(restored.keys()))  # 预期是 DatasetDict 和 split 名称

官方接口允许用 max_shard_size 或 num_shards 控制分片；多 split 的 num_shards 需要按 split 提供数量。数据量不大时可以先使用默认设置，避免把分片数量当成恢复条件。

出现加载失败时，按四层证据排查

1. 路径层：传给 load_from_disk() 的必须是保存目录，不能只指向其中一个 Arrow 文件，也不能把 Hub 名称当成本地路径。
2. 完整性层：搬运时复制整个目录及其元数据和分片；只复制一个 .arrow 文件会让目录结构不完整。
3. 对象层：单目录可能恢复为 Dataset，包含 split 的目录恢复为 DatasetDict。先打印类型，再决定用 restored["train"] 还是直接取列。
4. 内存层：keep_in_memory=True 会把数据复制到内存，适合小数据集临时读取；离线大数据集通常保留默认值，避免刚加载就产生额外内存压力。

离线迁移时的最小清单

先在有网环境完成数据整理和 save_to_disk()，再将保存目录作为一个整体打包。离线机器解包后传入本地绝对路径或稳定的项目相对路径，并先确认返回类型和 split 名称。需要继续训练时，再根据训练框架决定是否调用 with_format("torch")；不要因为能读取就误以为数据已经变成张量。

最常见的误区有三个：把缓存目录当成导出物、只复制 Arrow 分片、把 DatasetDict 当成单个样本表。按上面的四层证据判断，通常能在路径和目录阶段定位问题。

常见问题

save_to_disk 保存后还需要联网吗？

读取已保存目录本身不需要 Hub 网络请求；前提是目录、元数据和分片都已经完整搬运，且代码没有另行调用远程加载接口。

为什么恢复后不是 Dataset？

如果保存的是包含多个 split 的 DatasetDict，恢复结果就是 DatasetDict。先查看 split 名称，再选择 restored["train"] 等具体数据集。