MiaAI-Lab/Qwen3.8-27B-SGLang-DGX-Spark

本仓库的功能

MiaAI‑Lab 提供即开即用的 Docker 脚本，可在 NVIDIA DGX Spark（aarch64，128 GB 统一内存）上使用 SGLang 高性能推理引擎部署 Qwen 3.8 27B 大型语言模型。该仓库包含：

• 三种推测解码引擎（EAGLE/MTP、DSpark、DFlash2）的 Docker 启动脚本，均针对 DGX Spark 硬件进行了调优。
• 一组小型基准测试工具（bench/），可复现 README 中报告的性能数据。
• 配置辅助工具（.env.sample、启动脚本），可调整上下文长度（最高达 1 M 令牌）、并发数（最高 10 个并发请求）、量化模式和 CPU 绑定。
• 作者机器上实测获得最佳延迟/吞吐量的硬件特定标志文档。

简而言之，该仓库是用于在专用 NVIDIA 服务器上高速运行 270 亿参数 LLM 的 部署套件。

---

哪些人可能使用它

目标用户	为何重要
机器学习工程师 / 研究运维人员：需要在 NVIDIA DGX Spark 硬件上对 Qwen 3.8 27B 进行基准测试或部署。
AI 产品团队：构建聊天代理、代码助手或工具调用服务，需要在单个强大节点上实现低延迟推理。
性能调优爱好者：希望获得 SGLang 的推测解码器（EAGLE/MTP、DSpark、DFlash2）与硬件特定设置（CPU-set 绑定、FP8 KV 缓存、内存占比调优）结合使用的具体示例。
下游应用开发者（如 RAG 流水线、自主代理）：可通过标准 OpenAI 兼容的 /v1/models 端点调用已部署的模型。

---

快速入门

1. 克隆仓库并复制示例环境文件：

   git clone https://github.com/MiaAI-Lab/Qwen3.8-27B-SGLang-DGX-Spark.git
   cd Qwen3.8-27B-SGLang-DGX-Spark
   cp .env.sample .env   # 创建带有默认设置的 .env
   

2. 确保 Docker 可见 GPU（已安装 NVIDIA Container Toolkit），并导出 Hugging Face 访问令牌为 HF_TOKEN。
3. 选择一个引擎并启动：

   # 默认：DSpark（代码类工作负载最快）
   ./start-dspark.sh
   
   # 可选：经典 EAGLE/MTP 推测解码
   ./start.sh
   
   # 可选：DFlash2（适合短对话和长文写作）
   ./start-dflash.sh
   

   脚本会拉取对应的 SGLang 镜像，将 Qwen 检查点下载到 ./.cache/huggingface（约 24 GB），并启动监听端口 8888 的容器。
4. 测试服务器：

   curl http://127.0.0.1:8888/v1/models
   

   应返回 JSON 响应，确认模型名 qwen3.8-27b-sglang 已准备就绪。
5. 使用完毕后停止服务：

   ./stop.sh
   

---

可配置项（配置）

变量（在 .env 或 shell 环境中）	默认值	控制内容
YARN	0	启用 YaRN rope 缩放以支持超过 262 K 令牌的上下文。超过原生窗口长度时必须设为 1。
CONTEXT_LENGTH	262144	令牌窗口大小（262 K – 1 M）。更大的窗口需要 YARN=1。
MAX_CONCURRENT_REQUESTS	10	同时 API 调用数量；也决定 GDN 状态池大小。
QUANT	nvfp4	选择检查点变体：nvfp4（密集 BF16 头）、nvfp4-fp4（打包 FP4 头）、fp8（FP8 权重）、bf16（完整 BF16）。均在 128 GB 内存预算内。
CPUSET	5-9,15-19	将容器绑定到 DGX Spark 的 10 个高性能 Cortex‑X5 核心，保留较慢的 A725 核心空闲。
SPEC_STEPS / SPEC_TOPK / SPEC_DRAFT	3 / 1 / 4	EAGLE/MTP 推测解码器的调优参数。DSpark 和 DFlash2 引擎忽略这些。
CHUNKED_PREFILL	8192	预填充块大小；在该硬件上增大值可改善首个令牌延迟。
DF_TARGET（仅 DFlash2）	nvfp4	选择 DFlash2 引擎加载的检查点（nvfp4、nvfp4-fp4 或 bf16）。
IMAGE	引擎特定（见脚本）	若有本地构建的变体，可指向自定义 SGLang 镜像。

所有变量均可在命令行中覆盖，例如：

MAX_CONCURRENT_REQUESTS=5 CONTEXT_LENGTH=524288 YARN=1 ./start.sh

新值需在执行 ./stop.sh && ./start… 循环后生效。

---

实测性能数据（作者 DGX Spark 上测量）

引擎	典型延迟（秒） – 代码片段	典型延迟 – 长文	典型延迟 – 短对话
DSpark（block-7）	~51.5 s（代码最快）	~18 s（慢于 MTP）	~23 s（良好）
EAGLE/MTP	~34.5 s	~24 s（长文最佳）	~21 s
DFlash2（NVFP4）	~50.9 s	~25.4 s	29 – 67 s（修复令牌计数后流式短对话胜出）

所有数据均为 bench/ 中基准脚本的墙时时间，包含预填充、解码及任何推测起草开销。内存使用量约为 24 GB（密集 BF16 头）+ 约 2.5 GB（草稿模型）；打包 FP4 变体可节省数 GB。

---

何时选择哪个引擎

目标	推荐脚本	原因
调用工具或需要代码生成的代理	./start-dspark.sh	DSpark 的 block-7 草稿在代码密集型提示下提供最佳解码速度。
长文写作（论文、报告）	./start.sh（EAGLE/MTP）	MTP 的推测解码在大段连续输出中表现最佳。
通用聊天或混合负载	./start-dflash.sh	DFlash2 在代码与聊天性能间取得平衡，修复令牌计数后短对话延迟优于其他。

---

更多详细信息查阅位置

• 本机实测 – README 中的一张表格，列出作者观察到的所有延迟、内存占比和令牌计数限制。
• bench/ 脚本 – ndec.py、bench.sh、ab-image.sh 可在自有硬件上复现 A/B 对比。
• docs/ – 包含头脑风暴笔记（brainstorms/*.md）和长期计划（plans/*.md）。

---

TL;DR

若您拥有 NVIDIA DGX Spark 并需以低延迟运行 27 B Qwen 模型，此仓库提供：

• 三种领先 SGLang 推测解码器的预配置 Docker 镜像。
• 自动拉取模型、应用最优硬件标志并暴露 OpenAI 兼容 API 的脚本。
• 简单控制项，可将上下文长度扩展至 1 M 令牌，支持最多 10 个并发请求。

只需复制 .env.sample，选择关心的引擎，运行对应 start-*.sh，即可在几分钟内部署 Qwen 3.8 27B。