手把手教你用 Python 从 Hugging Face 构建自己的数据集元数据

1 阅读

手把手教你用 Python 从 Hugging Face 构建自己的数据集元数据

你有没有想过，那些在 Hugging Face Hub 上琳琅满目的数据集，它们本身的信息能不能被整理成一个新的数据集？答案是肯定的。这篇文章就带你一步步实现这个想法，不靠花哨的库，只用 Python 自带的工具，从零开始构建一个关于“数据集的数据集”。

为什么要收集数据集的元数据？

我们最终得到的数据集，每一行都描述了 Hugging Face Hub 上的一个公开数据集仓库。它包含的信息就像你在网页上看到的那样：仓库名、下载次数、点赞数、标签（tags）、支持的语言、文件格式等等。这些信息统称为元数据——描述数据的数据。

通过收集和分析这些元数据，我们可以回答一些有趣的问题：

  • 哪些任务类型（如文本分类、机器翻译）的数据集最受欢迎？
  • Parquet 和 CSV 哪种格式更常用？
  • 英语数据集是否真的占据了绝对主流？

更重要的是，这个过程本身就是一次完整的数据工程实践：从数据采集、清洗、验证到存储和探索，一应俱全。

第一步：让脚本跑起来

准备工作非常简单：

  1. 确保你的电脑安装了 Python 3.10 或更高版本。
  2. 创建一个新文件夹作为项目目录。
  3. 将文末提供的完整脚本保存为 build_dataset.py。
  4. 在该目录下打开终端，运行命令：
python build_dataset.py

脚本会自动执行四个步骤：收集、保存、检查和处理。完成后，你会在项目目录下看到一个名为 dataset_output 的文件夹，里面包含本次运行的所有成果。每次运行都会生成一个独立的时间戳命名的子文件夹，确保数据不会被覆盖。

第二步：向 Hugging Face 请求信息

脚本的核心是调用 Hugging Face Hub 的公开 API。它会发送一个请求，要求获取过去 30 天内下载量最高的最多 1000 个数据集的元数据。

请求中指定了几个关键参数：

  • sort: "downloads"：按下载量排序。
  • direction: -1：从高到低。
  • limit: 1000：最多返回 1000 条结果。
  • expand: ["downloads", "likes", "tags", "citation", "sha"]：明确要求返回哪些字段的详细信息。

这里有个重要细节：脚本只请求一页数据。Hub 上的数据远不止 1000 条，要获取全部数据需要处理“分页”（pagination），这会让脚本复杂不少。为了清晰地展示每个步骤，我们先聚焦于单页请求。

如果遇到网络问题或服务器繁忙，脚本会自动重试最多三次。如果是请求过于频繁（HTTP 429 错误），它会读取服务器返回的等待时间，并提示你稍后再试。

第三步：保存原始响应

在对数据做任何改动之前，脚本会先把 API 返回的原始 JSON 数据一字不差地保存下来，放在 RAWDATA/response.json 文件里。

这是一个至关重要的好习惯。想象一下，如果你在处理后的数据里发现了一个奇怪的值，你可以随时回到这个原始文件里核对，看看是 API 本身就返回了异常数据，还是你的处理逻辑出了问题。原始数据就是你的“真相来源”。

同时，脚本还会保存一个 collection.json 文件，记录下本次请求的具体参数、执行时间和脚本版本，确保整个过程是可追溯、可复现的。

第四步：处理数据意味着什么？

“处理”在这里指的是将原始、杂乱的 API 响应，整理成结构清晰、易于分析的格式。

Hugging Face 的 tags 字段是一个字符串列表，内容像这样：

["task_categories:text-classification", "language:en", "format:parquet"]

直接使用这个列表做分析很麻烦。所以，脚本会遍历这些标签，把有用的信息提取出来，放到专门的字段里：

  • task_categories: ["text-classification"]
  • languages: ["en"]
  • formats: ["parquet"]

这样一来，我们就可以轻松地统计有多少数据集是用于文本分类的，或者有多少是英文的，而不用每次都去解析那个混合的标签列表。

