[Core] Composable parallel: Phase 1 strategy overlay (TP/DP/stage-replica) (RFC #4084) (#4281)

Signed-off-by: Kushan A. <kahmadian@nvidia.com>
Signed-off-by: kushanam <kushanam@users.noreply.github.com>
Signed-off-by: Kushan A <kahmadian@nvidia.com>
Signed-off-by: kahmadian <kahmadian@users.noreply.github.com>
Co-authored-by: kushanam <kushanam@users.noreply.github.com>
Co-authored-by: kahmadian <kahmadian@users.noreply.github.com>

examples/offline_inference/qwen2_5_omni/README.md

@@ -60,3 +60,24 @@ If media file paths are not provided, the script will use default assets. Suppor
 - `mixed_modalities`: Audio + image + video
 - `use_audio_in_video`: Extract audio from video
 - `text`: Text-only query
+
+### Composable parallelism (strategy configs)
+
+You can shard or replicate a stage with a small composable-parallel
+`strategy.yaml` overlaid onto the **bundled default deploy config** -- no bespoke
+deploy YAML required. Supply the strategy with `--strategy-config` and any matching
+device layout via `--stage-overrides` (explicit kwargs forwarded to `Omni`).
+
+Both examples below require >= 3 GPUs (the thinker uses 2, talker + code2wav share a third):
+
+```bash
+# Tensor-parallel the thinker (TP=2)
+python end2end.py --query-type text --num-prompts 6 \
+    --strategy-config strategy_tp2.yaml \
+    --stage-overrides '{"0": {"devices": "0,1"}, "1": {"devices": "2"}, "2": {"devices": "2"}}'
+
+# Replicate the thinker across 2 engines (round-robin load balancing)
+python end2end.py --query-type text --num-prompts 6 \
+    --strategy-config strategy_stage_replica.yaml \
+    --stage-overrides '{"0": {"devices": "0,1"}, "1": {"devices": "2"}, "2": {"devices": "2"}}'
+```

examples/offline_inference/qwen2_5_omni/end2end.py

@@ -553,6 +553,39 @@ def parse_args():
         default=False,
         help="Use py_generator mode. The returned type of Omni.generate() is a Python Generator object.",
     )
+    parser.add_argument(
+        "--deploy-config",
+        type=str,
+        default=None,
+        help="Optional explicit deploy YAML (otherwise the bundled default is used).",
+    )
+    parser.add_argument(
+        "--strategy-config",
+        type=str,
+        default=None,
+        help=(
+            "Optional composable-parallel strategy.yaml mapping role -> parallel axes "
+            "(e.g. tp / stage_replica). Overlaid onto the merged stage configs."
+        ),
+    )
+    parser.add_argument(
+        "--stage-overrides",
+        type=str,
+        default=None,
+        help=(
+            "Optional JSON of per-stage overrides applied on top of the default "
+            'deploy config, e.g. \'{"0": {"devices": "0,1"}}\' to give the '
+            "thinker a 2-GPU pool. Lets you run a strategy on the bundled default "
+            "deploy config without writing a bespoke deploy YAML."
+        ),
+    )
+    parser.add_argument(
+        "--omni-lb-policy",
+        type=str,
+        default=None,
+        choices=["random", "round-robin", "least-queue-length"],
+        help="StagePool load-balancer policy for replicated stages (orchestrator-level knob).",
+    )
     return parser.parse_args()
 
 

examples/offline_inference/qwen2_5_omni/strategy_stage_replica.yaml

@@ -0,0 +1,22 @@
+# Composable-parallel strategy for Qwen2.5-Omni.
+#
+# Replicate the thinker stage across 2 independent engines and let the omni
+# StagePool balance requests round-robin across them. The thinker's `devices`
+# entry acts as a per-replica template, so omni expands it to one GPU per replica.
+# The `routing: round_robin` below auto-derives the StagePool load-balancer policy,
+# so --omni-lb-policy is not needed.
+#
+# Rather than hand-write a bespoke deploy YAML, run on the bundled default deploy
+# config and pass the matching 2-GPU device template via --stage-overrides (explicit
+# kwargs): the thinker gets a two-GPU pool while talker + code2wav share a third
+# card. Requires >= 3 GPUs.
+#
+# Usage:
+#   python3 end2end.py --query-type text --num-prompts 6 \
+#       --strategy-config strategy_stage_replica.yaml \
+#       --stage-overrides '{"0": {"devices": "0,1"}, "1": {"devices": "2"}, "2": {"devices": "2"}}'
+strategies:
+  thinker:
+    - axis: stage_replica
+      size: 2
+      routing: round_robin

examples/offline_inference/qwen2_5_omni/strategy_tp2.yaml

@@ -0,0 +1,19 @@
+# Composable-parallel strategy for Qwen2.5-Omni: tensor-parallel the thinker.
+#
+# Shard the thinker stage across 2 GPUs with tensor parallelism (TP=2). TP routing
+# is fixed (broadcast), so no `routing` / load-balancer policy is involved -- this
+# is the simplest axis and a good starting point for the mental model.
+#
+# The strategy sets tensor_parallel_size=2 on the thinker. Rather than hand-write a
+# bespoke deploy YAML, run on the bundled default deploy config and pass a matching
+# 2-GPU device layout via --stage-overrides (explicit kwargs), so the thinker gets a
+# two-GPU pool while talker + code2wav share a third card. Requires >= 3 GPUs.
+#
+# Usage:
+#   python3 end2end.py --query-type text --num-prompts 6 \
+#       --strategy-config strategy_tp2.yaml \
+#       --stage-overrides '{"0": {"devices": "0,1"}, "1": {"devices": "2"}, "2": {"devices": "2"}}'
+strategies:
+  thinker:
+    - axis: tp
+      size: 2