Hugging Face's logo

LeRobot documentation

策略

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

策略

每个策略都继承自 PreTrainedPolicy，它将 torch.nn.Module 与 Hub 混入类相结合，因此任何策略都可以通过相同的两个调用推送到 Hugging Face Hub 并从中加载。

每种策略都有各自的指南，包含训练配方和结果——ACT、SmolVLA、π₀、π₀.₅ 等其余策略均列于 Policies 下。如需添加策略，请参阅 Adding a Policy。

PreTrainedPolicy

类 lerobot.policies.PreTrainedPolicy

< >

( config: PreTrainedConfig*inputs**kwargs )

策略模型的基类。

chunk_inference_spec

< >

( )

声明默认当前观测块服务作者合约。

继承此实现即声明 predict_action_chunk 会完成直接调用方所需的所有准备工作，接受完整的当前观测，并以模型坐标系返回 [B, chunk_size, A]。其规范的处理器对必须支持完整块。 n_action_steps 是普通的播放切片；RTC 保留完整的预测时域。

要求仅使用 select_action 进行准备、其他动作布局或时间采样的策略必须重写此方法，并拒绝不支持的配置或提供自定义 runner。方法的存在或 warmup 成功并不能作为满足此契约的证据。策略/处理器状态仅允许在独占会话内使用，并且 reset() 必须将其清除以开始新的运行。

count_queued_actions

< >

( )

已计算并等待处理的动作数量。

对于不保留任何动作队列（从不分块）或当前队列为空（即将计算新块）的策略，返回 0。读取与 drop_queued_actions 所清除的相同队列，其名称见 :attr:_action_queue_attrs。

drop_queued_actions

< >

( )

丢弃由先前 select_action 调用预计算的操作。

强制在下一次 select_action 时执行一次新的前向传播，以便在剧集中途的条件变化（例如新指令）能立即生效，而不是在队列排空后才生效。与 reset 不同，剧集的其余状态会被保留。请从调用 select_action 的线程中调用此方法。它会清除 :attr:_action_queue_attrs 中指定的队列；不维护动作队列的策略将继承一个空操作。

forward

< >

( batch: dict[str, Tensor] ) → tuple[Tensor, dict | None]

参数

  • batch (dict[str, Tensor]) — 描述

返回值

tuple[Tensor, dict | None]

损失以及可能的其他信息。除损失（一个 Tensor）外，所有其他项都应为便于日志记录的、原生的 Python 类型。

摘要

from_pretrained

< >

( pretrained_name_or_path: str | Pathconfig: PreTrainedConfig | None = Noneforce_download: bool = Falseresume_download: bool | None = Noneproxies: dict | None = Nonetoken: str | bool | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falserevision: str | None = Nonestrict: bool = False**kwargs )

策略默认使用 policy.eval() 设置为评估模式（dropout 模块被禁用）。若要对其进行训练，您应首先使用 policy.train() 将其切换回训练模式。

generate_text

< >

( batch: dict[str, Any] )

在预处理后的观测批次上运行策略的文本头。

该请求以 batch 作为补充数据（:data:~lerobot.utils.constants.QUERY_KIND / QUERY_TEXT）进行传输；next_subtask 的回复会直接传入 set_task，因此它必须恰好是一个子任务，而不能是计划或编号列表。 返回生成的文本，且不得修改产生动作的状态（队列、观测历史）。

get_optim_params

< >

( )

返回要传递给优化器的策略特定参数（参数或参数组）。

predict_action_chunk

< >

( batch: dict[str, Tensor]**kwargs: Unpack[ActionSelectKwargs] )

返回给定观测值对应的动作块（适用于动作分块策略），可能以批量模式运行。

使用动作分块的子类应在 select_action 内调用此方法，以形成用于选择的缓存动作块。

支持 noise 关键字的策略会从该张量开始采样，其形状与策略通常生成的形状一致。当 noise 为 None 时，策略会按常规方式生成噪声。

可能返回一个 PolicyOutput，其中包含该 chunk 及其预测结果，与 select_action 相同。

push_model_to_hub

< >

( cfg: TrainPipelineConfigpeft_model = Nonestate_dict: dict[str, Tensor] | None = Nonedataset_meta: LeRobotDatasetMetadata | None = None )

参数

  • cfg (TrainPipelineConfig) — 训练配置；保存为 train_config.json，并用于渲染模型卡片。
  • peft_model — 训练适配器时的 PEFT 封装器，其权重将替换发布仓库中的完整模型权重。默认为 None。
  • state_dict (dict[str, Tensor] | None) — 忽略；当策略被分片时，权重现在会在内部进行收集。默认值为 None。
  • dataset_meta (LeRobotDatasetMetadata | None) — 用于模型卡的数据集元数据（如果可用）。默认为 None。

将此策略发布到 Hub。

已弃用：请改用 lerobot.common.train_utils.publish_trained_model()，该方法会同时发布模型及其前/后处理器。

重置

< >

( )

每当环境被重置时调用。

执行清除缓存等操作。

select_action

< >

( batch: dict[str, Tensor]**kwargs: Unpack[ActionSelectKwargs] )

返回一个要在环境中执行的操作（可能以批量模式执行）。

当模型使用观测历史，或输出一系列动作时，此方法负责处理缓存。

