Language

编写 Provider¶

本页描述任务级 provider 路径：自定义任务（包括托管在外部仓库中的任务）可以通过任务级 DomainRandomizationProvider 声明域随机化。Manager-Based 任务不写 provider；它们在 owner YAML 中通过 Hydra events: manager term 声明随机化（见域随机化与配置）。

任务级域随机化 provider 与 task env owner 放在一起。它们采样任务专属的状态，并返回由 DomainRandomizationManager 消费的 plan。

Provider 形态¶

当前的 provider 示例定义了以下 plan 方法中的一个或多个：

为模型变体或几何 materialization 构建 init plan。
返回带有状态更新和 reset 随机化 payload 的 reset plan。
返回用于 push 或 body-force 扰动的 interval plan。

Interval plan 由 IntervalTermOp 描述符构建（term 名称、NumPy payload、可选的 body_ids；见 Domain Randomization 契约）：

from unilab.dr import INTERVAL_TERM_BODY_FORCE, IntervalRandomizationPlan, IntervalTermOp


def build_interval_randomization_plan(self, env, step_counter):
    ...
    return IntervalRandomizationPlan(
        ops=(
            IntervalTermOp(
                INTERVAL_TERM_BODY_FORCE,
                force,  # 形状 (num_envs, len(body_ids), 3)
                body_ids=body_ids,
            ),
        ),
    )

迁移说明：通过旧版字段（push_perturbation_limit、body_ids、 body_force 等）返回 interval plan 已废弃。这类 plan 仍会经 IntervalRandomizationPlan.iter_ops() 1:1 适配，但新 provider 应填充 ops；旧字段将在下一个 unisim-core major release 中移除。

共享类型位于 unisim.dr.types（interval term 描述符位于 unisim.dr.interval），由 src/unilab/dr/__init__.py 再导出，manager 位于 src/unilab/dr/manager.py。

规则¶

将 XML、asset 和模型元数据访问保留在冷路径上，例如 init、 materialization 或 cache 创建。
不要从 env 热路径探测后端私有方法。
只 dispatch 后端通过其 DR 能力声明的字段。
将任务专属采样放在 task provider 中，而不是训练脚本中。

证据¶

provider 接口与 manager 位于：

src/unilab/dr/provider.py
src/unilab/dr/manager.py

开发者 contract 详情见 Domain Randomization 契约。