feat(vllm): Tackle out of memory errors (EAI-8058)

README.md

@@ -601,7 +601,8 @@ Log in with `huggingface-cli login` or set `HF_TOKEN` in your environment
 before serving gated models.
 
 `--gpu` selects which AMD GPU the server runs on. `auto` (the default) probes
-per-GPU VRAM with `amd-smi` and picks the lowest-numbered GPU that is idle and
+per-GPU VRAM (via `amd-smi`, or the amdgpu DRM sysfs counters when `amd-smi` is
+not installed) and picks the lowest-numbered GPU that is idle and
 not already used by another rocm-cli server (managed or foreground), falling
 back to the GPU with the most free memory. Pass a single index (`--gpu 1`) to
 pin a specific device. The

crates/rocm-core/src/fix.rs

@@ -574,9 +574,38 @@ const RECIPES: &[FixRecipe] = &[
         applies_on: PRINT_ON_WINDOWS,
         runner: None,
     },
-    // The number is a stable handle, not a position: `fix-16` is reserved by the
-    // vLLM out-of-memory entry on its own branch, so this one takes 17 rather
-    // than colliding and forcing whichever lands second to rename a published id.
+    FixRecipe {
+        fix_id: "fix-16-vllm-oom",
+        title: "vLLM ran the GPU out of memory at startup",
+        rationale: "vLLM reserves a fixed fraction (~90%) of each GPU's TOTAL VRAM for its KV cache by default, regardless of the model size or how much is currently free. Two different faults surface the same OOM, and they need opposite responses. If the GPU is shared or already busy, that reservation collides with memory in use and lowering it (or moving to a less-busy GPU) is the fix. If the model genuinely does not fit in this GPU's VRAM, lowering the reservation only trades an earlier OOM for a later one -- use a smaller or quantized model instead (rocm-cli serves one model on a single GPU; it does not shard a model across GPUs).",
+        commands: &[
+            "# Case 1 -- shared/busy GPU (tenancy collision): lower the reservation,",
+            "# or steer vLLM onto a less-busy device:",
+            "rocm serve <model> --gpu-memory-utilization 0.5",
+            "rocm serve <model> --gpu <index>",
+            "# Case 2 -- the model genuinely does not fit: the reservation is not the",
+            "# problem; pick a smaller or quantized model (single-GPU serving only).",
+        ],
+        needs_sudo: false,
+        needs_reboot: false,
+        needs_relogin: false,
+        verify: "rocm serve <model> <case-appropriate options above>   # re-run and watch for a clean startup",
+        notes: &[
+            "Only lower --gpu-memory-utilization when the GPU is shared or already busy; on a GPU dedicated to this server it cannot create the room a too-large model needs.",
+            "This entry is keyword-matched from the error text: `rocm diagnose` cannot see per-GPU VRAM or tenancy, so pass the failure with --symptom (or arrive from the `rocm serve` failure note).",
+        ],
+        // Matches `check_16_vllm_oom`'s `["linux", "wsl"]` registration: WSL2 is
+        // the supported way to serve from a Windows host and the failure mode is
+        // just as real there, so the fix has to be runnable where the diagnosis
+        // is reachable. Pinned by
+        // `every_checker_platform_is_covered_by_its_recipe`.
+        doc_url: None,
+        applies_on: PRINT_ON_LINUX_AND_WSL,
+        runner: None,
+    },
+    // The number is a stable handle, not a position: `fix-16` is held by the
+    // vLLM out-of-memory entry above, so this one takes 17 rather than
+    // colliding and forcing whichever lands second to rename a published id.
     FixRecipe {
         fix_id: "fix-17-torch-dlpack",
         title: "Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)",
@@ -976,6 +1005,35 @@ pub(crate) fn torch_rocm_indexes_named_in<'a>(
         .collect()
 }
 
