Datasets 数据集卡片Dataset Card编写指南从模板到 YAML 元数据驱动加载【免费下载链接】datasets The largest hub of ready-to-use datasets for AI models with fast, easy-to-use and efficient data manipulation tools项目地址: https://gitcode.com/gh_mirrors/da/datasets导读数据集卡片Dataset Card是 Hugging Face Datasets 生态中每个数据集必备的说明文档它以仓库根目录下的README.md为载体向使用者交代数据集的来源、结构、用途、偏见与局限性从而推动负责任地使用数据。本篇指南以当前仓库中的 数据集卡片模板 与配套的 Dataset Card 编写指南 为骨架逐节讲解每个字段的写作要点并结合本仓库源码深入剖析卡片顶部 YAML 元数据如何被 load.py 与 metadata.py 解析为数据集的分片splits与配置configs让读者既能写出一份专业完整的数据集卡片也能理解卡片元数据与底层加载机制的对应关系。为什么每个数据集都需要一张数据集卡片数据集卡片的理念源于 Mitchell 等人 2018 年提出的 Model Cards 思想并迁移到了数据集领域每份数据集都应配套一张卡片用于促进负责任的使用、告知使用者数据中可能存在的偏见。卡片让用户了解数据集的内容、使用背景、创建过程以及使用前应当注意的各种事项。在 Hugging Face Datasets 的实践中创建卡片非常简单官方流程如下在 Hub 上新建一个数据集仓库点击Create Dataset Card在仓库中生成一个README.md文件使用Metadata UI选择描述数据集的标签license、language、pretty_name、task_categories、size_categories 等这些标签帮助用户在 Hub 上检索到你的数据集点击Import dataset card template自动生成包含所有相关字段的模板逐节填写无法完成的部分写上[More Information Needed]提交更改后完整的数据集卡片就会显示在数据集仓库页面上。本仓库的 模板文件 正是上述流程第 3 步使用的标准模板而 编写指南 则对模板中的每一节给出了详细到该写什么、怎么写的说明。完整的创建步骤可参考 创建数据集卡片指南。模板的整体骨架五大分区与目录templates/README.md在文件头部的 YAML 块Front Matter之后先给出一个完整的 Table of Contents然后按五个大区组织内容Dataset Description数据集是什么、支持什么任务、包含什么语言Dataset Structure数据实例长什么样、有哪些字段、如何划分 splitDataset Creation数据集如何被创建、数据来源、标注过程、隐私信息Considerations for Using the Data社会影响、偏见讨论、已知局限Additional Information策展人、许可证、引用信息、贡献者。模板中每一节的占位符默认是[More Information Needed]编写者应尽量用真实内容替换确实无法填写的信息可以保留该占位符这既诚实又便于社区协作补全。卡片的头部信息区Dataset Description模板开头的元信息列表是整个卡片的名片包含五个可选条目Homepage数据集主页 URL若主页本身就是 GitHub 仓库则留空此项Repository如果数据集托管在 GitHub 或有 GitHub 主页填写仓库地址Paper若数据集由论文提出或有描述数据集的论文填写论文链接优先使用 Arxiv 落地页Leaderboard若数据集支持活跃的排行榜填写排行榜链接Point of Contact至少一位可联系的数据集负责人姓名与邮箱。Dataset Summary用几句话概括数据集本身、预期用途和支持的任务说明它为何被创建、如何被创建。摘要应明确提及数据集中包含的语言可以宽泛例如若干欧洲语言对的互译文本并描述数据所覆盖的领域、主题或体裁。Supported Tasks and Leaderboards对于该数据集打标的每一个任务给出任务的简要描述、评估指标以及建议使用的模型。对于未被结构化标签集覆盖的任务用other:other-task-name形式的标签补充描述。指南给出了一个标准句式可据此组织内容task-category-tag该数据集可用于训练 [TASK NAME] 模型任务内容是 [TASK DESCRIPTION]。该任务的成功通常通过达到高/低[metric name] 来衡量。模型名/模型类模型目前取得了如下成绩。若存在排行榜该任务有活跃排行榜位于 [leaderboard url]依据 [metric name] 对模型排名并同时报告 [other metric name]。Languages概述数据集中包含的语言并说明语言的具体特征例如是否为社交媒体文本、是否为非裔美国人英语等。当相关时应提供 [BCP-47] 语言代码即由主语言子标签primary language subtag、可选文字子标签script subtag和可选地区子标签region subtag构成的规范代码。数据结构区Dataset StructureData Instances给出一个 JSON 格式的典型数据实例示例并简要描述。模板给出了如下骨架{ example_field: ..., ... }此外还应在这一节描述数据点之间可能存在的关系以及这些关系是否被显式表达。如果存在更多示例可提供链接。Data Fields列出并描述数据集中存在的字段说明它们的数据类型以及在当前支持的任务中它们是输入还是输出。若数据包含 span 索引要描述其属性例如是基于字符级还是词级、是否连续等。若数据集包含 example ID需要说明其是否具有内在含义例如是否映射到其他数据集或指向数据点之间的关系。字段描述格式如下example_field对example_field的描述指南提示字段描述可以直接初始化自 Datasets Tagging 应用的Show Markdown Data Fields输出之后只需润色生成的描述。Data Splits当数据集包含多个 split 时描述并命名它们。说明拆分数据的标准例如训练集的标注由机器生成、开发集与测试集由人工生成或各示例的标注人数不同。同时给出每个 split 的规模并尽可能提供特征的描述性统计例如平均长度。指南给出了一个三列统计表的范式train / validation / test可用于填写输入句子数、平均句子长度等指标。数据集创建过程区Dataset CreationCuration Rationale回答什么需求催生了这个数据集以及在组装数据的过程中哪些主要决策背后的理由是什么。这是向使用者交代数据集设计意图的核心段落。Source Data描述源数据例如新闻文本与标题、社交媒体帖子、翻译句子等并进一步分为两个子节Initial Data Collection and Normalization描述数据收集过程、数据筛选标准、使用的关键词或搜索词以及可行的收集过程耗时。若数据来自其他已有数据集应链接到源数据集若收集后对数据做过修改或规范化例如词级分词需描述过程与所用工具Who are the source language producers?说明数据由人类还是机器生成描述最初创建数据的人或系统。如果可获得源数据创建者自我报告的人口统计或身份信息可以包含但禁止推断无法确认时应明确说明该信息未知。还应描述数据创建的条件如众包平台、数据来源网站以及是否提供了报酬并描述数据中代表或提及的其他人群。Annotations如果数据集中包含不属于初始数据收集的标注则在此描述分为两个子节Annotation process描述标注流程与使用的工具说明被标注的数据量若非全部描述或引用提供给标注者的标注指南提供标注者间一致性统计interannotator statistics以及标注验证过程Who are the annotators?说明标注由人类还是机器生成描述标注创建者及其遴选标准同样遵循不推断人口统计信息原则并描述标注发生的条件与报酬情况。Personal and Sensitive Information说明数据集是否使用身份类别identity categories及其使用方式与信息来源自我报告、从资料中收集、推断等。说明数据是否与个人关联、个体是否能在数据集中被直接或间接识别。同时说明数据是否包含敏感数据例如种族或民族出身、性取向、宗教信仰、政治观点或工会会员身份、位置、财务或健康数据、生物识别或遗传数据、政府身份证明如社保号、犯罪记录等。若做过匿名化处理描述匿名化过程。使用数据前的注意事项区Considerations for Using the DataSocial Impact of Dataset讨论使用该数据集可能对社会产生的影响既包括积极展望基于它的技术如何改善人们的生活也要讨论伴随的风险例如让重要决策对受影响者更加不透明或强化已有偏见。若数据集包含低资源或代表性不足的语言或该任务对弱势社区有影响也应在此详细说明。Discussion of Biases描述数据中可能反映出的具体偏见并说明是否采取了措施减轻其影响。若已有量化偏见的分析应在此给出简要总结并引用研究。Other Known Limitations如果针对该数据集的研究指出了其他局限例如标注伪影 annotation artifacts在此列出并引用。附加信息区Additional InformationDataset Curators列出参与数据集收集的人员及其所属机构若已知资助信息也一并写入。Licensing Information提供数据集许可证及许可证网页链接。Citation Information提供 BibTeX 格式的数据集引用参考。模板给出了标准结构article{article_id, author {Author List}, title {Dataset Paper Title}, journal {Publication Venue}, year {2525} }若数据集拥有 DOI请一并提供。Contributions感谢为数据集做出贡献的社区成员模板默认写法为Thanks to [github-username] for adding this dataset.。深入原理卡片 YAML 元数据如何驱动数据集加载数据集卡片不只是给人看的文档——它顶部的 YAML 块中声明的configs字段会被 Datasets 库解析为实际的加载配置这是文档驱动代码的典型体现。相关说明可参见仓库文档 repository_structure.mdx 中 Define your splits and subsets in YAML 一节。解析入口MetadataConfigs在源码 metadata.py 中MetadataConfigs是一个字典子类格式为{config_name: {**config_params}}。其类方法from_dataset_card_data负责把卡片 YAML 中的configs列表转换为该结构并做严格校验configs必须是列表否则抛出异常每个配置必须包含config_name字段data_files字段必须是字符串或列表列表项只能是字符串或恰好包含split与path两个键的字典见_raise_if_data_files_field_not_valid中的报错提示与示例features字段会被进一步解析为Features对象。从源码的报错提示可以看到data_files支持的全部合法形态例如configs: - config_name: default data_files: - split: train path: data/*.csv - split: test path: - holdout/abc.csv - holdout/def.csv测试文件 test_metadata_util.py 中给出了多种真实卡片 YAML 与期望解析结果的对照例如带default: true标记的双配置卡片、名为default的配置卡片、以及在configs中直接声明featuresid/int64、name/string、score/float64的卡片验证了 YAML 声明与代码行为的一致性。从元数据到 BuilderConfig在 load.py 的create_builder_configs_from_metadata_configs函数中解析出的MetadataConfigs会被逐条转换为BuilderConfig每个config_name对应一个 builder 配置data_files会被整理成按 split 分组的模式字典若某个配置指向的路径下没有匹配的数据文件会抛出EmptyDatasetError提示检查卡片 YAML 中的data_files参数卡片 YAML 中还可以传入 builder 特有的参数如 CSV builder 的分隔符sep源码会对这些参数做是否被 builder 支持的过滤不支持的参数会被忽略并输出警告日志未提供configs时库会回退为根据数据文件扩展名推断 builder 并生成单个默认配置。默认配置的判定规则MetadataConfigs.get_default_config_namemetadata.py实现了默认配置的判定逻辑当只有一个配置、或某个配置名为default、或某个配置显式标记了default: true时该配置即为默认配置若同时出现多个默认候选会抛出异常提示数据集存在多个默认配置。这与 repository_structure.mdx 中可以使用default: true设置默认配置从而用load_dataset(my_dataset_repository)免去第二个参数的说明完全对应。为什么这一点对卡片作者重要理解了上述机制卡片作者就能一处声明、多处生效在README.md的 YAML 中定义好configs既能让人读也能让库加载既定义了 split 与配置的对应关系又能顺带声明 builder 参数完全无需编写自定义加载代码。这正是数据集卡片从文档升级为数据集的机器可读入口的关键所在。若需要进一步了解不带 YAML 时库如何自动推断 split目录名、文件名、train-00000-of-00003.csv形式、train/training、validation/valid/val/dev、test/testing/eval/evaluation等关键词可阅读 repository_structure.mdx 的 Automatic splits detection 一节。快速上手从模板到成稿的完整路径结合本仓库提供的素材可以归纳出从零到一的完整路径在 Hub 上创建数据集仓库生成README.md仓库中另有 ADD_NEW_DATASET.md 概述了直接在 Hub 上分享数据集的两种方式网页端上传与 CLI 高级指南以 templates/README.md 为骨架创建卡片对照 templates/README_guide.md 逐节填写在 YAML 块中用configs声明 split 与子集参考 repository_structure.mdx 中的全部示例单文件、多文件、glob 模式、多配置、builder 参数、默认配置通过 CLI 分享数据集huggingface-cli upload或直接推送代码文件将README.md与数据文件一并提交上传后即可通过load_dataset(your-dataset-repo)一键加载若结构受支持数据集页面还会自动出现 Dataset Viewer 供所有人预览。一份优秀的数据集卡片应当是诚实而完整的它不仅要回答这个数据集能做什么更要坦率地回答它从哪来、包含什么风险、有哪些局限而 templates/README.md 的结构设计正是为了让这些关键问题一个都不被遗漏。【免费下载链接】datasets The largest hub of ready-to-use datasets for AI models with fast, easy-to-use and efficient data manipulation tools项目地址: https://gitcode.com/gh_mirrors/da/datasets创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考