Set 128K eager baseline and organize deployment documentation

.gitignore

@@ -11,3 +11,8 @@ __pycache__/
 *.safetensors
 *.gguf
 .DS_Store
+archive/
+.local-state/
+*.nsys-rep
+*.sqlite
+*.gitbundle

README.md

@@ -2,7 +2,8 @@
 
 在单台 NVIDIA DGX Spark（GB10 / ARM64 / 128 GB 统一内存）上部署
 `nvidia/Qwen3.8-Flash-Next-NVFP4` 的可复现配置。
-来自 2026-09-17 的实际部署：262144 上下文上限、MTP 2 tokens、OpenAI 兼容 API。
+当前基线：131072 tokens 总上下文上限（输入 + 输出）、MTP 2 tokens、OpenAI 兼容 API。
+由 2026-09-17 至 18 日的实测选定；262K 已因主机 OOM 从默认配置撤下。
 优化版启用经验证的前缀缓存，保持 eager 执行；32K 重复前缀首个 token 约从 14.05 秒降至 1.34 秒。
 这里的首个 token 包括思考内容，完整回答不会因此保证快 10 倍。详见 [优化报告](docs/optimization-results.md)。
 PLE 查找表通过磁盘映射按需读取；原始模型权重未重新量化。
@@ -39,7 +40,7 @@ API 地址：`http://<Spark-IP>:8000/v1`；模型名：`qwen3.8-flash-next`。
 
 | 参数 | 设置 |
 |---|---|
-| 上下文上限 | 262144 tokens |
+| 上下文上限 | 131072 tokens，输入与输出合计 |
 | MTP | 2 speculative tokens |
 | 同时调度请求数 | 4 |
 | 批处理 token 上限 | 2048 |
@@ -64,9 +65,9 @@ docker compose stop vllm
 ./scripts/start.sh baseline
 ./scripts/wait.sh
 ./scripts/test.sh
-# 保持 262K + MTP，只关闭前缀缓存
+# 保持 128K + MTP，只关闭前缀缓存
 ./scripts/start.sh no-prefix
