Agent 任务配方

本页是修改仓库前的 routing table。

新增训练 Recipe

Read:

• unirl/config/README.md
• 对应 examples/ 训练域下最接近的 recipe YAML

Edit:

• 同一个训练域/模型目录下的新 YAML
• 若是维护中的 recipe，同步更新 /zh/docs/configuration/experiments 和英文对应页

Check:

python -m unirl.train_<owner> --config-name=<path-under-examples> --cfg job --resolve

<owner> 按 recipe 的入口选择（diffusion、ar、sft、 async_diffusion、async_ar、pe、unified_model 或 agentic）； <path-under-examples> 是 examples/ 下不带扩展名的路径。

Risk: 把一个 trainer 生命周期的 rollout 或 placement 假设套到另一个 trainer， 或 batch geometry 不匹配。

See also: unirl/train/stack/base.py（由 unirl.train.stack 导出）、unirl/config/。

新增模型

Read:

• unirl/models/README.md
• 最接近的 unirl/models/<existing_model>/

Edit:

• unirl/models/<model_name>/
• examples/<path-under-examples>.yaml
• recipe 中构建模型包的 bundle: 和 pipeline: 块

Check:

• bundle._target_ 构建模型模块，pipeline._target_ 消费该共享 bundle
• LoRA target materialization
• rollout engine 期望的 prompt/condition contract

Risk: 把模型特定假设泄漏到 generic rollout 或 training package。

See also: unirl/types/ 和最接近的现有 model package。

新增 Rollout Engine

Read:

• unirl/rollout/README.md
• unirl/distributed/weight_sync/README.md
• existing engine/trainside、engine/sglang 或 engine/vllm_omni

Edit:

• unirl/rollout/engine/<engine>/
• dedicated engine 需要时同步 weight sync backend
• 至少一个 examples/<domain>/ 下的 recipe

Check:

• engine 契约是 generate(sample: Sample) -> Sample；
• backend 输出填入 Sample.parts 中对应的生成 Part；
• direct-vs-dedicated sync contract 通过 validation。

Risk: 把 backend-specific object 直接穿过 rollout/training 边界。

See also: unirl/types/sample.py。

新增或调试 Weight Sync

Read:

• unirl/distributed/weight_sync/README.md
• unirl/rollout/README.md
• recipe 中的 sync selection

Edit:

• unirl/distributed/weight_sync/
• 选择或调优 backend 时更新 examples/<path-under-examples>.yaml

Check:

• dedicated rollout engine 必须配置一个支持的 sync backend；
• direct sampling recipe 必须省略 sync；
• CUDA-IPC sync 只用于 colocate 的 dedicated rollout。

Risk: 混淆 trainer-to-rollout weight sync 和 rollout 输出的 tensor transport。

See also: unirl/distributed/tensor/、unirl/config/。

新增或调试 SDE

Read:

• unirl/sde/README.md
• unirl/algorithms/README.md
• recipe 的 sampling 和 sampling/sde_strategy

Edit:

• unirl/sde/
• unirl/models/<model_name>/ 下的模型特定 sigma override
• 选择 strategy 或 step schedule 时更新 recipe YAML

Check:

• 训练用 strategy 必须提供 GRPO-style loss 需要的 log-probability path；
• evaluation-only solver 不应被用于 train-side ratio objective；
• old log-prob 在 stack.num_updates_per_batch 多更新中保持固定。

Risk: 修改 sigma schedule 或 log-prob 行为，但没有同步 rollout/replay 假设。

See also: unirl/types/sampling.py、unirl/types/sample.py、 unirl/algorithms/flowgrpo.py。

新增 Reward

Read:

• /zh/docs/guides/rewards
• unirl/reward/README.md
• 最接近的 unirl/reward/local/ scorer

Edit:

• scorer implementation 和 spec config
• recipe reward backend

Check:

• scorer batch size 和 device behavior；
• scorer 持有模型时检查 offload/onload。

Risk: 引入没有 batch control 的慢速 in-process scoring。

See also: unirl/reward/local/base.py、unirl/types/reward.py。

调试失败运行

先运行：

python -m unirl.train_<owner> --config-name=<path-under-examples> --cfg job --resolve

然后按顺序看：

• config validation error；
• examples/ 下的启动器；
• unirl/rollout/README.md；
• unirl/train/readme.md。

Risk: 把 Hydra composition 已经编码的 invalid topology 误判成 Ray runtime root cause。