企业官网建设流程全解析

DeepSeek-v4-Flash-DSpark-2x-DGX-Spark 是一套让两台 NVIDIA DGX Spark（GB10，TP=2）跑满 DeepSeek V4 Flash Vision-Exp 的开源 recipe：vLLM 张量并行、DSpark 投机解码、1M token 上下文、原生图片输入。整个部署的行为几乎全部由一个文件控制——.env.dspark，里面包含 40+ 个关键开关：并发槽位、思考深度、NCCL/RoCE 网络、JIT 缓存、十几个 opt-in 热修复。这篇指南带你快速读懂这些开关、看懂并发基准数据，并绕开新手最容易踩的坑。

上图是默认配置（MAX_NUM_SEQS=6、NVFP4 DS-MLA KV）下的实测并发基准：并发升到 c=6 时，聚合吞吐约 158–190 tok/s，TTFT 稳定在 1.3–2.4 s——这正是.env.dspark里那组默认值想帮你守住的平衡点。

一分钟上手：复制、改值、重启

cp .env.dspark.example .env.dspark # 复制模板 # 编辑 .env.dspark，至少填好集群地址与网卡名 ./prepare-dspark-model-cache.sh --yes # 拉权重 ./stop-deepseek-v4-flash-dspark.sh # 改完开关后先停 ./start-deepseek-v4-flash-dspark.sh # 再启动

模板文件.env.dspark.example自带逐行中文级注释；启动脚本每次都会把 head 节点的.env.dspark同步到 worker。官方开关矩阵见 README.md 的 “.env.dsparkswitches” 章节，Anemll 与 Stage-C 两套镜像的差异矩阵见 docs/ENVS.md。

⚠️ 铁律一：任何开关改动后都要./stop-…+./start-…重建两个 rank 的容器。docker compose restart会复用容器的可写层，已经打进去的补丁和旧环境变量不会被还原，等于“改了没生效”。

8 组核心配置速查表

下面按功能分组列出.env.dspark.example中最常用的开关（共 50+ 项，下表覆盖 40+ 关键项）。⭐ 为新手必须理解的核心项。

1️⃣ 集群与节点寻址

2️⃣ NCCL / RoCE 网络

💡 GB10 的 QSFP 口会枚举成两块虚拟网卡（2× PCIe Gen5 x4）。实测在NCCL_IB_HCA里同时列出两个控制器（如rocep1s0f0,rocep1s0f1），端到端吞吐可提升约 7.6%（1311→1410 tok/s 单流场景）——这是网络组里性价比最高的一个调优点。

3️⃣ 权重与模型缓存

4️⃣ 服务形态与并发（性能主战场）

5️⃣ API 与推理控制

才生效，避免空 content | |VLLM_PREFIX_CACHE_RETENTION_INTERVAL|4096| issue #26：SWA 前缀缓存检查点间距（256 的倍数） | |DSPARK_ENABLE_DSPARK_SWA_PREFIX|0| 修复 prefix cache 命中后草稿 SWA 缓存为空导致的截断退化 |

6️⃣ 热修复与实验开关（默认全关，按需开启）

7️⃣ 运行时缓存与 NCCL 透传

8️⃣ 启动器侧辅助项

调高 MAX_NUM_SEQS 前必读：并发与稳定性

.env.dspark.example里有一段很长的“STABILITY”注释，是本项目最值钱的血泪记录：

• 高吞吐数字是真实的：N=32 时 c=32 聚合约 325 tok/s（对照默认 N=6 的 c=6 约 160）；
• 但 issue #141 的卡顿按突发（burst）随机发生，某台机器干净跑 3 轮，第 4 轮死锁在稀疏 MLA decode 里（约 700–900 秒墙钟后RuntimeError("cancelled")）；
• 没有任何被测MAX_NUM_SEQS被证实“普遍安全”，改它只改变发生概率，不是修复；
• 更隐蔽的是轻度症状：短卡顿 → 批次取消 →静默截断（没有finish_reason、没有抢占、没有任何指标告警）。调高并发后，除了看重启，更要盯“缺失的finish_reason”。

默认的 48 行验证规模（N=6, k=6 补齐）恰好低于观测到的 64/65 行边界，这是默认值保守的由来。单用户长上下文场景，建议直接留在 2 节点默认档；想要 16 槽 + ~200 tok/s 聚合，看 docs/TP3.md 的三节点方案。

新手最容易踩的 7 个坑

1. 改了开关只docker compose restart。容器可写层里的补丁和旧环境变量不会还原。正确姿势永远是./stop-deepseek-v4-flash-dspark.sh && ./start-deepseek-v4-flash-dspark.sh。
2. 手填GPU_MEMORY_UTILIZATION或DSPARK_MODEL。前者由启动脚本从GPU_MEMORY_UTILIZATION_TEXT导出，手填会打架；后者只应通过ABLITERATED间接切换。
3. 在 Anemll 0.1.1 上开 Stage-C 的VLLM_DSPARK_*变量。它们只注册在 Stage-C overlay 里（recipe/overlay/vllm/envs.py），在默认镜像里只会打出Unknown vLLM environment variable detected警告然后被忽略——看起来“没生效”，其实根本没生效。要启用需换成 Stage-C 镜像并合并 docker-compose.stage-c.override.yml。
4. DEFAULT_THINKING=max却只给 512 的max_tokens。max 档的实测推理可吃掉 ~12.5k tokens，答案会整个没着落（finish_reason: length、content 为空）。要么调大 token 预算、要么降档、要么启用 #31 热修复发thinking_token_budget。
5. MTP_NUM_TOKENS设为 5。校验脚本 validate-dspark-config.sh 会拦住：Vision-Exp 要求 k≥5 且能被 3 整除，所以是 6、9……想跑 k=5 需同时开DSPARK_ENABLE_DSPARK_BLOCK_K=1。
6. 多 key 鉴权不加引号。启动脚本会source这个文件，空格分隔的多 key 不加引号时第二个 key 会被当命令执行。另注意：设了任一 key 变量后，文件里必须带补丁 patches/hotfix-vllm-redact-api-key-log.sh，且文件建议chmod 600——key 会出现在容器 argv 和docker inspect里，轮换必须 stop/start。
7. 两台机器的 RoCE 口名不同却只填 head。GB10 环网上 worker 的 facing port 常与 head 不同，记得用WORKER_NCCL_IB_HCA等 4 个变量单独指定；GID 索引默认自动解析（NCCL_IB_GID_AUTO=1），手动 pin 反而可能在重启后失效。

启动失败的排查顺序

./validate-dspark-config.sh # 1. 先校验 .env.dspark（模型、k 值、捕获规模等） ./status-deepseek-v4-flash-dspark.sh # 2. 看双节点健康状态 ./logs-deepseek-v4-flash-dspark.sh # 3. 拉双节点日志 ./smoke-deepseek-v4-flash-dspark.sh # 4. 冒烟请求

四个脚本都在仓库根目录，配合 docs/PATCHES.md 的热修复证据记录，基本能覆盖 90% 的启动问题。如果确认某个开关“改了没生效”，先问一句：我是不是只做了 restart 而不是 stop+start？

写在最后

.env.dspark的设计哲学很清楚：默认值就是被 A/B 过的安全档，注释就是实验记录。每个DSPARK_ENABLE_*开关背后都对应一份实测数据（如 docs/CLAUDE/ab-results-2026-09-03.md），开之前花两分钟读一下注释里的测量结论，比盲目试错快得多。先从默认档跑通 6 并发 ~160 tok/s 的基线，再按需逐个打开实验开关，是这条 2× DGX Spark 路线上最稳的调优节奏。