-# 恢复默认 262K + MTP + 前缀缓存
+# 恢复默认 128K + MTP + 前缀缓存
 ./scripts/start.sh
 ```
 
@@ -80,7 +81,7 @@ docker compose stop vllm
 ## 长上下文实测边界
 
 64K、128K 的单请求合成检索在 eager 和 CUDA Graph 下均通过；接近 260K 时两组均发生主机 OOM，
-即使 eager 返回正确答案也不能视为稳定通过。当前 262144 配置上限不是容量保证。
+即使 eager 返回正确答案也不能视为稳定通过。默认已限制为 131072；这仍不是多路满长并发或长期稳定性的保证。
 详见 [长上下文测试报告](docs/context262k-results.md)，其中包含资源证据、受影响服务和恢复记录。
 
 ## 文件说明
@@ -114,3 +115,8 @@ python3 scripts/summarize-benchmark.py benchmark.jsonl
 
 Nsight 已确认图重放生效，短回答约提升 4.5%；长输入预填充未被当前小尺寸图覆盖，
 GPU 活动本已接近连续。详见 [性能剖析报告](docs/cuda-graph-profile.md)，包括 PLE 等待/查表区分及原始证据摘要。
+
+## 运维与证据入口
+
+[当前基线与文档索引](docs/README.md) · [Spark 目录、归档与更新流程](docs/operations.md)。
+历史报告保留测试当时的 262K 参数；它们不覆盖当前默认配置。

compose.yaml

@@ -1,6 +1,7 @@
 name: qwen38-flash-dgx-spark
 services:
   vllm:
+    container_name: qwen38-flash-vllm
     image: local/qwen38-flash-spark:prefix-eager-0bfc7a15
     build:
       context: .
@@ -44,7 +45,7 @@ services:
         --tensor-parallel-size 1
         --dtype bfloat16 --kv-cache-dtype auto
         --gpu-memory-utilization ${GPU_MEMORY_UTILIZATION:-0.80}
-        --max-model-len 262144 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
+        --max-model-len 131072 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
         --enable-chunked-prefill --enable-prefix-caching
         --speculative-config '{"method":"mtp","num_speculative_tokens":2}'
         --enforce-eager --no-enable-flashinfer-autotune

configs/no-prefix.yaml

@@ -8,7 +8,7 @@ services:
         --tensor-parallel-size 1
         --dtype bfloat16 --kv-cache-dtype auto
         --gpu-memory-utilization ${GPU_MEMORY_UTILIZATION:-0.80}
-        --max-model-len 262144 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
+        --max-model-len 131072 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
         --enable-chunked-prefill --no-enable-prefix-caching
         --speculative-config '{"method":"mtp","num_speculative_tokens":2}'
         --enforce-eager --no-enable-flashinfer-autotune

docs/README.md

@@ -0,0 +1,19 @@
+# 当前基线与证据索引
+
+当前默认：单台 DGX Spark，固定 nightly / 模型 revision，**131072 总 tokens、eager、前缀缓存、MTP=2、BF16 KV、GPU memory=0.80**。
+128K 是输入与输出共享的上限。例如预留 2048 输出时，输入不能超过 129024 tokens。
+max_num_seqs=4 是调度上限，尚未验证四路同时满 128K；有限合成检索通过不等于长期稳定性保证。
+
+| 文档 | 用途 |
+|---|---|
+| [运维说明](operations.md) | Spark 项目结构、升级、归档与回退 |
+| [版本清单](provenance.md) | 固定镜像、模型、适配来源 |
+| [前缀缓存优化](optimization-results.md) | 缓存正确性与首次性能改善 |
+| [图复测](cuda-graph-retest.md) | 2048 输出预算下的小尺寸图验证 |
+| [容量边界](context262k-results.md) | 64K/128K 通过、接近 260K 主机 OOM |
+| [Nsight 剖析](cuda-graph-profile.md) | 图真实生效但约 4.5% 收益的证据 |
+| [迁移验收](main-baseline-migration.md) | 本次 main 整理及 Spark 128K 部署验证 |
+
+历史报告中的 262K、旧镜像和“恢复原配置”仅描述测试当时状态。
+默认配置及 no-prefix 回退现均为 128K；更保守的 baseline 回退为 32K、无 MTP。
+实验图覆盖仍是可选项，不自动作为生产默认。

docs/benchmark-method.md

@@ -1,6 +1,7 @@
 # 优化实验方法
 
-固定模型 revision、原始权重、MTP=2、BF16 KV、262144 上下文上限和 GPU memory=0.80。
+固定模型 revision、原始权重、MTP=2、BF16 KV 和 GPU memory=0.80。
+早期实验使用 262144 上限；当前默认上限为 131072。每轮结果以对应报告的实际参数为准。
 按 eager 基线 → piecewise CUDA Graph 实验 → eager+前缀缓存逐项比较，不把多项改动的收益混在一起。
 候选未通过启动、基准和 smoke test 前不作为默认配置。
 

docs/context262k-results.md

@@ -1,5 +1,7 @@
 # 长上下文测试：64K / 128K 通过，接近 262K 存在主机 OOM
 
+> 历史实验记录：保留当时的配置和恢复状态。当前部署已改为 128K eager 基线，见 [当前状态](README.md)。
+
 2026-09-17 开始测试，2026-09-18 完成恢复。方案见 [测试方案](context262k-plan.md)。
 
 **不能将当前配置的 262144 上限视为稳定可用容量。**

docs/cuda-graph-profile.md

@@ -1,5 +1,7 @@
 # CUDA Graph 性能剖析：图已生效，主要收益受 GPU 工作占比限制
 
+> 历史实验记录：保留当时的配置和恢复状态。当前部署已改为 128K eager 基线，见 [当前状态](README.md)。
+
 2026-09-18，Asia/Shanghai。方案与脚本见 [profile128k](../experiments/profile128k/plan.md)。
 
 CUDA Graph 确实被重放，并非参数失效。本轮短回答生成速度中位数由 **29.954 → 31.316 tokens/s（约 +4.5%）**，

docs/cuda-graph-retest.md

@@ -1,5 +1,7 @@
 # CUDA Graph 2048 输出预算复测（2026-09-17）
 
+> 历史实验记录：保留当时的配置和恢复状态。当前部署已改为 128K eager 基线，见 [当前状态](README.md)。
+
 结论：CUDA Graph + 前缀缓存通过本轮三次完整基准及前缀正确性、工具调用检查。
 长输入未再发生输出预算截断，短回答生成速度中位数约提升 4.4%。
 本次按复测范围执行，默认部署仍保留 eager + 前缀缓存。

docs/operations.md

@@ -0,0 +1,43 @@
+# Spark 运维
+
+以本 Git 仓库的 main 作为当前配置来源，不混用历史实验目录里的 Compose。
+
+## 目录约定
+
+- 项目根目录：Git 管理的 Compose、Dockerfile、脚本、文档。
+- `.env`：本机缓存路径、已有 API key 文件路径、代理；权限 0600，不提交 Git。
+- `runtime-cache/`：原有编译缓存，保留挂载路径；不提交 Git。
+- `archive/<时间>/legacy/`：整理前的部署脚本、Compose 和日志，只用于追溯。
+- `archive/<时间>/experiments/`：历史实验及原始 Nsight trace；目录 0700。
+- `archive/<时间>/tmp/`：本任务遗留的临时打包和检查文件。
+- `.local-state/`：本机迁移、健康检查、资源与部署提交记录；目录 0700。
+- 模型权重和 API key 继续使用原外部路径，不复制进仓库。
+
+归档不是现用配置。旧 Compose 的相对路径依赖原目录，不能直接从 archive 启动。
+原始 trace 可能含进程参数，不对外分享、不提交 Git。
+
+## 更新与验证
+
+```bash
+git status --short
+git pull --ff-only origin main
+# 不随意拉取新的 nightly。更新镜像须先核实固定版本并构建。
+./scripts/start.sh
+./scripts/wait.sh
+./scripts/test.sh
+./scripts/test-prefix.sh
+```
+
+若 Spark 没有 Gitea 凭据，可由已登录的工作站传输 `git bundle`，在 Spark fetch 本地 bundle 后 fast-forward main。
+不要把工作站 token 写进 Spark 的 Git remote；remote 始终使用不含凭据的仓库 URL。
+启动和重载约需 10–13 分钟，会中断当前请求。
+
+## 回退
+
+`./scripts/start.sh no-prefix`：保留 128K + MTP，关闭前缀缓存。
+`./scripts/start.sh baseline`：32K、无 MTP 的较保守配置。
+回退后同样执行 wait 和 smoke 检查。实验图配置位于 experiments/graph，当前也限制为 128K。
+不要把历史 262K 配置当成稳定回退。
+
+日常看 `/proc/meminfo` 的 MemAvailable 和 `/proc/vmstat` 的 oom_kill 增量，不能只看容器 healthy。
+测试时监控脚本的停止阈值只提供尽力保护。业务输出预算必须包含思考 tokens。

docs/optimization-results.md

@@ -1,5 +1,7 @@
 # 优化结果：采用 eager + 前缀缓存
 
+> 历史实验记录：保留当时的配置和恢复状态。当前部署已改为 128K eager 基线，见 [当前状态](README.md)。
+
 2026-09-17，单台 DGX Spark / GB10，固定模型与镜像版本不变。
 最终启用前缀缓存及两处 Mamba 块对齐修正；保持原始权重、BF16 KV、MTP=2、
 262144 上下文、GPU 内存比例 0.80、并发 4、batch token 上限 2048、eager 执行。

docs/packaging-validation.md

@@ -1,5 +1,7 @@
 # 项目整理验证（2026-09-17）
 
+> 历史实验记录：保留当时的配置和恢复状态。当前部署已改为 128K eager 基线，见 [当前状态](README.md)。
+
 - 全部 Python 文件通过语法解析；全部 Shell 脚本通过 bash -n。
 - vendor/vllm_ple_mmap.py 的 SHA256 与部署时使用的文件一致。
 - Spark 上 docker compose config 验证默认及 baseline 两套配置成功。

docs/validation.md

@@ -1,5 +1,7 @@
 # 验证记录
 
+> 历史实验记录：保留当时的配置和恢复状态。当前部署已改为 128K eager 基线，见 [当前状态](README.md)。
+
 日期：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 的结果。
@@ -26,7 +28,7 @@ completion tokens 包括思考 token。以上是小样本验证，不是性能
 后者不是“两个满长度请求已压测”的承诺。实际可用空间随运行环境变化。
 主模型选择 FLASHINFER_CUTLASS；FP8 MTP 选择 DEEPGEMM，实测推理成功。
 
-## 未验证
+## 当时未验证（后续进展见文档索引）
 
 - 完整 262144-token 请求及长时间高并发压力。
 - 多模态输入、完整模型 CUDA Graph 和 prefix caching。

experiments/graph/compose.prefix.yaml

@@ -12,7 +12,7 @@ services:
         --tensor-parallel-size 1
         --dtype bfloat16 --kv-cache-dtype auto
         --gpu-memory-utilization ${GPU_MEMORY_UTILIZATION:-0.80}
-        --max-model-len 262144 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
+        --max-model-len 131072 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
         --enable-chunked-prefill --enable-prefix-caching
         --speculative-config '{"method":"mtp","num_speculative_tokens":2}'
         --compilation-config '{"mode":3,"cudagraph_mode":"PIECEWISE","splitting_ops":["vllm::unified_attention_with_output","vllm::unified_mla_attention_with_output","vllm::mamba_mixer2","vllm::mamba_mixer","vllm::short_conv","vllm::qwen4_exp_ple_short_conv","vllm::qwen4_exp_qsa_with_output","vllm::linear_attention","vllm::qwen_gdn_attention_core","vllm::qwen_gdn_attention_core_fused_norm_packed","vllm::gdn_attention_core_xpu","vllm::olmo_hybrid_gdn_full_forward","vllm::sparse_attn_indexer","vllm::rocm_aiter_sparse_attn_indexer","vllm::deepseek_v4_attention","vllm::hpc_rope_norm_forward","vllm::unified_kv_cache_update","vllm::unified_mla_kv_cache_update","vllm::spark_ple_lookup"],"cudagraph_capture_sizes":[1,2,4,8,12]}' --no-enable-flashinfer-autotune

experiments/graph/compose.yaml

@@ -12,7 +12,7 @@ services:
         --tensor-parallel-size 1
         --dtype bfloat16 --kv-cache-dtype auto
         --gpu-memory-utilization ${GPU_MEMORY_UTILIZATION:-0.80}
-        --max-model-len 262144 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
+        --max-model-len 131072 --max-num-seqs ${MAX_NUM_SEQS:-4} --max-num-batched-tokens 2048
         --enable-chunked-prefill --no-enable-prefix-caching
         --speculative-config '{"method":"mtp","num_speculative_tokens":2}'
         --compilation-config '{"mode":3,"cudagraph_mode":"PIECEWISE","splitting_ops":["vllm::unified_attention_with_output","vllm::unified_mla_attention_with_output","vllm::mamba_mixer2","vllm::mamba_mixer","vllm::short_conv","vllm::qwen4_exp_ple_short_conv","vllm::qwen4_exp_qsa_with_output","vllm::linear_attention","vllm::qwen_gdn_attention_core","vllm::qwen_gdn_attention_core_fused_norm_packed","vllm::gdn_attention_core_xpu","vllm::olmo_hybrid_gdn_full_forward","vllm::sparse_attn_indexer","vllm::rocm_aiter_sparse_attn_indexer","vllm::deepseek_v4_attention","vllm::hpc_rope_norm_forward","vllm::unified_kv_cache_update","vllm::unified_mla_kv_cache_update","vllm::spark_ple_lookup"],"cudagraph_capture_sizes":[1,2,4,8,12]}' --no-enable-flashinfer-autotune