From aac589ee49fc264d99e5cc3296bd3f88217c7693 Mon Sep 17 00:00:00 2001
From: cyq <61975706+cyq1017@users.noreply.github.com>
Date: Mon, 15 Jun 2026 14:14:37 +0800
Subject: [PATCH] fix(cookbook): diagnose sglang native deps (#4112)

---
 routes/cookbook_helpers.py          | 10 ++++++++++
 routes/cookbook_routes.py           | 10 ++++++++++
 static/js/cookbook-diagnosis.js     |  9 +++++++++
 tests/test_cookbook_diagnosis.py    | 21 +++++++++++++++++++++
 tests/test_cookbook_diagnosis_js.py | 10 ++++++++++
 5 files changed, 60 insertions(+)

diff --git a/routes/cookbook_helpers.py b/routes/cookbook_helpers.py
index 78b644ea0..d06af50d7 100644
--- a/routes/cookbook_helpers.py
+++ b/routes/cookbook_helpers.py
@@ -1093,6 +1093,16 @@ def _diagnose_serve_output(text: str) -> dict | None:
             "vLLM is not installed or not in PATH on this server.",
             [{"label": "install vLLM in Cookbook Dependencies", "op": "dependency", "package": "vllm"}],
         ),
+        (
+            r"sgl_kernel[\s\S]*(Python\.h|libnuma\.so\.1|common_ops)|"
+            r"(Python\.h|libnuma\.so\.1|common_ops)[\s\S]*sgl_kernel|"
+            r"Please ensure sgl_kernel is properly installed",
+            "SGLang native dependencies are missing on this server.",
+            [
+                {"label": "install OS packages: libnuma-dev python3.12-dev build-essential", "op": "manual"},
+                {"label": "upgrade sglang-kernel after OS packages are installed", "op": "manual"},
+            ],
+        ),
         (
             r"sglang.*command not found|No module named sglang|SGLang is not installed",
             "SGLang is not installed or not in PATH on this server.",
diff --git a/routes/cookbook_routes.py b/routes/cookbook_routes.py
index cfbb514ac..9f6ca1949 100644
--- a/routes/cookbook_routes.py
+++ b/routes/cookbook_routes.py
@@ -171,6 +171,16 @@ def setup_cookbook_routes() -> APIRouter:
                 "vLLM is not installed or not in PATH on this server.",
                 [{"label": "install vLLM in Cookbook Dependencies", "op": "dependency", "package": "vllm"}],
             ),
+            (
+                r"sgl_kernel[\s\S]*(Python\.h|libnuma\.so\.1|common_ops)|"
+                r"(Python\.h|libnuma\.so\.1|common_ops)[\s\S]*sgl_kernel|"
+                r"Please ensure sgl_kernel is properly installed",
+                "SGLang native dependencies are missing on this server.",
+                [
+                    {"label": "install OS packages: libnuma-dev python3.12-dev build-essential", "op": "manual"},
+                    {"label": "upgrade sglang-kernel after OS packages are installed", "op": "manual"},
+                ],
+            ),
             (
                 r"sglang.*command not found|No module named sglang|SGLang is not installed",
                 "SGLang is not installed or not in PATH on this server.",
diff --git a/static/js/cookbook-diagnosis.js b/static/js/cookbook-diagnosis.js
index 1ea9ea4b8..2a597553d 100644
--- a/static/js/cookbook-diagnosis.js
+++ b/static/js/cookbook-diagnosis.js
@@ -320,6 +320,15 @@ export const ERROR_PATTERNS = [
       }},
     ],
   },
+  {
+    pattern: /sgl_kernel[\s\S]*(Python\.h|libnuma\.so\.1|common_ops)|(Python\.h|libnuma\.so\.1|common_ops)[\s\S]*sgl_kernel|Please ensure sgl_kernel is properly installed/i,
+    message: 'SGLang native dependencies are missing on this server.',
+    fixes: [
+      { label: 'Copy OS package command', action: () => _copyText('sudo apt-get install -y libnuma-dev python3.12-dev build-essential') },
+      { label: 'Copy kernel upgrade', action: () => _copyText('python3 -m pip install --upgrade sglang-kernel') },
+      { label: 'Open Dependencies', action: () => _openCookbookDependencies('sglang') },
+    ],
+  },
   {
     pattern: /sglang.*command not found|No module named sglang|SGLang is not installed/i,
     message: 'SGLang is not installed or not in PATH.',
diff --git a/tests/test_cookbook_diagnosis.py b/tests/test_cookbook_diagnosis.py
index da3168ab1..b590d4cf7 100644
--- a/tests/test_cookbook_diagnosis.py
+++ b/tests/test_cookbook_diagnosis.py
@@ -13,3 +13,24 @@ def test_diagnose_vllm_modelopt_lm_head_error():
     assert "ModelOpt LM-head" in diagnosis["message"]
     assert diagnosis["suggestions"][0]["op"] == "manual"
     assert "provides this CLI" in diagnosis["suggestions"][0]["label"]
+
+
+def test_diagnose_sglang_native_dependency_errors():
+    output = """
+    /tmp/cuda_utils.c:7:10: fatal error: Python.h: No such file or directory
+    ImportError:
+    [sgl_kernel] CRITICAL: Could not load any common_ops library!
+    Please ensure sgl_kernel is properly installed with:
+    pip install --upgrade sglang-kernel
+    Error details from previous import attempts:
+    - ImportError: libnuma.so.1: cannot open shared object file
+    """
+
+    diagnosis = _diagnose_serve_output(output)
+
+    assert diagnosis is not None
+    assert "SGLang native dependencies" in diagnosis["message"]
+    labels = [suggestion["label"] for suggestion in diagnosis["suggestions"]]
+    assert any("libnuma-dev" in label for label in labels)
+    assert any("python3.12-dev" in label for label in labels)
+    assert any("sglang-kernel" in label for label in labels)
diff --git a/tests/test_cookbook_diagnosis_js.py b/tests/test_cookbook_diagnosis_js.py
index 42d7fc982..5b8dc849a 100644
--- a/tests/test_cookbook_diagnosis_js.py
+++ b/tests/test_cookbook_diagnosis_js.py
@@ -10,3 +10,13 @@ def test_repair_kernels_pip_spec_is_shell_quoted():
 
     assert '"kernels<0.15"' in source
     assert " --break-system-packages kernels<0.15" not in source
+
+
+def test_sglang_native_dependency_diagnosis_is_exposed_to_browser():
+    source = DIAGNOSIS_JS.read_text(encoding="utf-8")
+
+    assert r"Python\.h" in source
+    assert r"libnuma\.so\.1" in source
+    assert "SGLang native dependencies" in source
+    assert "libnuma-dev python3.12-dev build-essential" in source
+    assert "sglang-kernel" in source