Tencent-Hunyuan · CjhHa1 · Sep 24, 2026 · Sep 1, 2026 · Sep 2, 2026 · Sep 14, 2026
@@ -11,7 +11,7 @@ virtualenv, never `--all-extras`. `train` and `infer` do not pull a rollout engi
 | Engine extra | PyTorch | CUDA |
 |---|---|---|
 | `vllm` (vLLM + vLLM-Omni) | `2.13.0+cu130` | 13.0 |
-| `sglang` | `2.11.0+cu130` | 13.0 |
+| `sglang` | `2.13.0+cu130` | 13.0 |
 
 SGLang's wheel needs glibc >= 2.34. Put NVIDIA's CUDA 13 forward-compat
 libraries on `LD_LIBRARY_PATH` before launch; the launchers do not do this.
@@ -20,7 +20,7 @@ libraries on `LD_LIBRARY_PATH` before launch; the launchers do not do this.
 
 ```bash
 uv venv --python 3.12 --seed .venv && source .venv/bin/activate
-uv pip install -e ".[vllm,train,infer]" --prerelease=allow
+uv pip install -e ".[vllm,train,infer]"
 ```
 
 ## sglang
@@ -47,7 +47,7 @@ Limit build parallelism with `MAX_JOBS` if host RAM is constrained, then install
 the SGLang extra:
 
 ```bash
-uv pip install -e ".[sglang,train,infer]" --prerelease=allow
+uv pip install -e ".[sglang,train,infer]"
 ```
 
 ## Extras