+/// Test-only view of a recipe's actionable remediation: its `verify` command,
+/// its `notes`, and its *executable* command lines (comment/prose lines
+/// stripped). Lets the diagnosis catalog cross-check that the Fix it emits for a
+/// shared `fix_id` has not silently diverged from this recipe.
+#[cfg(test)]
+pub(crate) fn recipe_verify_notes_and_run_commands(
+    fix_id: &str,
+) -> Option<(&'static str, &'static [&'static str], Vec<&'static str>)> {
+    find_recipe(fix_id).map(|recipe| {
+        let run_commands = recipe
+            .commands
+            .iter()
+            .copied()
+            .filter(|line| !line.trim_start().starts_with('#'))
+            .collect::<Vec<_>>();
+        (recipe.verify, recipe.notes, run_commands)
+    })
+}
+
+/// Test-only view of the platform families a recipe is runnable on.
+///
+/// `None` when no recipe carries `fix_id`. Lets the diagnosis catalog assert
+/// that every platform a checker answers on is a platform `rocm fix` will
+/// actually act on, which `recipe_verify_notes_and_run_commands` cannot see.
+#[cfg(test)]
+pub(crate) fn recipe_applies_on(fix_id: &str) -> Option<Vec<&'static str>> {
+    find_recipe(fix_id).map(|recipe| recipe.applies_on.iter().map(|p| p.os).collect())
+}
+
 /// Whether `fix_id` names an entry in the catalog.
 ///
 /// A predicate rather than the lookup itself, because the caller that needs it
@@ -2315,9 +2373,10 @@ mod tests {
         let count = ids.len();
         ids.dedup();
         assert_eq!(ids.len(), count, "duplicate fix-id in RECIPES");
-        // 18 bare-metal/Windows entries (fix-17, fix-18 and fix-19 among them)
-        // plus the 7 WSL ones.
-        assert_eq!(count, 25, "expected 25 catalog entries");
+        // 19 bare-metal/Windows entries (fix-16-vllm-oom, fix-17-torch-dlpack,
+        // fix-18-comgr-conflict and fix-19-shm-too-small among them) plus the
+        // 7 WSL ones.
+        assert_eq!(count, 26, "expected 26 catalog entries");
     }
 
     /// Restored, not new. This PR made the `wsl` arm of the platform lookup
