Mini-SGLang

一个轻量级但高性能的大语言模型推理框架。

---

Mini-SGLang 是 SGLang 的精简实现，旨在揭开现代 LLM 服务系统的复杂面纱。它拥有约 5,000 行 Python 代码 的简洁代码库，既是一个功能强大的推理引擎，也是研究人员和开发者透明的参考实现。

✨ 核心特性

• 高性能：通过先进的优化技术，达到业界领先的吞吐量和延迟。
• 轻量且易读：代码结构清晰、模块化，并配有完整的类型注解，易于理解和修改。
• 高级优化：
  • 基数缓存：在不同请求之间复用共享前缀的 KV 缓存。
  • 分块预填充：降低长上下文推理时的峰值内存占用。
  • 重叠调度：利用 GPU 计算隐藏 CPU 调度开销。
  • 张量并行：支持跨多张 GPU 的扩展推理。
  • 优化内核：集成 FlashAttention 和 FlashInfer，以实现最高效率。
  • ...

🚀 快速入门

⚠️ 平台支持：Mini-SGLang 目前仅支持 Linux（x86_64 和 aarch64）。Windows 和 macOS 由于依赖于 Linux 特有的 CUDA 内核（sgl-kernel、flashinfer），暂不支持。建议在 Windows 上使用 WSL2，或通过 Docker 实现跨平台兼容性。

1. 环境设置

推荐使用 uv 进行快速可靠的安装（注意 uv 不会与 conda 冲突）。

# 创建虚拟环境（推荐 Python 3.10+）
uv venv --python=3.12
source .venv/bin/activate

前提条件：Mini-SGLang 依赖于 JIT 编译的 CUDA 内核。请确保已安装 NVIDIA CUDA 工具包，且其版本与显卡驱动版本一致。可通过 nvidia-smi 检查显卡驱动的 CUDA 兼容性。

2. 安装

直接从源码安装 Mini-SGLang：

git clone https://github.com/sgl-project/mini-sglang.git
cd mini-sglang && uv venv --python=3.12 && source .venv/bin/activate
uv pip install -e .

💡 在 Windows (WSL2) 上安装

由于 Mini-SGLang 需要 Linux 特有的依赖项，Windows 用户应使用 WSL2：

1. 安装 WSL2（如尚未安装）：

   # 以管理员身份运行 PowerShell
   wsl --install
   

2. 在 WSL2 上安装 CUDA：

   • 参照 NVIDIA 的 WSL2 CUDA 指南
   • 确保 Windows 显卡驱动支持 WSL2

3. 在 WSL2 中安装 Mini-SGLang：

   # 在 WSL2 终端中
   git clone https://github.com/sgl-project/mini-sglang.git
   cd mini-sglang && uv venv --python=3.12 && source .venv/bin/activate
   uv pip install -e .
   

4. 从 Windows 访问：服务器将在 http://localhost:8000 提供服务，Windows 浏览器和应用程序均可访问。

🐳 使用 Docker 运行

前提条件：

• Docker
• NVIDIA 容器工具包

1. 构建 Docker 镜像：

   docker build -t minisgl .
   

2. 运行服务器：

   docker run --gpus all -p 1919:1919 \
       minisgl --model Qwen/Qwen3-0.6B --host 0.0.0.0
   

3. 交互式 Shell 模式运行：

   docker run -it --gpus all \
       minisgl --model Qwen/Qwen3-0.6B --shell
   

4. 使用 Docker 卷保存缓存数据（推荐用于加速后续启动）：

   docker run --gpus all -p 1919:1919 \
       -v huggingface_cache:/app/.cache/huggingface \
       -v tvm_cache:/app/.cache/tvm-ffi \
       -v flashinfer_cache:/app/.cache/flashinfer \
       minisgl --model Qwen/Qwen3-0.6B --host 0.0.0.0
   

3. 在线推理服务

只需一条命令即可启动兼容 OpenAI API 的推理服务。

# 在单张 GPU 上部署 Qwen/Qwen3-0.6B
python -m minisgl --model "Qwen/Qwen3-0.6B"

# 在 4 张 GPU 上使用张量并行部署 meta-llama/Llama-3.1-70B-Instruct，监听端口 30000
python -m minisgl --model "meta-llama/Llama-3.1-70B-Instruct" --tp 4 --port 30000

服务器启动后，您可以通过 curl 或任何兼容 OpenAI API 的客户端发送请求。

4. 交互式 Shell

通过添加 --shell 参数，可以直接在终端中与模型对话。

python -m minisgl --model "Qwen/Qwen3-0.6B" --shell

您还可以使用 /reset 清除聊天历史。

基准测试

离线推理

更多详情请参阅 bench.py。设置 MINISGL_DISABLE_OVERLAP_SCHEDULING=1 可进行重叠调度的消融实验。

测试配置：

• 硬件：1x H200 GPU。
• 模型：Qwen3-0.6B、Qwen3-14B
• 总请求数：256 条序列
• 输入长度：随机采样自 100–1024 个 token
• 输出长度：随机采样自 100–1024 个 token

在线推理

更多详情请参阅 benchmark_qwen.py。

测试配置：

• 硬件：4x H200 GPU，通过 NVLink 连接。
• 模型：Qwen3-32B
• 数据集：Qwen 跟踪日志，回放前 1000 条请求。

启动命令如下：

# Mini-SGLang
python -m minisgl --model "Qwen/Qwen3-32B" --tp 4 --cache naive

# SGLang
python3 -m sglang.launch_server --model "Qwen/Qwen3-32B" --tp 4 \
    --disable-radix --port 1919 --decode-attention flashinfer

注意：如果从 HuggingFace 下载模型时遇到网络问题，可尝试使用 --model-source modelscope 从 ModelScope 下载：

python -m minisgl --model "Qwen/Qwen3-32B" --tp 4 --model-source modelscope

📚 更多信息

• 详细特性：探索所有可用功能和命令行参数。
• 系统架构：深入了解 Mini-SGLang 的设计与数据流。

Mini-SGLang 快速上手指南

环境准备

• 系统要求：仅支持 Linux (x86_64/aarch64)。Windows 用户需使用 WSL2，macOS 不支持。
• 前置依赖：
  • NVIDIA CUDA Toolkit（版本需与显卡驱动匹配，通过 nvidia-smi 检查）
  • Python 3.12+（推荐）

安装步骤

1. 安装 uv（推荐，避免与 conda 冲突）：

   pip install uv
   

2. 创建并激活虚拟环境：

   uv venv --python=3.12
   source .venv/bin/activate
   

3. 克隆仓库并安装：

   git clone https://github.com/sgl-project/mini-sglang.git
   cd mini-sglang
   uv pip install -e .
   

   Windows 用户：请在 WSL2 中执行上述步骤（WSL2 安装指南）。

基本使用

1. 启动在线服务（最简示例）：

   python -m minisgl --model "Qwen/Qwen3-0.6B"
   

   • 服务默认运行在 http://localhost:8000，兼容 OpenAI API。
   • 国内加速：如下载模型慢，添加 --model-source modelscope：

     python -m minisgl --model "Qwen/Qwen3-0.6B" --model-source modelscope
     

2. 交互式聊天：

   python -m minisgl --model "Qwen/Qwen3-0.6B" --shell
   

   • 在终端直接对话，使用 /reset 清除历史。