@@ -58,7 +58,7 @@ uv pip install -e ".[sglang,train,infer]" --prerelease=allow
 | `sglang` | `sglang[diffusion]`, `checkpoint-engine`, `flash-attn-4`, `flash-linear-attention[conv1d]`, torch +cu130 stack, PyAV | SGLang-based AR/VLM and diffusion recipes |
 | `fastvideo` | FastVideo pinned to an upstream Git commit | WAN 2.1 / 2.2 rollout; [the extra does not currently resolve](#fastvideo-installation-blocker) |
 | `train` | `wandb`, `aiohttp`, `math-verify` | Training runs and local math-answer scoring |
-| `cosmos3` | `diffusers>=0.39` | [Cosmos3 SFT](unirl/models/cosmos3/README.md); apply the [version constraint](#cosmos3-version-prerequisite) |
+| `cosmos3` | `diffusers>=0.39` | [Cosmos3 SFT](unirl/models/cosmos3/README.md); uv's `diffusers==0.40.0` override already satisfies this extra |
 | `infer` | `accelerate`, `timm` | HunyuanImage3, Janus-Pro, and similar models |
 | `eval` | `torchvision`, `paddlepaddle`, `paddleocr`, `python-Levenshtein` | OCR-based reward components |
 | `veomni` | `veomni` | Recipes using the [VeOmni training backend](unirl/train/backend/veomni/) |
@@ -76,9 +76,9 @@ engine extras; install it when you need OCR rewards.
 For development tools (lint and tests):
 
 ```bash
-uv pip install -e ".[vllm,train,infer,eval,dev]" --prerelease=allow
+uv pip install -e ".[vllm,train,infer,eval,dev]"
 # or, for the sglang engine:
-uv pip install -e ".[sglang,train,infer,eval,dev]" --prerelease=allow
+uv pip install -e ".[sglang,train,infer,eval,dev]"
 ```
 
 Prefer these extras over the legacy [`requirements.txt`](requirements.txt) and
@@ -89,24 +89,19 @@ Prefer these extras over the legacy [`requirements.txt`](requirements.txt) and
 The `fastvideo` extra pins
 [hao-ai-lab/FastVideo@2095477](https://github.com/hao-ai-lab/FastVideo/blob/2095477eac7e289c7a7ab13acb367ca60687c304/pyproject.toml),
 which requires `transformers==4.57.3` and `wandb>=0.21.0`. The transformers pin
-conflicts with UniRL's `transformers>=5.6,<5.7`, so `.[fastvideo]` does not
+conflicts with UniRL's `transformers>=5.12,<5.13`, so `.[fastvideo]` does not
 resolve — a separate venv does not help, because UniRL's base deps still apply.
 Adding `train` also conflicts on `wandb`. Use `$FASTVIDEO_PATH` as in the
 [FastVideo engine README](unirl/rollout/engine/fastvideo/README.md) until the extra
 is solvable.
 
-### Cosmos3 version prerequisite
+### Cosmos3
 
-`cosmos3` asks for `diffusers>=0.39`, but uv's override `diffusers>=0.38.0`
-[replaces](https://docs.astral.sh/uv/concepts/resolution/#dependency-overrides)
-that floor instead of intersecting with it. Include `cosmos3` in the extras and
-pass `--constraint` when installing:
+`cosmos3` asks for `diffusers>=0.39`. The uv override pins `diffusers==0.40.0`,
+which already satisfies that floor, so install it as a normal extra:
 
 ```bash
-COSMOS3_CONSTRAINTS="$(mktemp)"
-printf '%s\n' 'diffusers>=0.39' > "$COSMOS3_CONSTRAINTS"
-uv pip install -e ".[vllm,train,infer,cosmos3]" --prerelease=allow \
-    --constraint "$COSMOS3_CONSTRAINTS"
+uv pip install -e ".[vllm,train,infer,cosmos3]"
 ```
 
 ## Environment

@@ -18,7 +18,7 @@ training environment can be installed with:
 ```bash
 uv venv --python 3.12 --seed .venv
 source .venv/bin/activate
-uv pip install -e ".[vllm,train,infer]" --prerelease=allow
+uv pip install -e ".[vllm,train,infer]"
 ```
 
 Both supported engine extras (`vllm` and `sglang`) install PyAV for raw video

@@ -114,7 +114,7 @@ rollout:
     _target_: unirl.rollout.engine.vllm_omni.config.VLLMOmniEngineConfig
     model_path: ${oc.env:QWEN3_OMNI_PATH,/path/to/Qwen3-Omni-30B-A3B-Instruct}
     modality: qwen3_omni_thinker
-    stage_yaml_override: qwen3_omni_thinker_only_rl_1x4.yaml
+    deploy_config_override: qwen3_omni_thinker_only_rl_1x4.yaml
     enable_sleep_mode: true
     max_prompt_length: 16384
     video_fps: 2.0

@@ -124,7 +124,7 @@ rollout:
     model_path: ${oc.env:QWEN3_OMNI_PATH,/path/to/Qwen3-Omni-30B-A3B-Instruct}
     modality: qwen3_omni_thinker
     # Audio-in-video must serialize packed forwards to avoid elevated rollout/replay K3.
-    stage_yaml_override: qwen3_omni_thinker_only_rl_audio_video_1x4.yaml
+    deploy_config_override: qwen3_omni_thinker_only_rl_audio_video_1x4.yaml
     enable_sleep_mode: true
     max_prompt_length: 16384
     video_fps: 2.0

@@ -114,7 +114,7 @@ rollout:
     model_path: ${oc.env:QWEN3_OMNI_PATH,/path/to/Qwen3-Omni-30B-A3B-Instruct}
     modality: qwen3_omni_thinker
     # Audio-in-video must serialize packed forwards to avoid elevated rollout/replay K3.
-    stage_yaml_override: qwen3_omni_thinker_only_rl_audio_video_1x4.yaml
+    deploy_config_override: qwen3_omni_thinker_only_rl_audio_video_1x4.yaml
     enable_sleep_mode: true
     max_prompt_length: 16384
     video_fps: 2.0

@@ -109,7 +109,7 @@ rollout:
     _target_: unirl.rollout.engine.vllm_omni.config.VLLMOmniEngineConfig
     model_path: ${oc.env:QWEN3_OMNI_PATH,/path/to/Qwen3-Omni-30B-A3B-Instruct}
     modality: qwen3_omni_thinker
-    stage_yaml_override: qwen3_omni_thinker_only_rl_1x4.yaml
+    deploy_config_override: qwen3_omni_thinker_only_rl_1x4.yaml
     enable_sleep_mode: true
     max_prompt_length: 16384
     image_max_pixels: ${bundle.config.image_max_pixels}

@@ -122,7 +122,7 @@ rollout:
     _target_: unirl.rollout.engine.vllm_omni.config.VLLMOmniEngineConfig
     model_path: ${oc.env:QWEN3_OMNI_PATH,/path/to/Qwen3-Omni-30B-A3B-Instruct}
     modality: qwen3_omni_thinker
-    stage_yaml_override: qwen3_omni_thinker_only_rl_1x4.yaml   # TP=4 (audio tower 20 heads)
+    deploy_config_override: qwen3_omni_thinker_only_rl_1x4.yaml   # TP=4 (audio tower 20 heads)
     enable_sleep_mode: true
     omni_extra:
       stage_init_timeout: 1200

@@ -109,7 +109,7 @@ rollout:
     _target_: unirl.rollout.engine.vllm_omni.config.VLLMOmniEngineConfig
     model_path: ${oc.env:QWEN3_OMNI_PATH,/path/to/Qwen3-Omni-30B-A3B-Instruct}
     modality: qwen3_omni_thinker
-    stage_yaml_override: qwen3_omni_thinker_only_rl_1x4.yaml   # TP=4 (audio tower 20 heads)
+    deploy_config_override: qwen3_omni_thinker_only_rl_1x4.yaml   # TP=4 (audio tower 20 heads)
     enable_sleep_mode: true
     omni_extra:
       stage_init_timeout: 1200

@@ -137,7 +137,7 @@ backend:
     total_steps: 100000
   lora_cfg:
     _target_: unirl.train.configs.LoraConfig
-    rank: 64                           # must be <= the stage YAML's max_lora_rank (64)
+    rank: 64                           # must be <= the deploy config's max_lora_rank (64)
     alpha: 128
     dropout: 0.0
     bias: none
@@ -162,7 +162,7 @@ rollout:
     # Required; same checkpoint the bundle loads.
     model_path: ${oc.env:BAGEL_PATH,ByteDance-Seed/BAGEL-7B-MoT}
     # BAGEL single-stage editing modality (registers BagelIt2iAdapter + boots
-    # stage_configs/bagel_t2i_rl.yaml — one YAML serves both image-out modalities —
+    # deploy_configs/bagel_t2i_rl.yaml — one YAML serves both image-out modalities —
     # with RLBagelPipeline).
     modality: bagel_it2i
     # Required for colocate: the trainer calls sleep()/wake_up() around the train

@@ -134,7 +134,7 @@ backend:
     total_steps: 100000
   lora_cfg:
     _target_: unirl.train.configs.LoraConfig
-    rank: 64                           # must be <= the stage YAML's max_lora_rank (64)
+    rank: 64                           # must be <= the deploy config's max_lora_rank (64)
     alpha: 128
     dropout: 0.0
     bias: none
@@ -159,7 +159,7 @@ rollout:
     # Required; same checkpoint the bundle loads.
     model_path: ${oc.env:BAGEL_PATH,ByteDance-Seed/BAGEL-7B-MoT}
     # BAGEL single-stage editing modality (registers BagelIt2iAdapter + boots
-    # stage_configs/bagel_t2i_rl.yaml — one YAML serves both image-out modalities —
+    # deploy_configs/bagel_t2i_rl.yaml — one YAML serves both image-out modalities —
     # with RLBagelPipeline).
     modality: bagel_it2i
     # Required for colocate: the trainer calls sleep()/wake_up() around the train

@@ -119,7 +119,7 @@ rollout:
     # Required; same checkpoint the bundle loads.
     model_path: ${oc.env:BAGEL_PATH,/root/hf_model/BAGEL-7B-MoT}
     # BAGEL single-stage T2I diffusion modality (registers BagelT2iAdapter +
-    # boots stage_configs/bagel_t2i_rl.yaml with RLBagelPipeline).
+    # boots deploy_configs/bagel_t2i_rl.yaml with RLBagelPipeline).
     modality: bagel_t2i
     # Required for colocate: trainer calls sleep()/wake_up() around the train
     # phase, a no-op unless CuMemAllocator is enabled at vLLM-Omni init time.

@@ -108,7 +108,7 @@ rollout:
     # Required; same checkpoint the bundle loads.
     model_path: ${oc.env:BAGEL_PATH,/root/hf_model/BAGEL-7B-MoT}
     # BAGEL single-stage T2I diffusion modality (registers BagelT2iAdapter +
-    # boots stage_configs/bagel_t2i_rl.yaml with RLBagelPipeline).
+    # boots deploy_configs/bagel_t2i_rl.yaml with RLBagelPipeline).
     modality: bagel_t2i
     # Separate slabs don't time-share GPUs, so sleep/wake is unnecessary.
     enable_sleep_mode: false

@@ -20,7 +20,7 @@
 #     sync (sd3/qwen v2 use it). Pushes the trained LoRA adapter into the
 #     co-located sibling engine in-process; the engine runs base + adapter,
 #     which is mathematically the merged model the separate recipe pushed.
-#     hv15's stage config sets enable_lora/max_lora_rank=64 so the adapter
+#     hv15's deploy config sets enable_lora/max_lora_rank=64 so the adapter
 #     actually applies. This avoids the CUDA-IPC path's SGLang dependency,
 #     which the vllm-omni-only venv (two-venv image) does not provide.
 #

@@ -6,7 +6,7 @@
 #   - LoRA training (lora_cfg kept), pushed as the bare ADAPTER each sync
 #     (RemoteLoraWeightSync ships lora_A/lora_B to the engine's set_lora_from_tensors).
 #   - No NCCL group / merged-model broadcast: rank 0 ships the few-MB adapter over a
-#     plain Ray RPC to each rollout Worker. The vLLM-Omni sd35_t2i stage config
+#     plain Ray RPC to each rollout Worker. The vLLM-Omni sd35_t2i deploy config
 #     enables LoRA (enable_lora: true, max_lora_rank: 32), so the engine accepts it.
 
 num_devices: 8
@@ -87,7 +87,7 @@ rollout:
   config:
     _target_: unirl.rollout.engine.vllm_omni.config.VLLMOmniEngineConfig
     model_path: ${oc.env:PRETRAINED_MODEL,stabilityai/stable-diffusion-3.5-medium}
-    # sd35_t2i stage config enables LoRA (enable_lora: true, max_lora_rank: 32),
+    # sd35_t2i deploy config enables LoRA (enable_lora: true, max_lora_rank: 32),
     # so the engine accepts the adapter pushed by RemoteLoraWeightSync.
     modality: sd3_t2i
     # Separate slabs do not time-share GPUs, so sleep/wake is unnecessary.

@@ -118,7 +118,7 @@ backend:
 # texts per prompt; the DiT engine (modality dit_recaption, single diffusion
 # stage, GPUs 4-7) renders M distinct-noise images per recaption. UnifiedModelTrainer
 # wires both with remote() in the shared placement; each engine clears
-# CUDA_VISIBLE_DEVICES for its multi-GPU HI3 modality and its stage YAML's
+# CUDA_VISIBLE_DEVICES for its multi-GPU HI3 modality and its deploy config's
 # runtime.devices pins the physical cards (a real partition, NOT anchor+pop).
 # Both run enable_sleep_mode so the trainer can sleep/wake them around the
 # colocate train phase. The two engines share ONE backbone/LoRA via sync.

@@ -124,7 +124,7 @@ backend:
 # texts per prompt; the DiT engine (modality dit_recaption, single diffusion
 # stage, GPUs 4-7) renders M distinct-noise images per recaption. UnifiedModelTrainer
 # wires both with remote() in the shared placement; each engine clears
-# CUDA_VISIBLE_DEVICES for its multi-GPU HI3 modality and its stage YAML's
+# CUDA_VISIBLE_DEVICES for its multi-GPU HI3 modality and its deploy config's
 # runtime.devices pins the physical cards (a real partition, NOT anchor+pop).
 # Both run enable_sleep_mode so the trainer can sleep/wake them around the
 # colocate train phase. The two engines share ONE backbone/LoRA via sync.

@@ -41,10 +41,9 @@ dependencies = [
   "tensordict>=0.5",
 ]
 
-# Parent/inline engines load this. Multi-stage StageDiffusionProc does not —
-# VLLMOmniHijack.hijack() reinstalls the same hook in spawn children.
+# vllm-omni 0.28 loads this in parent and spawned stage processes.
 [project.entry-points."vllm_omni.general_plugins"]
-unirl_capture_flush = "unirl.rollout.engine.vllm_omni.plugin:register_capture_flush"
+unirl_runtime = "unirl.rollout.engine.vllm_omni.plugin:register_unirl_runtime"
 
 [project.optional-dependencies]
 # sglang pinned to the upstream release the UniRL sglang patch package
@@ -83,10 +82,12 @@ sglang = [
 ]
 # CUDA 13: vllm >=0.26 wants a bare `torch==2.13.0` whose wheel is cu130, and a
 # +cu129 pin would resolve anyway, linking a CUDA-12 torch under a CUDA-13 vllm.
-# Prerelease, so installs need --prerelease=allow, plus sglang's compat layer.
 vllm = [
-  "vllm==0.27.0 ; sys_platform == 'linux'",
-  "vllm-omni==0.27.0rc1 ; sys_platform == 'linux'",
+  "vllm==0.28.0 ; sys_platform == 'linux'",
+  "vllm-omni==0.28.0 ; sys_platform == 'linux'",
+  # vllm-omni 0.28 needs >=5.10.1,<5.15 (5.10.0 is yanked, 5.15 has a known
+  # construction regression); exact because there is no uv.lock to hold it.
+  "transformers==5.12.1 ; sys_platform == 'linux'",
   "torch==2.13.0+cu130 ; sys_platform == 'linux'",
   "torchvision==0.28.0+cu130 ; sys_platform == 'linux'",
   # torchaudio is not required directly by the vLLM backend, so this extra
@@ -169,17 +170,14 @@ index-strategy = "unsafe-best-match"
 # transformers 5.12.1 accepts tokenizers<=0.23.0, but tokenizers 0.23.0(rc)
 # dropped the `cls` kwarg from RobertaProcessing.__new__, so deserializing a
 # saved CLIP tokenizer.json raises TypeError at rollout init (the SD3 text
-# encoders, e2e-confirmed on H20). The sglang install's --prerelease=allow flag
-# (see INSTALL.md) otherwise selects 0.23.0rc*; this override outranks it AND
-# guards against 0.23.0 shipping stable. tokenizers 0.22.2 verified on both
-# engine venvs.
+# encoders, e2e-confirmed on H20). Keep both engine stacks on the verified
+# tokenizers 0.22 family.
 override-dependencies = [
   "kernels>=0.14.1,<0.15",
   "tokenizers>=0.22,<0.23",
-  # sglang[diffusion] hard-pins diffusers==0.37.0 (still pinned on sglang main),
-  # colliding with the base diffusers>=0.38.0 floor (#91); override to the floor
-  # so ".[sglang,...]" stays solvable (same tactic as kernels/tokenizers above).
-  "diffusers>=0.38.0",
+  # Override sglang[diffusion]'s stale 0.37 pin with the exact version required
+  # by vllm-omni 0.28.0. Both mutually exclusive engine stacks use this version.
+  "diffusers==0.40.0",
 ]
 environments = [
   "sys_platform == 'linux' and platform_machine == 'x86_64'",

@@ -90,7 +90,7 @@ Engine dirs use two layouts. The compact engines (`trainside`, `fastvideo`,
 management), `utils/`, `weight_sync.py`, and a
 runtime-patch dir for the pinned upstream (`sglang_diffusion/_patches/`,
 `vllm_omni/patches/`). `vllm_omni` additionally carries worker-subprocess code
-(`pipelines/`, `worker/`) and stage boot configs (`stage_configs/`).
+(`pipelines/`, `worker/`) and deployment configs (`deploy_configs/`).
 
 Model onboarding is per-engine, and the adapter file is usually **not** the whole
 change surface:
@@ -107,7 +107,7 @@ change surface:
   model needs a new upstream patch.
 - **`vllm_omni`:** add an `adapters/<family>.py` binder (keyed by modality),
   register it, import it in `adapters/__init__.py`, and add the appropriate boot
-  YAML under `stage_configs/`. DiT families additionally need a worker-side
+  YAML under `deploy_configs/`. DiT families additionally need a worker-side
   `pipelines/<model>/pipeline.py`; if the AR/DiT worker needs new behavior, add a
   `worker/` extension or `patches/compat_<model>.py`.
 

@@ -8,7 +8,7 @@
 from typing import Any, Dict, List
 
 _PROTOCOL_VERSION = 1
-_SUPPORTED_VLLM_VERSION = "0.27.0"
+_SUPPORTED_VLLM_VERSION = "0.28.0"
 
 
 class _ProtocolError(RuntimeError):

@@ -245,7 +245,7 @@ def build_conditions(self, sample: Sample, per_request: List[List[OmniRawResult]
 class BagelAdapter(ModelAdapter):
     """Bind BAGEL t2i and it2i to one single-stage DiT worker."""
 
-    stage_yaml = "bagel_t2i_rl.yaml"
+    deploy_config = "bagel_t2i_rl.yaml"
     omni_mode = "text-to-image"
     needs_driver_tokenizer = False
     image_input: bool = False  # Whether the modality requires an edit-source image.

@@ -45,7 +45,7 @@ class ModelAdapter(ABC):
 
     modality: str = ""
 
-    stage_yaml: str = ""
+    deploy_config: str = ""
     omni_mode: Optional[str] = None
     needs_sigmas: bool = True
     needs_driver_tokenizer: bool = True
@@ -75,9 +75,9 @@ def resolve_sde_label(strategy: Any) -> Optional[str]:
 
     def boot_kwargs(self) -> Dict[str, Any]:
         """Model-specific boot intent beyond the generic config spelling."""
-        require(bool(self.stage_yaml), f"{type(self).__name__} must set stage_yaml")
+        require(bool(self.deploy_config), f"{type(self).__name__} must set deploy_config")
         kwargs: Dict[str, Any] = {
-            "stage_yaml": self.stage_yaml,
+            "deploy_config": self.deploy_config,
             "needs_driver_tokenizer": bool(self.needs_driver_tokenizer),
             "clear_cuda_visible": bool(self.clear_cuda_visible),
         }