@@ -2362,6 +2421,43 @@ mod tests {
     /// `apply` reaches its internal-error path. The converse is deliberately
     /// not asserted: a print-only recipe may hold a runner that reports without
     /// writing, which is exactly what `fix-2-unset-override` does on Linux.
+    #[test]
+    fn the_utilization_hint_example_matches_the_recipe_command() {
+        // The shared hint carries a worked value, and `fix-16-vllm-oom` hands
+        // the user a command carrying another. They drifted once already: the
+        // docs and the recipe moved to 0.5 while the const kept recommending
+        // 0.1, so one `rocm diagnose` printed "e.g. 0.1 for a small model"
+        // directly above `rocm serve <model> --gpu-memory-utilization 0.5`.
+        // Nothing caught it -- the cross-check in `diagnose` exempts the summary
+        // as prose framing, and a line-based grep misses the const because the
+        // flag and the value sit on different continuation lines.
+        const FLAG: &str = "--gpu-memory-utilization";
+        let hint = crate::VLLM_GPU_MEMORY_UTILIZATION_HINT;
+        let example = hint
+            .split_once("e.g. ")
+            .and_then(|(_, rest)| rest.split_whitespace().next())
+            .unwrap_or_else(|| {
+                panic!("the shared hint no longer carries a worked `e.g. <value>`:\n{hint}")
+            });
+        let recipe = find_recipe("fix-16-vllm-oom").expect("fix-16-vllm-oom is in the catalog");
+        let commanded = recipe
+            .commands
+            .iter()
+            .find_map(|line| line.split_once(FLAG))
+            .and_then(|(_, rest)| rest.split_whitespace().next())
+            .unwrap_or_else(|| {
+                panic!(
+                    "fix-16-vllm-oom no longer commands `{FLAG}`:\n{:#?}",
+                    recipe.commands
+                )
+            });
+        assert_eq!(
+            example, commanded,
+            "the shared hint recommends `{FLAG} {example}` while `rocm fix fix-16-vllm-oom` \
+             commands `{FLAG} {commanded}`; both can print in a single `rocm diagnose` report"
+        );
+    }
+
     #[test]
     fn a_recipe_that_acts_has_a_runner() {
         for r in RECIPES {
@@ -2510,6 +2606,17 @@ mod tests {
                 ("fix-9-igpu-dgpu", "windows", FixClass::NeedsArgument),
             ]
         );
+        // fix-16-vllm-oom carries a workaround the user must weigh (lowering the
+        // VRAM reservation is wrong for a model that genuinely does not fit), so
+        // it is deliberately PRINT-ONLY and must never join the AUTO set.
+        let oom = find_recipe("fix-16-vllm-oom").expect("OOM recipe is in the catalog");
+        assert!(
+            oom.applies_on
+                .iter()
+                .all(|p| p.class == FixClass::PrintOnly),
+            "fix-16-vllm-oom must stay PRINT-ONLY on every platform it applies to"
+        );
+        assert!(oom.runner.is_none(), "a PRINT-ONLY recipe has no runner");
     }
 
     #[test]

crates/rocm-core/src/lib.rs

@@ -38,12 +38,14 @@ pub mod proc_lifecycle;
 pub mod report;
 pub mod report_delivery;
 pub mod runtime;
+pub mod terminal;
+
 #[cfg(test)]
 mod test_env;
 pub mod uv;
 pub use diagnose::{
-    DiagnoseReport, Diagnosis, Fix, Route, diagnose as run_diagnose,
-    render_report_text as render_diagnose_text,
+    DiagnoseReport, Diagnosis, Fix, Route, VLLM_OOM_CANONICAL_SYMPTOM, diagnose as run_diagnose,
+    render_report_text as render_diagnose_text, vllm_oom_symptom_is_diagnosable,
 };
 pub use disk_space::{
     SpaceCheck, available_space_for_path, check_space_for_path, ensure_space_for,
@@ -5718,8 +5720,21 @@ fn detect_linux_drm_ip_discovery_gfx_target() -> Option<String> {
     None
 }
 
-#[cfg(any(target_os = "linux", test))]
-fn is_amdgpu_device(device_dir: &Path) -> bool {
+/// Whether a DRM `device` directory belongs to an AMD GPU: the PCI `vendor` id
+/// (`0x1002`), or, when that is unreadable, an `amdgpu` `uevent` `DRIVER=` line.
+///
+/// Both signals are needed. A vendor-only test under-counts on hosts where
+/// `vendor` is absent or unreadable, and the callers are counting *cards* — the
+/// KFD/DRM count authority here and the `rocm` CLI's sysfs fallback probe — so
+/// an under-count silently narrows the multi-card ordinal guard.
+///
+/// `pub` and not `#[cfg(target_os = "linux")]` precisely so there is one copy:
+/// the CLI's fallback probe used to carry its own, with a doc comment asserting
+/// the two were "the same two-signal test" and nothing holding them to it. It
+/// reads files, so there is nothing platform-specific to gate, and gating it
+/// would put it out of reach of a dependent crate's `cfg(test)` build.
+#[must_use]
+pub fn is_amdgpu_device(device_dir: &Path) -> bool {
     if let Ok(vendor) = fs::read_to_string(device_dir.join("vendor"))
         && vendor.trim().eq_ignore_ascii_case("0x1002")
     {
@@ -8136,6 +8151,27 @@ pub fn resolve_amd_smi_binary() -> OsString {
     resolve_amd_smi_binary_in_home(runtime_home_dir().as_deref())
 }
 
+/// The `--gpu-memory-utilization` workaround for a shared/busy GPU.
+///
+/// Shared by the `rocm` CLI (pre-launch low-VRAM note), the vLLM engine adapter
+/// (post-failure OOM hint) and the `fix-16-vllm-oom` diagnosis summary, so those
+/// surfaces never drift into different wording for the same fix. The
+/// `rocm fix fix-16-vllm-oom` catalog rationale is deliberately NOT this text —
+/// it frames the same fault for a different reader — but its worked value is
+/// pinned to this one (see below). vLLM reserves a fixed fraction of each
+/// GPU's *total* VRAM by default (~0.9), independent of the model size or how
+/// much is currently free, so on a shared or busy card that reservation
+/// collides with memory already in use and the engine OOMs even a tiny model.
+///
+/// The worked example must stay the value the `fix-16-vllm-oom` recipe and the
+/// docs hand the user (`0.5`). A smaller budget such as `0.1` sits below the
+/// weights of most models people actually serve, so it trades one startup
+/// failure for another. Pinned by
+/// `the_utilization_hint_example_matches_the_recipe_command`.
+pub const VLLM_GPU_MEMORY_UTILIZATION_HINT: &str = "vLLM reserves ~90% of the GPU's total VRAM by default; on a shared or busy GPU this can \
+     collide with memory already in use. Lower the reservation with `--gpu-memory-utilization \
+     <0-1>` (e.g. 0.5 for a small model), or target a less-busy GPU with `--gpu <index>`.";
+
 /// Locate `amd-smi` inside the bin directories of the newest managed ROCm SDK
 /// runtime recorded in the registry. The binary ships with the TheRock wheel
 /// (under the SDK `bin_path` and/or the venv `install_root/bin`) and is not on