# 策略

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

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

## PreTrainedPolicy[[lerobot.policies.PreTrainedPolicy]]

#### lerobot.policies.PreTrainedPolicy[[lerobot.policies.PreTrainedPolicy]]

```python
lerobot.policies.PreTrainedPolicy(config: PreTrainedConfig, *inputs, **kwargs)
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L73)

策略模型的基类。

#### chunk_inference_spec[[lerobot.policies.PreTrainedPolicy.chunk_inference_spec]]

```python
chunk_inference_spec()
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L308)

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

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

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

#### count_queued_actions[[lerobot.policies.PreTrainedPolicy.count_queued_actions]]

```python
count_queued_actions()
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L263)

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

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

#### drop_queued_actions[[lerobot.policies.PreTrainedPolicy.drop_queued_actions]]

```python
drop_queued_actions()
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L245)

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

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

#### forward[[lerobot.policies.PreTrainedPolicy.forward]]

```python
forward(batch: dict[str, Tensor])
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L376)

**参数：**

batch (dict[str, Tensor]) : _描述_

**返回：** tuple[Tensor, dict | None]

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

_摘要_

#### from_pretrained[[lerobot.policies.PreTrainedPolicy.from_pretrained]]

```python
from_pretrained(pretrained_name_or_path: str | Path, config: PreTrainedConfig | None = None, force_download: bool = False, resume_download: bool | None = None, proxies: dict | None = None, token: str | bool | None = None, cache_dir: str | Path | None = None, local_files_only: bool = False, revision: str | None = None, strict: bool = False, **kwargs)
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L159)

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

#### generate_text[[lerobot.policies.PreTrainedPolicy.generate_text]]

```python
generate_text(batch: dict[str, Any])
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L363)

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

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

#### get_optim_params[[lerobot.policies.PreTrainedPolicy.get_optim_params]]

```python
get_optim_params()
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L230)

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

#### predict_action_chunk[[lerobot.policies.PreTrainedPolicy.predict_action_chunk]]

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

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L389)

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

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

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

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

#### push_model_to_hub[[lerobot.policies.PreTrainedPolicy.push_model_to_hub]]

```python
push_model_to_hub(cfg: TrainPipelineConfig, peft_model = None, state_dict: dict[str, Tensor] | None = None, dataset_meta: LeRobotDatasetMetadata | None = None)
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L431)

**参数：**

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()`，该方法会同时发布模型及其前/后处理器。

#### 重置[[lerobot.policies.PreTrainedPolicy.reset]]

```python
reset()
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L237)

每当环境被重置时调用。

执行清除缓存等操作。

#### select_action[[lerobot.policies.PreTrainedPolicy.select_action]]

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

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L405)

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

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

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

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

#### supports_rtc[[lerobot.policies.PreTrainedPolicy.supports_rtc]]

```python
supports_rtc()
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L280)

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

#### supports_text_generation[[lerobot.policies.PreTrainedPolicy.supports_text_generation]]

```python
supports_text_generation()
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L359)

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

#### validate_chunk_input_features[[lerobot.policies.PreTrainedPolicy.validate_chunk_input_features]]

```python
validate_chunk_input_features(features: tuple[FeatureSpec, ...])
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L284)

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

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

#### wrap_with_peft[[lerobot.policies.PreTrainedPolicy.wrap_with_peft]]

```python
wrap_with_peft(peft_config = None, peft_cli_overrides: dict | None = None)
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L471)

**参数：**

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]]

#### lerobot.configs.PreTrainedConfig[[lerobot.configs.PreTrainedConfig]]

```python
lerobot.configs.PreTrainedConfig(n_obs_steps: int = 1, input_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>, output_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>, device: str | None = None, dtype: torch.dtype | None = None, use_amp: bool = False, use_peft: bool = False, push_to_hub: bool = True, repo_id: str | None = None, private: bool | None = None, tags: list[str] | None = None, license: str | None = None, pretrained_path: pathlib.Path | None = None, pretrained_revision: str | None = None)
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/configs/policies.py#L42)

**参数：**

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]]

#### lerobot.policies.make_policy[[lerobot.policies.make_policy]]

```python
lerobot.policies.make_policy(cfg: PreTrainedConfig, ds_meta: LeRobotDatasetMetadata | None = None, env_cfg: EnvConfig | None = None, rename_map: dict[str, str] | None = None, defer_weight_load: bool = False, pretrained_path: str | Path | None = None)
```

[源代码](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/factory.py#L255)

**参数：**

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` 对象中推导得出。该函数可以从头初始化一个新策略，也可以加载一个预训练策略。