{{htmlmetatags>metatag-robots=(index,follow)
metatag-keywords=(LeRobot,Hugging Face Hub,数据集共享,模型共享,EnvHub,认证,缓存)
metatag-description=(LeRobot 的 Hugging Face Hub 集成：数据集和模型共享、Hub 操作、版本兼容性和认证机制)
}}

====== LeRobot Hugging Face Hub 集成 ======

本页面记录 LeRobot 如何与 Hugging Face Hub 集成以存储、版本化和分发数据集、策略和奖励模型。Hub 作为所有 LeRobot 组件的中央仓库，实现跨社区的无缝共享和可复现性。

LeRobot 利用 ''huggingface_hub'' 库为机器人数据提供 Git 风格的体验，支持版本化快照、选择性下载和自动元数据生成。

[[机器人:lerobot:home|返回概述]]

===== Hub 集成架构 =====

LeRobot 将 Hugging Face Hub 视为一等存储后端。集成主要由 ''LeRobotDataset''（数据）和 ''HubMixin''（通过 ''RewardModelConfig'' 和 ''PreTrainedPolicy'' 的模型）处理。

===== 数据集 Hub 操作 =====

数据集下载使用 ''snapshot_download'' 并带有智能缓存：

  * 当提供 ''repo_id'' 且没有 ''root'' 路径时，默认使用 ''$HF_LEROBOT_HOME/hub'' 下的版本安全快照缓存
  * ''LeRobotDataset'' 支持两种模式：从本地 ''root'' 加载或从 ''repo_id'' 下载

'''LeRobotDatasetMetadata''' 类处理初始发现，先下载 ''meta/'' 目录，允许系统在提交下载大型 Parquet 或视频文件前检查数据集结构。

==== 数据集元数据文件 ====

Hub 上的每个数据集仓库包含由 ''LeRobotDatasetMetadata'' 管理的 ''meta/'' 目录：

  * ''info.json''：数据集信息（FPS、特征维度、总帧数等）
  * ''stats.json''：每通道统计数据（均值、标准差、最小、最大值）
  * ''tasks.parquet''：任务描述

===== 模型和奖励 Hub 操作 =====

LeRobot 使用 ''HubMixin'' 为配置类提供 Hub 功能：

  * ''RewardModelConfig'' 使用 ''from_pretrained'' 和 ''push_to_hub'' 实现奖励分类器和 SARM 的加载和共享
  * 模型卡使用 ''lerobot_modelcard_template.md'' 模板确保文档完备
  * 数据集卡通过 ''create_lerobot_dataset_card'' 创建

===== 版本控制和兼容性 =====

  * 当前标准格式版本：**v3.0**（''CODEBASE_VERSION = "v3.0"''）
  * 如果请求的版本与代码库版本匹配，系统使用 ''get_safe_version'' 确保 Hub 仓库确实包含该版本或兼容版本
  * **v2.1 到 v3.0 迁移**：提供迁移脚本 ''convert_dataset_v21_to_v30.py''

===== 认证和缓存 =====

**Hub 缓存**：

  * ''HF_LEROBOT_HUB_CACHE''（默认为 ''$HF_LEROBOT_HOME/hub''）用于版本安全快照存储
  * 如果显式提供 ''root'' 路径，Hub 下载直接物化到该路径

**认证机制**：

  * ''HfApi'' 用于认证请求（如创建仓库、推送文件）
  * ''token'' 参数传递给 ''snapshot_download'' 和 ''hf_hub_download''，支持私有仓库
  * 训练脚本使用 ''WandBLogger'' 记录模型工件到 Weights & Biases，可链接回 Hugging Face 模型

===== 相关页面 =====

  * [[机器人:lerobot:home|LeRobot 框架概述]]
  * [[机器人:lerobot:数据集|数据集]]
  * [[机器人:lerobot:训练与评估|训练与评估]]