Hugging Face's logo

LeRobot documentation

策略

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

←数据集 处理器→