x

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 分配更多内存。