# 故障排查与上游依据

## 原 Qwen3.6 升级后启动失败

旧部署使用主模型 marlin、MTP triton，但 V2 runner 曾未正确应用 draft MoE backend。
对应修复：[vLLM #54788](https://github.com/vllm-project/vllm/pull/54788)，
[GB10 复现评论](https://github.com/vllm-project/vllm/pull/54788#issuecomment-5554777896)。
不能把所有 NVFP4/MTP 错误都归为同一问题；本项目 NVIDIA Flash Next 的 MTP 是 block FP8。
对应加载支持修复：[vLLM #55513](https://github.com/vllm-project/vllm/pull/55513)。
固定 nightly 已包含这些代码；本项目没有把主、草稿模型强制绑定同一 MoE backend。

## 模型下载超时

先确认 `.env` 中 MODEL_HTTP_PROXY / MODEL_HTTPS_PROXY 是否沿用了可用代理。
下载容器单独使用这些变量，HF 缓存写入主机；服务以 HF_HUB_OFFLINE=1 读取固定 revision。
不要为网络故障修改推理参数。已有权重需要位于正确的 HF snapshot 目录并具备完整 blob 链接。

## 权重加载慢

本模型约 123.57 GiB，首次主模型加载约 9 分钟，MTP 再约 1 分钟。
healthcheck 的 start_period 为 30 分钟。用 `docker compose logs -f vllm` 确认分片进度。
如果出现异常退出，先读堆栈；不要只依赖自动重启或盲目提高内存比例。

## 内存不足或变慢

先看主机 `free -h`、`vmstat 1`，再看服务日志的 KV 分配和 PLE gather 时间。
不要只看 Docker stats，也不要把 available 当作完全空闲。
确认没有旧模型或其他 GPU 容器并行运行。默认 0.80 留给页缓存的空间有实际用途。
必要时使用 `scripts/start.sh baseline` 回退，再逐项增加配置。

## 更新 nightly

不要只改镜像 tag。先核对 ngram_embedding 接口和两处 FLA 源码结构，重跑 adapter GPU 测试、
启动测试和实际问答。Dockerfile 对被替换的内容使用断言，接口变化应让构建失败以便审查。

社区适配来源：[blazux/qwen3.8-Flash-DGX](https://github.com/blazux/qwen3.8-Flash-DGX)。
本项目只使用其 mmap helper 和两项 FLA 修改，没有搬用所有社区优化。