LeRobot 数据集卡片模板解析读懂 README 的生成骨架与发布原理【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobotHugging Face LeRobot 中的每个数据集仓库Dataset Repo都自带一张自动生成的 README用于描述数据集的元数据、结构与引用方式。这张 README 并非手写而是由 card_template.md 这个 Jinja2 模板渲染而成。本文将完整拆解该模板的字段结构、create_lerobot_dataset_card的渲染流程、meta/info.json与卡片内容的对应关系以及push_to_hub、lerobot-annotate两条真实发布路径帮助读者理解 LeRobot 数据集卡片的生成机制并掌握自定义数据集发布时的完整实操方法。一、模板定位数据集发布链路中的最后一道工序在 LeRobot 中数据集从本地采集到 Hub 发布大体经历lerobot_record采集 →DatasetWriter落盘parquet mp4 存储→meta/info.json元数据写入 → 上传数据文件 → 生成并推送 README 数据集卡片。而 card_template.md 就是这条链路的最后一道工序——它决定了上传到 Hub 后读者在数据集主页看到的第一屏内容。从源码可以确认它的真实消费位置datasets/utils.py 中的create_lerobot_dataset_card()通过importlib.resources.files(lerobot.datasets) / card_template.md读取模板内容再交给DatasetCard.from_template()渲染lerobot_dataset.py 的push_to_hub()在完成数据上传后调用该函数生成卡片并推送lerobot_annotate.py 在标注流水线发布阶段重新生成全新卡片避免旧卡片的链接指向源数据集。此外仓库中还有另一套面向模型而非数据集的卡片模板lerobot_modelcard_template.md由 common/train_utils.py 在模型发布时使用。两者分工明确数据集仓库用card_template.md模型仓库用lerobot_modelcard_template.md。二、模板的完整结构逐段拆解模板全文并不长却由四个职责分明的区域组成下面按顺序逐段说明其作用与渲染方式。1. YAML front matter卡片元数据头模板开头的---包裹区是 YAML front matter对应 Hugging FaceDatasetCard的数据结构DatasetCardData# For reference on dataset card metadata, see the spec # prettier-ignore {{ card_data }}card_data是渲染变量由create_lerobot_dataset_card()传入的DatasetCardData对象序列化而来# prettier-ignore用于告诉格式化工具不要改写这段由代码生成的 YAML保证元数据与代码逻辑一致注释中引用的字段规范来自 Hugging Face Hub 的 dataset card 说明即 license、tags、task_categories、configs 等标准键。在 utils.py 中DatasetCardData被固定填入如下内容字段值说明licensekwargs.get(license)默认apache-2.0须为 Hub 合法 license 标识tags[LeRobot] tags基础标签固定为LeRobot调用方可追加task_categories[robotics]固定归类为机器人任务configs[{config_name: default, data_files: data/*/*.parquet}]声明默认配置读取data/下的全部 parquet 数据文件注意configs中的data_files与 LeRobot 的数据目录约定一一对应每条 episode 的状态/动作数据以 parquet 分片存放在data/下分片大小由DatasetInfo.data_files_size_in_mb控制data/*/*.parquet正好匹配这一布局。测试 tests/datasets/test_dataset_utils.py 精确验证了这套默认值tags [LeRobot]、task_categories [robotics]、configs中data_files data/*/*.parquet。而test_with_tags同文件 L108-L111则验证了追加标签的行为create_lerobot_dataset_card(tags[tag1, tag2])会得到[LeRobot, tag1, tag2]。2. 可视化徽章一键打开数据集浏览器{% if repo_id is defined and repo_id %} a classflex hrefhttps://huggingface.co/spaces/lerobot/visualize_dataset?path{{ repo_id }} img classblock dark:hidden src.../visualize-this-dataset-xl.svg/ img classhidden dark:block src.../visualize-this-dataset-xl-dark.svg/ /a {% endif %}当渲染时传入repo_id卡片顶部就会出现Visualize this dataset徽章点击会跳转到 LeRobot 官方可视化 Space并携带path{{ repo_id }}参数直接打开对应数据集。这里采用明暗双图dark:hidden/hidden dark:block适配深浅主题。若未传repo_id整段被 Jinja2 条件块跳过不渲染任何内容。3. Dataset Description三大信息锚点## Dataset Description {{ dataset_description | default(, true) }} - **Homepage:** {{ url | default([More Information Needed], true)}} - **Paper:** {{ paper | default([More Information Needed], true)}} - **License:** {{ license | default([More Information Needed], true)}}dataset_description数据集的自由文本描述默认空字符串可通过create_lerobot_dataset_card(dataset_description...)注入url/paper/license分别渲染 Homepage、Paper、License 三个锚点均采用default([More Information Needed], true)——第一个参数是缺省文案第二个参数true表示只在变量未定义或为空时才使用默认值避免把空字符串覆盖为占位文本。4. Dataset Structure自动化的 info.json 快照## Dataset Structure {{ dataset_structure | default([More Information Needed], true)}}dataset_structure是本模板最有自动化色彩的部分。当调用方传入dataset_info时utils.py该字段会被自动组装为meta/info.json: json {...DatasetInfo 序列化后的完整 JSON...}即直接把数据集自带的 [meta/info.json](https://link.gitcode.com/i/23d72e55ab4d7426038efe5e1de62325) 全文内嵌进 README让访问者无需下载整个数据集即可预览其数据结构。DatasetInfo 是定义在 [datasets/utils.py](https://link.gitcode.com/i/4835de5eae24145edbda405987f9ac5c) 的类型化 dataclass序列化时会把 feature 的 shape 从 tuple 转回 list、并丢弃未设置的 tools / storage_format 字段保证输出 JSON 干净且与磁盘上的 info.json 一致。 ### 5. CitationBibTeX 引用块 jinja2 ## Citation **BibTeX:** bibtex {{ citation_bibtex | default([More Information Needed], true)}}通过 citation_bibtex 变量注入标准的 BibTeX 条目。若未提供则渲染为占位文本 [More Information Needed]提示贡献者补充引用信息。 ## 三、渲染入口create_lerobot_dataset_card 的参数契约 模板的所有占位变量均由 [create_lerobot_dataset_card()](https://link.gitcode.com/i/0e38cfec262b29f5752e1d70b5bf49d0) 注入。函数签名与关键行为如下 python def create_lerobot_dataset_card( tags: list | None None, dataset_info: DatasetInfo | None None, **kwargs, ) - DatasetCard:tags追加到[LeRobot]之后的标签列表dataset_info传入后自动生成dataset_structure内容**kwargs透传给模板渲染的剩余变量覆盖license、repo_id、url、paper、dataset_description、citation_bibtex等全部占位符返回huggingface_hub.DatasetCard对象可继续调用其push_to_hub()上传。函数内部还硬编码了task_categories[robotics]与configs[{config_name: default, data_files: data/*/*.parquet}]这是 LeRobot 数据集在 Hub 上可被datasets库直接按default配置加载的基础详见前文字段表。四、两条真实发布路径路径一LeRobotDataset.push_to_hub 自动发布最常规的用法是通过LeRobotDataset门面类发布lerobot_dataset.py 的完整流程为前置校验仅支持默认存储格式storage_format DEFAULT_STORAGE_FORMAT否则抛出NotImplementedError——这是为了保证data/、videos/等文件布局与卡片中configs.data_files的 glob 匹配创建仓库HfApi().create_repo(repo_id, repo_typedataset, exist_okTrue)若指定branch则基于当前 revision 创建分支上传文件默认忽略images/目录push_videosFalse时追加忽略videos/适合只发布元数据与 parquet 的场景生成并推送卡片调用create_lerobot_dataset_card(tagstags, dataset_infoself.meta.info, licenselicense, repo_idself.repo_id, **card_kwargs)随后card.push_to_hub(...)打版本标签tag_versionTrue时用当前代码库版本打 Git tag供LeRobotDataset加载时解析 revision见 dataset_metadata.py 的_version属性。关键参数一览参数默认值作用branchNone推送到指定分支不存在则创建tagsNone追加到卡片的标签列表licenseapache-2.0卡片 license 标识tag_versionTrue是否打代码库版本 tagpush_videosTrue为False时跳过videos/上传privateNoneTrue建私有仓库None交由组织默认策略allow_patternsNone限制上传文件的 globupload_large_folderFalse大数据集改用upload_large_folder**card_kwargs—透传卡片模板变量路径二lerobot-annotate 标注流水线重新生成卡片在可转向标注流水线中--push_to_hub触发 _push_to_hub上传数据时显式排除README.mdignore_patterns[.annotate_staging/**, **/.DS_Store, README.md]注释明确说明原因若推送到new_repo_id旧卡片的可视化徽章链接仍指向源数据集必须整体丢弃、重新生成上传完成后从本地读取meta/info.jsonload_info(root)调用create_lerobot_dataset_card(dataset_infodataset_info, licenseapache-2.0, repo_idrepo_id)生成全新卡片并推送随后按info.json中的codebase_version打版本 tag并妥善处理RevisionNotFoundError等异常见 L181-L210。这里与push_to_hub的差异值得注意标注流水线固定使用licenseapache-2.0且不追加自定义 tags说明这是一条面向自动化的确定性输出路径而push_to_hub则把 tags、license 等选择权完全开放给调用方。五、meta/info.json 与卡片的映射关系卡片中Dataset Structure一节的 JSON 内容直接来自meta/info.json其结构由 DatasetInfo dataclass 定义。理解该结构有助于判断一张卡片会展示什么字段类型说明codebase_versionstr创建数据集的 LeRobot 代码版本如v3.0fpsint采集帧率构造时校验必须为正featuresdict[str, dict]各 feature 定义shape、dtype 等序列化时 shape 转 listtotal_episodes/total_frames/total_tasksint计数从 0 起递增chunks_sizeintparquet 分片大小须为正data_files_size_in_mb/video_files_size_in_mbint文件大小阈值MB须为正data_path/video_pathstr文件路径模板storage_formatstr | None存储格式非 None 时路由到对应 backendrobot_typestr | None可选机器人类型splitsdict[str, str]数据集划分写入时更新为{train: 0:{total_episodes}}toolslist[dict] | NoneOpenAI 风格工具 schema未设置时不下发total_episodes与total_frames在 dataset_metadata.py 中随 episode 写入实时累加因此发布时内嵌进卡片的 JSON 快照天然是最终计数。序列化规则utils.py会剔除None的tools与storage_format保持旧数据集info.json的整洁。六、实际操作自定义数据集发布时的卡片定制场景一通过 push_to_hub 定制卡片from lerobot.datasets import LeRobotDataset dataset LeRobotDataset(your-org/my-robot-dataset) dataset.push_to_hub( tags[simulation, pick-place], licenseapache-2.0, push_videosTrue, dataset_descriptionA pick-and-place dataset collected with LeRobot., urlhttps://example.com/project, paperhttps://example.com/paper, citation_bibtexmisc{my2026robot, author {...}, title {...}, year {2026}, }, )其中dataset_description、url、paper、citation_bibtex会经**card_kwargs透传进入模板分别填充 Description 与 Citation 区块。场景二独立生成并预览卡片不依赖具体数据集对象直接构造并检查渲染结果from lerobot.datasets.utils import create_lerobot_dataset_card card create_lerobot_dataset_card( tags[tag1, tag2], licenseapache-2.0, repo_idyour-org/my-robot-dataset, dataset_descriptionHello from a custom card., ) print(card.text) # 查看渲染后的完整 Markdown print(card.data.tags) # [LeRobot, tag1, tag2] card.push_to_hub(your-org/my-robot-dataset, repo_typedataset)这正是 tests/datasets/test_dataset_utils.py 中验证的行为不带参数时得到默认[LeRobot]标签传入 tags 后按[LeRobot, ...]顺序拼接。场景三结合 lerobot-annotate 流水线lerobot-annotate --config path/to/config.yaml --push_to_hub \ --repo_id your-org/source-dataset --new_repo_id your-org/annotated-dataset发布时仓库会自动丢弃源卡片并生成一张指向新仓库、license 为apache-2.0的新卡片最后打上codebase_version版本 tag详见 lerobot_annotate.py。七、常见问题与注意事项license 必须是合法标识符create_lerobot_dataset_card文档字符串明确要求 license 取值为 Hugging Face Hub 的合法 license 标识如apache-2.0、mit传错会导致卡片元数据异常。default(..., true)的语义模板中所有default(x, true)均表示仅当变量未定义/为空时才用默认值。因此显式传入空字符串dataset_description不会覆盖为占位文本反而会渲染为空段落。非默认存储格式无法发布push_to_hub只支持默认 parquet/mp4 布局若storage_format为其他值如lance需走对应存储后端的数据管理流程LeRobotDataset.push_to_hub会直接报NotImplementedErrorlerobot_dataset.py。版本 tag 是加载的必要条件发布后缺失版本 tag 时LeRobotDataset加载会抛出RevisionNotFoundErrorlerobot-annotate会在异常时打印补打 tag 的修复命令lerobot_annotate.py。图片默认不上传ignore_patterns始终包含images/若希望发布图像数据需要自行扩展allow_patterns或使用其他上传方式。八、小结card_template.md虽然只有 35 行却是 LeRobot 数据集发布体系中小而关键的一环它把meta/info.json的机器可读元数据、repo_id驱动的可视化入口、标准化的 Description / Structure / Citation 区块统一渲染成一张规范的 Hugging Face 数据集 README。理解这张模板的变量契约与两条发布路径LeRobotDataset.push_to_hub 与 lerobot-annotate即可在自己的数据集发布流程中精准控制卡片内容让数据集的元数据、结构与引用信息一次到位。相关参考文件card_template.md · datasets/utils.py · dataset_metadata.py · lerobot_dataset.py · lerobot_annotate.py · test_dataset_utils.py【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考