Add reproducible DGX Spark deployment for Qwen3.8 Flash Next NVFP4

docs/architecture.md

@@ -0,0 +1,24 @@
+# PLE 与统一内存
+
+GB10 的 CPU/GPU 共用统一内存。把 PLE 固定放到 CPU 内存仍会占用同一内存池。
+本模型约 47.7 GiB 的 PLE 表不需要每一步完整读取，因此映射原始 safetensors，按索引收集所需行。
+Linux 页缓存保留访问过的数据，未命中才访问 SSD。此方式不重新量化、不截断表、不修改哈希。
+
+`patches/spark_ngram_adapter.py` 适配 nightly 新的 ngram_embedding 接口，
+复用上游哈希/缩放和 vendor 的 mmap/custom-op；只支持此 FP8 PLE 布局和 ETP=1。
+它修改内部类，因此不能随意升级基础镜像。失败时应修复版本兼容，不能吞掉异常继续运行。
+
+实测默认配置模型权重占 76.36 GiB，KV 缓存约 14.52 GiB。
+主机空闲时 used 约 102 GiB、buff/cache 约 19 GiB、available 约 18 GiB、free 约 1.6 GiB。
+这些是不同口径，available 包含可回收缓存，不能与 buff/cache 相加；也不能认定所有缓存都是 PLE。
+主机约 227 MiB 的 swap 存量不等同于持续发生 swap I/O。
+
+增大 `GPU_MEMORY_UTILIZATION` 主要增加 KV 空间，适合更多并发或长输入，并不直接提高单流解码速度。
+它会减少 PLE 页缓存空间。应比较 TTFT、tokens/s、排队时间、KV 使用率、页缺失和 swap I/O，
+而不是追求 100% 内存占用。社区默认同样为 0.80，但社区性能数字不是此配置的测试结果。
+
+完整 PLE 运算包含 GPU 同步，日志中的 op 总时长不能全部归因于磁盘；分析时应区分 gather 与 gpu-wait。
+当前使用 eager 执行，未开启 prefix caching，也没有采用社区可选的二次 FP8 量化或词表裁剪。
+
+来源：[社区方案](https://github.com/blazux/qwen3.8-Flash-DGX)、
+[Linux 内存指标](https://docs.kernel.org/filesystems/proc.html)。

docs/packaging-validation.md

@@ -0,0 +1,13 @@
+# 项目整理验证（2026-09-17）
+
+- 全部 Python 文件通过语法解析；全部 Shell 脚本通过 bash -n。
+- vendor/vllm_ple_mmap.py 的 SHA256 与部署时使用的文件一致。
+- Spark 上 docker compose config 验证默认及 baseline 两套配置成功。
+- 将两套配置展开后的 command、entrypoint 与原部署逐项比较，完全一致。
+- 新目录结构在 Spark 上成功 docker build，临时镜像为 local/qwen38-git-check:0bfc7a15。
+  构建使用已经核对的本地基础镜像 tag，没有重新拉取浮动 nightly。
+- 新版 smoke-test.py 对现有线上容器执行成功：算术 1.76 秒、中文回答 5.18 秒、工具调用 1.92 秒。
+- 检查 Git 待提交文件：不含 .env、密钥文件、原始日志、模型权重或原主机/代理地址。
+
+线上服务没有被重建。此轮验证覆盖项目构建、配置等价性与测试脚本；
+没有从空缓存重新下载 124 GiB 权重，也没有再次完整加载模型。

docs/provenance.md

@@ -0,0 +1,22 @@
+# 固定版本与来源
+
+- 模型：`nvidia/Qwen3.8-Flash-Next-NVFP4`
+- 模型 revision：`fc694b54fb0174e0913e6adf86691ef85a4ead47`
+- 基础镜像：`vllm/vllm-openai@sha256:c4392d76e3eec8983fa152651365158cb062e348fd40398963f499d5867b9e28`
+- 基础镜像源码 commit：`0bfc7a15d095fe83ecc82b50561a93c177fece2d`
+- 本地构建 tag：`local/qwen38-flash-spark:nightly-0bfc7a15`
+
+nightly 的包版本曾报告 `0.3.1.dev3+g0bfc7a15d`，因此使用镜像 digest/源码 commit 标识，
+不把它当作正式版 0.29.0。BASE_IMAGE override 仅用于已核对 digest 的本地镜像别名。
+
+## 第三方文件
+
+`vendor/vllm_ple_mmap.py` 原样获取自：
+https://raw.githubusercontent.com/blazux/qwen3.8-Flash-DGX/main/src/vllm_ple_mmap.py
+
+获取日期 2026-09-17。原 URL 使用 main，不是永久版本链接；本仓库保存文件本体，以下 hash 固定实际采用内容：
+
+`SHA256 02adb76b789f9fccf472e922e3be7b4b2a95962ae7d7c3eb99bfeac6052dccad`
+
+不要重新下载 main 后仍宣称是同一版本。许可证按获取时的文件保存在 vendor/LICENSE。
+适配层和 Dockerfile 是本次部署的本地改动，第三方 helper 未修改。

docs/troubleshooting.md

@@ -0,0 +1,37 @@
+# 故障排查与上游依据
+
+## 原 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 修改，没有搬用所有社区优化。

docs/validation.md

@@ -0,0 +1,36 @@
+# 验证记录
+
+日期：2026-09-17。硬件为单台 DGX Spark / GB10，ARM64，121 GiB 可见内存。
+系统 DGX OS 7.6，内核 7.0.0-1019-nvidia，驱动 580.173.02，驱动支持 CUDA 13.0。
+版本见 provenance.md；这不是可泛化到所有 nightly 或所有 GPU 的结果。
+
+## 原部署的实测结果
+
+| 配置/测试 | 结果 |
+|---|---|
+| 32K / 不启用 MTP / eager | 成功启动 |
+| 32K：17 × 19 | 323，3.66 秒，56 completion tokens |
+| 32K：中文解释天空颜色 | 正常，5.19 秒，81 completion tokens |
+| 262K 上限 / MTP 2 / eager | 成功启动，健康检查通过 |
+| MTP：17 × 19 | 323，2.40 秒，56 completion tokens |
+| MTP：中文解释天空颜色 | 正常，5.46 秒，150 completion tokens |
+| 自动工具调用 | get_weather，city=上海，约 2.25 秒 |
+| 局域网健康检查 | HTTP 200 |
+| 适配层 CUDA 测试 | PASS，逐字节 FP8 查表及缩放一致 |
+| 适配层 torch.compile 测试 | COMPILE_PASS |
+
+completion tokens 包括思考 token。以上是小样本验证，不是性能基准；不同回答长度不能直接比较速度。
+测试工具调用只检查模型产生的结构化调用，不访问真实天气服务。
+
+262K 配置日志：模型权重 76.36 GiB，KV 缓存 14.52 GiB，报告 524288 总 token 容量；
+后者不是“两个满长度请求已压测”的承诺。实际可用空间随运行环境变化。
+主模型选择 FLASHINFER_CUTLASS；FP8 MTP 选择 DEEPGEMM，实测推理成功。
+
+## 未验证
+
+- 完整 262144-token 请求及长时间高并发压力。
+- 多模态输入、完整模型 CUDA Graph 和 prefix caching。
+- 其他 GPU、其他模型 revision、其他 nightly、ETP > 1。
+- 重启机器后的恢复耗时（已设置 unless-stopped，但未为测试重启机器）。
+
+仓库整理后的构建/配置验证另记录于 packaging-validation.md。