From 3f96a0df024005d0165b0f338dff248b35bcfe1c Mon Sep 17 00:00:00 2001
From: chenjw28 <792430652@qq.com>
Date: Fri, 12 Jun 2026 10:56:36 +0800
Subject: [PATCH] x

---
 docker/README.md                      | 22 ++++++++++++++++++++++
 docker/scripts/entrypoint.sh          |  2 +-
 docker/scripts/patch_vllm_platform.py | 22 ++++++++++++++++++++--
 3 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/docker/README.md b/docker/README.md
index c1013f1..66ce819 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -406,6 +406,28 @@ docker compose build --no-cache gradio
 docker compose up -d --force-recreate
 ```
 
+**Q: 任务失败并提示 `Please install vllm to use the vllm-async-engine backend`**
+
+这通常不是简单的“没安装 vllm”，而是任务进程里 `import vllm` 或 `from vllm.platforms import current_platform` 失败，MinerU 将真实异常包装成了这句提示。先在容器内直接诊断：
+
+```bash
+docker compose exec gradio bash -lc '/opt/mineru_venv/bin/python - <<"PY"
+import traceback
+try:
+    import torch
+    import vllm
+    from vllm.platforms import current_platform
+    print("torch:", torch.__version__, "hip:", torch.version.hip)
+    print("vllm:", vllm.__version__)
+    print("platform:", type(current_platform).__name__, "is_rocm:", current_platform.is_rocm())
+except Exception:
+    traceback.print_exc()
+    raise
+PY'
+```
+
+当前入口脚本会在服务启动前执行同样的 vLLM 导入验证；如果验证失败，容器会直接退出并在 `docker compose logs gradio` 中显示真实 traceback，而不是等任务执行时才报泛化错误。
+
 **Q: 构建时 `ninja` 被 kill（exit 137）**
 
 内存不足。将 Dockerfile 中 `ninja -j4` 改为 `ninja -j2` 或 `ninja -j1`，或给 Docker 分配更多内存。
diff --git a/docker/scripts/entrypoint.sh b/docker/scripts/entrypoint.sh
index 8bec7f8..275efe1 100644
--- a/docker/scripts/entrypoint.sh
+++ b/docker/scripts/entrypoint.sh
@@ -11,7 +11,7 @@ echo "[entrypoint] running patches..."
 
 # vllm 平台补丁
 if [ -f ${SCRIPTS_DIR}/patch_vllm_platform.py ]; then
-    ${VENV}/bin/python ${SCRIPTS_DIR}/patch_vllm_platform.py || echo "[entrypoint] patch_vllm_platform.py failed (non-fatal)"
+    ${VENV}/bin/python ${SCRIPTS_DIR}/patch_vllm_platform.py
 fi
 
 # MinerU 推理补丁
diff --git a/docker/scripts/patch_vllm_platform.py b/docker/scripts/patch_vllm_platform.py
index 1775545..96dbdc9 100644
--- a/docker/scripts/patch_vllm_platform.py
+++ b/docker/scripts/patch_vllm_platform.py
@@ -2,10 +2,11 @@
 """vllm 平台检测补丁
 
 问题 1：amdsmi 不可用时 platform 回退到 torch.version.hip
-问题 2：rocm.py 中 logger.warning_once() 导致循环导入
+问题 2：rocm.py 中 logger.warning_once() 导致循环导入（默认不再改写；仅保留为显式开关）
 """
 
 import os
+import traceback
 
 VLLM_DIR = '/opt/vllm/vllm'
 
@@ -33,7 +34,16 @@ def patch6_init_platform_fallback():
 
 
 def patch7_rocm_break_import_cycle():
-    """补丁 7：platforms/rocm.py —— logger.warning_once → sys.stderr.write"""
+    """补丁 7：platforms/rocm.py —— logger.warning_once → sys.stderr.write
+
+    这个补丁会直接改写 vLLM 源码中的函数调用。部分 vLLM 版本里
+    logger.warning_once(...) 参数不一定兼容 sys.stderr.write(...)，改写后可能
+    导致 import vllm / import vllm.platforms.rocm 失败。MinerU 会把这种导入失败
+    包装成 "Please install vllm"，因此默认禁用，只在显式设置环境变量时启用。
+    """
+    if os.environ.get('VLLM_PATCH_ROCM_WARNING_ONCE') != '1':
+        print('Patch 7: skipped (set VLLM_PATCH_ROCM_WARNING_ONCE=1 to enable).')
+        return
     f = os.path.join(VLLM_DIR, 'platforms', 'rocm.py')
     c = open(f).read()
     old = 'logger.warning_once('
@@ -49,6 +59,14 @@ def patch7_rocm_break_import_cycle():
 def main():
     patch6_init_platform_fallback()
     patch7_rocm_break_import_cycle()
+    try:
+        import vllm
+        from vllm.platforms import current_platform
+        print(f'vllm runtime import OK: {vllm.__version__}, platform={type(current_platform).__name__}')
+    except Exception:
+        print('ERROR: vllm runtime import failed after platform patches:')
+        traceback.print_exc()
+        raise
     print('vllm platform patches done.')