现实世界的数据总是不完美的

在处理真实数据时，你很快会发现一个事实：很多字段是缺失的。

比如，在某次运行中，1000 条记录里有 369 条没有 format 标签，987 条没有返回 citation（引用信息）。这并不意味着这些数据集没有文件格式或引用信息，只是这次 API 调用没有提供。

脚本会诚实地保留这些缺失值，在 JSON 中用 null 表示。对于像 formats 这样的列表字段，如果没有匹配的标签，则会是一个空列表 []。

学会接受并正确处理缺失值，而不是武断地用 0 或其他默认值填充，是数据工作中一项非常重要的技能。它能让你的分析结论更加严谨可靠。

第五步：在完成前先检查一遍

脚本在保存最终结果前会进行一系列检查，确保数据的基本质量：

  • 检查是否有重复的数据集 ID。
  • 验证下载量和点赞数是否为非负整数。
  • 确认标签列表的格式是否符合预期。

最关键的一步是：脚本会把刚刚写入磁盘的 datasets.jsonl 文件重新读取一遍，并与内存中的原始记录进行比对。如果两者不一致，说明在保存过程中可能出现了问题，脚本会立即报错。这个简单的“回环测试”能有效防止因文件写入错误而导致后续分析出错。

第六步：选择合适的存储格式

脚本采用了两种互补的格式来存储结果：

  • 主数据集 (datasets.jsonl)：采用 JSONL (JSON Lines) 格式。这种格式每行一个独立的 JSON 对象，非常适合存储包含嵌套列表（如多种语言、多个任务）的记录。你可以用任何文本编辑器打开它，也可以用 Python 轻松逐行读取。

  • 分析报告 (*.csv)：所有统计报告，如任务类别计数、语言分布、格式统计等，都保存为 CSV 文件。这种格式可以直接用 Excel、Google Sheets 或任何数据分析工具打开，方便进行排序、筛选和可视化。

此外，脚本还会生成一个详尽的 README.md 文件，解释了每个字段的含义、数据收集方法和已知的局限性，以及一个包含所有统计摘要的 summary.json 文件。这些文档能让你在几个月后回看这个项目时，依然能快速理解它的来龙去脉。

第七步：看看结果，但要保持清醒

脚本运行结束后，会在终端打印一份详细的洞察报告，告诉你哪些数据集最近最火，哪些任务和格式最常见。

然而，解读这些结果时必须格外小心。报告里有两个关键提醒：

  1. 下载量 ≠ 质量分数：下载量高只能说明很多人下载了它，但无法证明这个数据集质量好、标注准或者适合你的任务。它甚至不是独立用户的数量，因为一次批量下载也会被计为一次。

  2. 我们的样本是有偏的：我们只收集了“过去 30 天下载量最高的 1000 个”数据集。这意味着我们的结论只能描述这个特定群体的特征，而不能代表整个 Hugging Face Hub。例如，你可以说“在我们的样本中，21.5% 的数据集带有 format:parquet 标签”，但绝不能说“所有人都在用 Parquet”。

认识到数据的来源和局限性，是避免得出错误结论的关键。

接下来可以做什么？

现在，你已经拥有了一个结构良好、自带文档的小型数据集。你可以用它来做很多事情：

  • 构建一个简易的数据集查找器：根据任务、语言或格式快速筛选。
  • 制作一个仪表盘：动态展示你收集到的统计数据。
  • 撰写一份元数据完整性报告：分析哪些字段经常缺失，为未来的数据收集提供建议。
  • 进行时间序列比较：过一段时间再运行一次脚本，比较两次快照的异同，观察趋势变化。

一个更深入的方向是数据增强（enrichment）。例如，脚本虽然保存了 citation 字段，但并未处理其中的 DOI（数字对象标识符）。你可以手动或通过另一个脚本，为部分数据集补充经过验证的 DOI 信息，并通过 dataset_id 将其关联起来，从而为你的数据集增加新的维度。

总之，从提出问题、收集数据、处理验证到最终分析，你已经完成了一次完整的数据项目闭环。而这，仅仅是个开始。