Hugging Face Datasets 怎样随本地数据保存描述与引用信息

给数据集创建或补充 DatasetInfo，把描述写入 description、引用写入 citation，然后对这个 Dataset 调用 save_to_disk，即可把说明与本地数据快照一起保存。接收方应使用 load_from_disk 加载整个目录，而不是只复制一个 Arrow 文件。只想另存说明时，再用 ds.info.write_to_directory。

我更愿意把描述当成交接内容的一部分：一份文本列告诉接收者“有哪些句子”，说明则告诉他“这些句子为什么被整理在一起”。下面用完全虚构的短文本构造一个最小例子，不下载外部语料，也不把示例引用冒充真实论文。

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

准备一份不会混入外部来源的演示数据

示例需要 Python 环境已经安装 datasets。在自己的项目中应记录实际依赖版本，接收方也使用项目约定的环境。这里不指定未经必要性判断的版本号，也不宣称跨版本格式永久兼容。

使用相对目录 handoff-demo/snapshot 保存数据快照，另建 metadata-only 保存说明副本。两个目录用途不同，不要把它们当作两份完整数据。

把描述和引用绑定到同一个 Dataset

Dataset 关联实际的 Arrow 行数据；DatasetInfo 记录说明与列结构。下面显式声明 text 文本列，避免把项目说明误当成每一行都重复出现的数据字段。描述应写清整理目的、来源范围及局限；引用需要使用真实来源提供的文本，本例只填写一个标明演示性质的 BibTeX 条目。

from pathlib import Path
from datasets import Dataset, DatasetInfo, Features, Value

root = Path("handoff-demo")
root.mkdir(exist_ok=True)
snapshot = root / "snapshot"

# 两条人工编写的演示句子，不是从第三方语料摘取的数据。
rows = {"text": ["清晨的风掠过空地。", "纸张上的线条逐渐清晰。"]}
features = Features({"text": Value("string")})

# 引用明确标为演示条目，实际项目应换成真实来源的引用信息。
info = DatasetInfo(
    description="两条人工合成的教程演示文本，不代表真实训练语料。",
    citation="""@misc{tutorial_demo_text,
  title = {Synthetic Text for a Dataset Handoff Example},
  note = {Fictional tutorial entry, not a published research paper}
}""",
    features=features,
)
ds = Dataset.from_dict(rows, features=features, info=info)

# 使用独立快照目录，防止把本例与其他交付目录混在一起。
if snapshot.exists():
    raise FileExistsError("快照目录已存在，请另选目录名")
ds.save_to_disk(str(snapshot))

这个示例的关键是先把 info 传入构造器，再保存持有它的 ds。如果只是新建了一个游离的 DatasetInfo 变量，却仍保存另一个数据集对象，说明不会因为变量名相似而自动关联。

读取快照时，从加载对象取得说明

接收方拿到完整 snapshot 目录后，用配套 API 加载，再读取 restored.info。以下片段是给读者的使用示例，本文没有在本机执行，也没有采集输出截图。

from datasets import load_from_disk

# 这里加载完整快照目录，不能改成目录中的单个数据文件。
restored = load_from_disk("handoff-demo/snapshot")
print(restored.info.description)
print(restored.info.citation)

# 行数据仍通过 Dataset 访问，说明不需要拼接进每条记录。
print(restored[0]["text"])

按示例构造的内容，描述应说明人工合成文本，引用应保留虚构演示标记，首行文本则仍是第一条句子。如果在业务代码中重新构造了 Dataset，例如把若干列提取成普通字典后另建对象，应同时考虑是否继续传递原有说明，不能仅凭列名一致就认定说明仍然相同。

完整目录交接与单独导出说明怎样选择

完整快照需要数据文件、dataset_info.json 等配套文件及保存时的状态信息。不要只挑一个看起来最大的 Arrow 文件发送，也不要手工删掉不认识的小文件。API 的目录布局应由库管理，交接时保留其整体结构。

如果审阅者暂时只需要描述与引用，而不需要数据行，可以另外导出说明。这个副本便于阅读，但并不是可恢复训练数据的备份。

from pathlib import Path
from datasets import DatasetInfo

metadata_dir = Path("handoff-demo/metadata-only")
metadata_dir.mkdir(exist_ok=True)

# ds 来自前面的构造示例；这里仅导出说明，不保存数据行。
ds.info.write_to_directory(str(metadata_dir), pretty_print=True)

# 读取的是 DatasetInfo，不是完整 Dataset。
metadata = DatasetInfo.from_directory(str(metadata_dir))
print(metadata.description)
print(metadata.citation)

后续修改说明时，保留清楚的交付版本

对我来说，最容易忽略的是“磁盘上那份”和“内存里这份”不是同一时刻的状态。修改 ds.info.description 或 ds.info.citation 后，应把带有新说明的对象保存为新的交付快照，再告知接收方使用哪份目录。只修改内存对象，不会自动改写已经发送的目录。

README 可以补充预处理流程、负责人及业务限制，但不应与 DatasetInfo 的描述相互矛盾。引用只说明来源，并不自动授予使用许可；原始数据的授权材料与实际处理约定仍应随项目保留。示例没有替任何外部数据声明许可。

只导出 JSONL 或 CSV，说明会自动跟过去吗？

不要把表格导出当成 Dataset 快照。若接收方必须使用这类格式，可以另附说明文件和 README，并明确它们与哪份数据对应。

为什么单独的 metadata-only 目录不能加载成数据集？

它只由说明导出接口生成，没有完整数据快照的行数据及状态。要恢复数据，应使用前面完整保存的 snapshot 目录。

修改描述需要重新下载原始语料吗？

本地已经有可加载的快照时，可以加载后修改说明并另存。是否需要重新取得原始数据，取决于数据内容是否也发生变化，而不是描述字段本身。