返回一个裸动作张量，或一个 PolicyOutput：一个与输入批次结构相同的批次，其中 "action" 键下存放动作，"prediction" 键下存放策略预期或认为的其他内容（一个 PolicyPrediction）。预测值与动作一样按批次组织，每个环境对应一个值，且每个条目以其所引用的内容作为键：预测帧以其所预测的观测键为键，语言以注释样式（“subtask”、“plan”、“memory”）为键，边界框（注释 VQA 模式）以其所绘制的相机为键。调用方使用 lerobot.processor.policy_output_to_transition 对这两种返回类型进行归一化；—display_data 显示第一个环境的预测值。

预测值保存了当前步骤的数据：跨越一个片段（例如一段想象的视频片段）的预测值会逐块返回，并附带每块所属的动作。每个条目会保持显示，直到它再次被返回。预测功能通过策略自行选择的配置字段来启用，且不得改变动作；用于引导策略的文本应通过 generate_text 传递。

supports_rtc

< >

( )

该策略是否实现了实时分块推理语义。

supports_text_generation

< >

( )

该策略是否实现了 generate_text（两者需同时重写）。

validate_chunk_input_features

< >

( features: tuple[FeatureSpec, ...] )

在提供服务之前验证规范输入，默认情况下使用精确的形状。

显式调整大小或掩码缺失输入的策略可能会覆盖此约定。此类例外应归属于策略，而非传输层。协商后的线路模式仍会固定每个已提供特征的形状。

wrap_with_peft

< >

( peft_config = Nonepeft_cli_overrides: dict | None = None )

参数

  • peft_config — 可选的 PEFT 适配器配置（例如 LoraConfig）。 如果提供，则直接使用（并应用 CLI 覆盖）。
  • peft_cli_overrides — 可选的 CLI 覆盖项字典（method_type、target_modules、r 等）。 这些项将与策略默认值合并，以构建最终配置。

使用 PEFT 适配器包装此策略，以实现参数高效微调。

此方法是 PEFT 集成的唯一入口点。子类应重写 _get_default_peft_targets() 以提供默认的目标模块，并重写 _validate_peft_config() 以执行特定于策略的验证。

PreTrainedConfig

类 lerobot.configs.PreTrainedConfig

< >

( n_obs_steps: int = 1input_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>output_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>device: str | None = Nonedtype: torch.dtype | None = Noneuse_amp: bool = Falseuse_peft: bool = Falsepush_to_hub: bool = Truerepo_id: str | None = Noneprivate: bool | None = Nonetags: list[str] | None = Nonelicense: str | None = Nonepretrained_path: pathlib.Path | None = Nonepretrained_revision: str | None = None )

参数

  • n_obs_steps — 传递给策略的环境步数观测数量（包括当前步以及向前回溯的额外步数）。
  • input_features — 一个字典，用于定义策略输入数据的 PolicyFeature。键表示输入数据的名称，值为 PolicyFeature，由 FeatureType 和 shape 属性组成。
  • output_features — 一个字典，用于定义策略输出数据的 PolicyFeature。键表示输出数据的名称，值为 PolicyFeature，由 FeatureType 和 shape 属性组成。
  • normalization_mapping — 一个字典，将 FeatureType 的 str 值（例如 “STATE”、“VISUAL”）映射到对应的 NormalizationMode（例如 NormalizationMode.MIN_MAX）

策略模型的基础配置类。

make_policy

lerobot.policies.make_policy

< >

( cfg: PreTrainedConfigds_meta: LeRobotDatasetMetadata | None = Noneenv_cfg: EnvConfig | None = Nonerename_map: dict[str, str] | None = Nonedefer_weight_load: bool = Falsepretrained_path: str | Path | None = None ) → PreTrainedPolicy

参数

  • cfg (PreTrainedConfig) — 要创建的 policy 的配置。如果设置了 cfg.pretrained_path，则将从该路径加载权重来初始化 policy。
  • ds_meta (LeRobotDatasetMetadata | None) — 用于推断特征形状和类型的数据集元数据。同时为归一化层提供统计信息。
  • env_cfg (EnvConfig | None) — 用于推断特征形状和类型的环境配置。必须提供 ds_meta 或 env_cfg 之一。
  • rename_map (dict[str, str] | None) — 可选的映射，用于将数据集或环境特征键匹配到预期的策略特征名称（例如，"left" → "camera1"）。
  • defer_weight_load (bool) — 构建与 from_pretrained 完全相同的策略——相同的配置解析、相同的基于统计信息的缓冲区、相同的设备放置和评估模式——但跳过 safetensors 权重加载。用于从 DCP 检查点恢复的场景，其分片权重会在 accelerator.prepare() 之后流式加载（分布式检查点引擎会覆盖随机初始化）。对于 PEFT 策略，仅跳过适配器权重的加载，基础权重仍按常规加载。
  • pretrained_path (str | Path | None) — 从此处加载权重（或 PEFT 适配器），而不是从 cfg.pretrained_path 加载。后者在策略构建完成后，仍用于指明该策略所微调的源模型名称。在从检查点恢复训练时使用此参数。

返回值

PreTrainedPolicy

已实例化并放置到设备上的策略模型。

引发

ValueError 或 NotImplementedError

  • ValueError — 如果同时提供了 ds_meta 和 env_cfg，或者两者都未提供。
  • NotImplementedError — 如果尝试使用不受支持的政策-后端组合（例如，VQBeT 与 ‘mps’）。

实例化一个策略模型。

该工厂函数负责创建策略的逻辑，这需要确定输入和输出特征的维度。这些维度可以从 LeRobotDatasetMetadata 对象或 EnvConfig 对象中推导得出。该函数可以从头初始化一个新策略，也可以加载一个预训练策略。

Update on GitHub

←数据集 处理器→