feat: add SGLANG_RAY_BUNDLE_INDICES for fine-grained Ray bundle index control (#24667)

Signed-off-by: Haichuan Hu <kaisennhu@gmail.com>

docs_new/docs/basic_usage/offline_engine_api.ipynb

@@ -47,6 +47,62 @@
     "Please see [the examples](https://github.com/sgl-project/sglang/tree/main/examples/runtime/engine) for further use cases."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Ray Integration\n",
+    "\n",
+    "When running in a Ray cluster, you can use `RayEngine` with a custom placement group for fine-grained GPU placement control.\n",
+    "\n",
+    "### Custom Placement Groups\n",
+    "\n",
+    "Pass a `placement_group` with 1-GPU-per-bundle bundles to control exactly which GPUs are used. Each bundle should have exactly 1 GPU for deterministic mapping.\n",
+    "\n",
+    "```python\n",
+    "import ray\n",
+    "from ray.util.placement_group import placement_group\n",
+    "from sglang.srt.ray.engine import RayEngine\n",
+    "\n",
+    "ray.init()\n",
+    "\n",
+    "# Create placement group with specific GPU bundles\n",
+    "pg = placement_group(\n",
+    "    [{\"GPU\": 1} for _ in range(4)],  # 4 bundles, each with 1 GPU\n",
+    "    strategy=\"STRICT_PACK\",\n",
+    ")\n",
+    "ray.get(pg.ready())\n",
+    "\n",
+    "# Launch RayEngine on custom placement group\n",
+    "engine = RayEngine(\n",
+    "    model_path=\"meta-llama/Meta-Llama-3-8B-Instruct\",\n",
+    "    tp_size=4,\n",
+    "    use_ray=True,\n",
+    "    placement_group=pg,\n",
+    ")\n",
+    "\n",
+    "# Optional: specify exact bundle indices via environment variable\n",
+    "# export SGLANG_RAY_BUNDLE_INDICES=\"0,1,2,3\"\n",
+    "```\n",
+    "\n",
+    "### Bundle Index Control\n",
+    "\n",
+    "Use `SGLANG_RAY_BUNDLE_INDICES` environment variable to specify which placement group bundles to use for each worker rank. This enables:\n",
+    "- Skipping unhealthy GPUs\n",
+    "- Topology-aware placement (e.g., NVLink-connected GPUs)\n",
+    "- Non-sequential bundle assignment\n",
+    "\n",
+    "```bash\n",
+    "# Use bundles 0,1,2,7 (skip bundles 3-6) for tp_size=4\n",
+    "export SGLANG_RAY_BUNDLE_INDICES=\"0,1,2,7\"\n",
+    "\n",
+    "# Place workers on NVLink-connected GPUs\n",
+    "export SGLANG_RAY_BUNDLE_INDICES=\"0,1,2,3\"\n",
+    "```\n",
+    "\n",
+    "The number of indices must match `world_size` (`tp_size * pp_size * dp_size`, or `tp_size * pp_size` when `enable_dp_attention=True`)."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},