x

docker/ISSUES.md

@@ -499,7 +499,7 @@ print('device_type:', repr(current_platform.device_type))
   docker compose build && docker compose --profile gradio up -d --force-recreate
   ```
 
-### 7.4 模型架构 inspect 失败（待解决）
+### 7.4 模型架构 inspect 失败（triton 版本过旧）
 
 **现象**：7.1、7.2 修复后（`platform=RocmPlatform`），解析任务在 vllm 加载模型阶段失败：
 
@@ -509,19 +509,77 @@ print('device_type:', repr(current_platform.device_type))
   failed to be inspected. Please check the logs for more details.
 ```
 
-启动日志同时有：
+**真实根因**（gradio 的 ClickException 吞掉了 vllm 内部栈，需手动复现 `inspect_model_cls` 捕获完整 traceback）：
 
 ```
-WARNING [config.py:71] Support for Transformers v4 is deprecated. 
-The Transformers v4 codepath will become unmaintained in vLLM v0.22.0 
-... Please upgrade to Transformers v5: pip install --upgrade transformers
+inspect_model_cls(['Qwen2VLForConditionalGeneration'])
+  → import vllm.model_executor.models.qwen2_vl
+    → from ...attention import MMEncoderAttention
+      → fa_utils.py: from flash_attn import flash_attn_varlen_func
+        → flash_attn_interface.py: from aiter.ops.triton... import flash_attn_2
+          → aiter/__init__.py: from .ops.attention import *
+            → aiter/ops/attention.py: from aiter.ops.triton.gluon.pa_decode_gluon import ...
+              → gluon/__init__.py:
+RuntimeError: aiter gluon kernels require triton>=3.6.0, found 3.5.1
 ```
 
-**初步判断**：transformers 版本与 vllm main 的模型 inspect 逻辑不兼容。矛盾在于：
-- vllm 提示升级到 transformers v5
-- `mineru[pipeline]` 依赖锁死 `transformers<5.0.0,>=4.57.3`（强制 v4）
+**vllm main 的 Qwen2VL 加载链一路 import 到 aiter，aiter 的 gluon kernels 要求 triton ≥ 3.6.0，但 `import triton` 实际得到 3.5.1。** 整个 import 链断裂 → Qwen2VL 类加载失败 → `failed to be inspected`。
 
-待诊断（确认实际版本、Qwen2VL 是否在 transformers 注册表、inspect 真实报错）后再补最终方案。
+> **排查弯路**：曾怀疑是 vllm registry 访问 `model_config.model_impl`（transformers v5 字段，v4 缺失）导致，写了补丁 9 给 10 处访问加 `getattr` 兜底。但补丁 9 应用后 7.4 依旧——说明 `model_impl` **不是**根因。补丁 9 无害（vllm ModelConfig 有该属性时透传，transformers config 缺时兜底 "auto"），保留，但真正解决 7.4 的是 triton 版本。
+
+**triton 版本现状**（`pip list` 有 4 个相关包，容易误判）：
+
+| 包 | 版本 | 说明 |
+|---|---|---|
+| `pytorch-triton-rocm` | 3.5.1 | torch 依赖的 ROCm triton，**`import triton` 实际加载的是这个** |
+| `triton` | 3.7.0 | 原生 triton（满足 ≥3.6.0，但被 pytorch-triton-rocm 覆盖） |
+| `triton-rocm` | 3.6.0 | 另一个 ROCm triton |
+| `triton_kernels` | 1.0.0+amd | 缺 `matmul_ogs` 模块（非致命） |
+
+**关键陷阱**：`import triton` 返回 3.5.1 而非 pip 显示的 3.7.0——因为 `pytorch-triton-rocm` 把自己注册成 `triton` 顶层包，覆盖了原生 `triton`。所以 pip list 看版本会误导，必须看 `import triton; triton.__version__`。
+
+**解决**：设环境变量 `AITER_USE_SYSTEM_TRITON=1`。aiter 的 gluon `__init__.py` 检测逻辑：
+
+```python
+if int(os.environ.get("AITER_USE_SYSTEM_TRITON", 0)):
+    warnings.warn(...)   # 仅警告，import 继续
+else:
+    raise RuntimeError(...)   # 阻断 import
+```
+
+设 1 后 RuntimeError 降级为 warning，import 链不再阻断，Qwen2VL 类正常加载。**这是 aiter 官方提供的逃生口**。
+
+固化进 `docker-compose.yml`（gradio / worker0 / worker1 都要加）：
+
+```yaml
+environment:
+  - AITER_USE_SYSTEM_TRITON=1
+```
+
+**验证**：
+
+```bash
+docker exec -e AITER_USE_SYSTEM_TRITON=1 mineru-gradio /opt/mineru_venv/bin/python -c "
+from vllm.config.model import ModelConfig
+from vllm.model_executor.models.registry import ModelRegistry
+mp='/opt/models/modelscope/models/OpenDataLab/MinerU2.5-Pro-2605-1.2B'
+cfg = ModelConfig(model=mp, tokenizer=mp, trust_remote_code=True, dtype='auto', seed=0)
+print(ModelRegistry.inspect_model_cls(cfg.architectures, cfg))
+"
+# 期望输出：(..., 'Qwen2VLForConditionalGeneration')
+```
+
+**遗留隐患**（非阻塞）：
+- `AITER_USE_SYSTEM_TRITON=1` 只是不阻断 import，triton 3.5.1 实际可能不支持 gluon kernel 的某些 API。实测 Qwen2VL 推理跑通（142 页 PDF 解析成功），说明推理路径未真正调用 gluon kernel——只是 import 链被牵连。
+- 若未来某模型真用 gluon kernel 且 triton 3.5.1 API 不够，需真正升级 ROCm triton 到 ≥3.6.0（注意 `pytorch-triton-rocm` 与 torch 版本绑定，升级有风险，见 1.5 节）。
+
+### 7.5 `_version.py` 与 force-recreate 的坑
+
+**现象**：`docker compose up -d --force-recreate` 后，`Invalid version: 'dev'`（7.1）复发。
+
+**原因**：热修复时用 `docker exec` 写入 `/opt/vllm/vllm/_version.py`，这只存在于**运行容器的可写层**，不在镜像层。`--force-recreate` 重建容器后丢失。补丁 6/7/9 是 entrypoint 跑脚本应用的，会自动重应用；但 `_version.py` 是 Dockerfile 阶段 8b 写的，**镜像里如果 Dockerfile 没改，重建即丢**。
+
+**解决**：把 `_version.py` 写入固化进 Dockerfile 阶段 8b（见 6.1/7.1 节）。固化前用 `docker restart`（保留容器层），不要 `--force-recreate`。
 
 ---