Mini-SGLang 实战指南从零部署 OpenAI 兼容的高性能 LLM 推理服务【免费下载链接】mini-sglangA compact implementation of SGLang, designed to demystify the complexities of modern LLM serving systems.项目地址: https://gitcode.com/GitHub_Trending/mi/mini-sglangMini-SGLang 是 SGLang 的一个紧凑实现用约 5000 行 Python 代码构建出一套完整可用的 LLM 推理与 Serving 系统目标是去神秘化现代 LLM serving 的复杂性。本文以仓库 README.md 为主线结合 docs/features.md、docs/structures.md 与源码实现系统讲解 Mini-SGLang 的安装部署、在线服务、交互式 Shell、全部命令行参数、核心优化机制Radix Cache、Chunked Prefill、Overlap Scheduling、Tensor Parallelism、CUDA Graph以及内部系统架构读完即可独立完成从克隆仓库到多 GPU 集群部署、压测与消融实验的完整闭环。一、Mini-SGLang 是什么Mini-SGLang 是一个轻量级但高性能的大语言模型推理框架其定位非常明确它是 SGLang 的紧凑复刻实现代码量约5000 行 Python在提供可用推理引擎能力的同时也作为研究者与开发者理解现代 LLM serving 系统的透明参考实现。核心设计理念可以概括为三点高性能High Performance通过多项高级优化达到有竞争力的吞吐与延迟表现轻量且可读Lightweight Readable代码库干净、模块化、全程类型注解易于理解与二次修改优化完备Advanced Optimizations内置 Radix Cache、Chunked Prefill、Overlap Scheduling、Tensor Parallelism、FlashAttention / FlashInfer 等现代 serving 系统标配优化手段。从工程结构看pyproject.toml项目以python/minisgl为源码根通过 setuptools 的package-dir { python}完成包映射支持 Python 3.10采用 MIT 许可证测试配置位于 tests/。二、核心特性一览README 明确列出的关键特性如下它们也是后续各章节展开的主线特性作用配置入口Radix Cache跨请求复用共享前缀的 KV cache减少冗余计算--cache radix默认Chunked Prefill长上下文服务中把长提示拆分为小块降低峰值显存、避免 OOM--max-prefill-length n默认 8192Overlap Scheduling将 CPU 调度开销与 GPU 计算重叠隐藏调度延迟默认开启可用环境变量MINISGL_DISABLE_OVERLAP_SCHEDULING1关闭做消融Tensor Parallelism跨多 GPU 扩展推理--tp n默认 1优化内核集成 FlashAttention 与 FlashInfer--attn fa,fi等CUDA Graph捕获并重放 CUDA Graph降低解码阶段 CPU launch 开销--cuda-graph-max-bs n默认开启这些特性并非停留在文档层面而是都有对应的源码与注册机制支撑详见后文高级配置参数详解与系统架构章节。三、环境准备与安装3.1 平台支持重要前提Mini-SGLang 目前仅支持 Linuxx86_64 与 aarch64。Windows 与 macOS 不受支持原因在于其依赖 Linux 专属的 CUDA 内核sgl-kernel、flashinfer。Windows 用户官方推荐两条替代路径使用WSL2使用Docker。3.2 使用 uv 创建虚拟环境项目推荐使用uv进行快速可靠的安装uv与conda不冲突# 创建虚拟环境推荐 Python 3.10以下以 3.12 为例 uv venv --python3.12 source .venv/bin/activate前置条件Mini-SGLang 依赖 JIT 编译的 CUDA 内核因此必须安装NVIDIA CUDA Toolkit且其版本需与驱动版本匹配。可用nvidia-smi查看驱动支持的 CUDA 能力。3.3 从源码安装git clone https://gitcode.com/GitHub_Trending/mi/mini-sglang cd mini-sglang uv venv --python3.12 source .venv/bin/activate uv pip install -e .从 pyproject.toml 可以看到运行时核心依赖包括torch2.10.0、transformers4.56.0, 4.57.3、flashinfer-python0.5.3、sgl_kernel0.3.17.post1、apache-tvm-ffi0.1.4、pyzmq、fastapi、uvicorn、msgpack、modelscope、openai、prompt_toolkit等开发依赖dev则包含pytest、black、flake8、mypy、ruff、pre-commit等质量工具。3.4 WindowsWSL2安装路径以管理员身份在 PowerShell 中执行wsl --install安装 WSL2在 WSL2 内按 NVIDIA 官方指南安装 CUDA并确保 Windows GPU 驱动支持 WSL2在 WSL2 终端内执行与 Linux 相同的安装流程见 3.3 节服务启动后Windows 浏览器与应用可通过http://localhost:8000访问具体端口以实际启动参数为准默认见下文 5.1 节。3.5 使用 Docker仓库根目录提供了 Dockerfile前置依赖为 Docker 与 NVIDIA Container Toolkit。构建镜像docker build -t minisgl .启动在线服务docker run --gpus all -p 1919:1919 \ minisgl --model Qwen/Qwen3-0.6B --host 0.0.0.0启动交互式 Shelldocker run -it --gpus all \ minisgl --model Qwen/Qwen3-0.6B --shell挂载持久化缓存卷推荐可显著加速后续启动JIT 编译与模型缓存HuggingFace、tvm-ffi、flashinfer建议落盘复用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四、快速开始在线服务4.1 单条命令启动 OpenAI 兼容服务Mini-SGLang 的入口为python -m minisgl对应源码 python/minisgl/main.py其仅做一件事调用launch_server()。以下是 README 中的两个典型示例# 单 GPU 部署 Qwen/Qwen3-0.6B python -m minisgl --model Qwen/Qwen3-0.6B # 4 卡 Tensor Parallelism 部署 Llama-3.1-70B-Instruct监听 30000 端口 python -m minisgl --model meta-llama/Llama-3.1-70B-Instruct --tp 4 --port 30000服务启动后即可使用标准curl或任意 OpenAI 兼容客户端发起请求。4.2 服务端点与请求示例在线服务基于 FastAPI 实现见 python/minisgl/server/api_server.py提供以下端点POST /v1/chat/completions标准对话补全端点兼容 OpenAI Chat Completions 协议POST /v1健康检查GET/POST/HEAD/OPTIONS 均返回{status: ok}GET /v1/models列出当前加载的模型POST /generateMini-SGLang 自有的简易生成端点返回 SSE 流。请求体模型OpenAICompletionRequest支持字段包括model、prompt、messages、max_tokens默认 16、temperature默认 1.0、top_k默认 -1、top_p默认 1.0、n、stream、stop、presence_penalty、frequency_penalty、ignore_eos。注意当前SamplingParams实际透传的是ignore_eos、max_tokens、temperature、top_k、top_p等参数源码中留有 TODO 注释说明更多采样参数待支持。服务同时支持流式SSE与非流式两种响应模式。4.3 模型下载源切换如果从 HuggingFace 下载模型遇到网络问题可改用 ModelScope 源python -m minisgl --model Qwen/Qwen3-32B --tp 4 --model-source modelscope该逻辑在 python/minisgl/server/args.py 中实现当--model-source modelscope且模型路径不是本地目录时调用modelscope.snapshot_download下载若配合--dummy-weight则会忽略权重文件*.bin、*.safetensors、*.pt、*.ckpt。五、交互式 Shell 模式对于演示与调试场景Mini-SGLang 提供交互式 Shell直接在终端输入提示词模型实时生成回复并自动维护聊天历史以保持上下文。python -m minisgl --model Qwen/Qwen3-0.6B --shellShell 内可用命令/reset清空聊天历史开启新会话/exit或 Ctrl-D退出。从源码看python/minisgl/server/api_server.py 中的shell()Shell 基于prompt_toolkit实现支持命令自动补全每一轮对话都会把历史消息组装为messages列表发给服务端采样参数由环境变量控制SHELL_MAX_TOKENS、SHELL_TOP_K、SHELL_TOP_P、SHELL_TEMPERATURE见 python/minisgl/env.py。另外在启动解析时args.py--shell会自动把cuda_graph_max_bs与max_running_req强制设为 1、并静默输出以保证交互体验。六、高级配置参数详解源码级所有命令行参数都在 python/minisgl/server/args.py 中解析配置对象继承链为ServerArgs - SchedulerConfig - EngineConfig见 python/minisgl/scheduler/config.py 与 python/minisgl/engine/config.py。执行python -m minisgl --help可查看完整帮助。下表整理自源码默认值与 README/docs 说明参数默认值说明--model-path/--model必填模型权重路径本地目录或 HuggingFace repo ID--dtypeauto可选auto/float16/bfloat16/float32auto对 FP32/FP16 模型用 FP16、BF16 模型用 BF16--tensor-parallel-size/--tp-size1张量并行度--max-running-requests256最大并发运行请求数--max-seq-len-overrideNone覆盖最大序列长度--memory-ratio0.9用于 KV cache 的 GPU 显存比例--dummy-weight关闭测试用随机权重跳过真实权重加载--disable-pynccl关闭禁用 PyNCCL 张量并行通信默认启用use_pyncclTrue--host127.0.0.1服务监听地址--port1919服务监听端口--cuda-graph-max-bs/--graphNoneCUDA Graph 捕获的最大 batch设为0关闭该特性--num-tokenizer/--tokenizer-count0Tokenizer 进程数0表示与 Detokenizer 共享--max-prefill-length/--max-extend-length8192Chunked Prefill 单块最大 token 数--num-pagesNone覆盖 KV cache 最大页数--page-size1系统页大小--attention-backend/--attnauto注意力后端传两个值如fa,fi则前为 prefill、后为 decode--model-sourcehuggingface可选huggingface/modelscope--cache-typeradixKV cache 管理策略可选radix/naive--moe-backendautoMoE 后端可选值见SUPPORTED_MOE_BACKENDS--shell-mode关闭以 Shell 模式运行下面逐一深入这些参数背后的机制。6.1 Chunked Prefill长上下文防 OOMChunked Prefill 源自 Sarathi-Serve 论文提出的思路默认开启。它把长提示在 prefill 阶段拆分为更小的 chunk显著降低峰值显存避免长上下文服务中的 Out-Of-MemoryOOM。块大小由--max-prefill-length n配置默认 8192。注意把n设得非常小如 128不推荐会明显损害性能。源码中max_extend_tokens同时作为max_forward_len返回scheduler/config.py即单次前向的最大长度直接约束调度器切块粒度。6.2 Page Size分页管理单元通过--page-size指定系统的分页大小默认 1。页是 KV cache 池MHAKVCache分配的最小单元。需要特别留意的是某些注意力后端会覆盖用户设置的页大小例如trtllm后端只支持页大小 16、32、64。6.3 Attention 后端prefill 与 decode 可异构Mini-SGLang 集成了三种高性能注意力内核faFlashAttentionfiFlashInfertrtllmTensorRT-LLM 的 FMHA。它支持prefill 与 decode 使用不同后端以最大化效率。例如在 NVIDIA Hopper GPU 上默认组合是 prefill 用 FlashAttention 3、decode 用 FlashInfer。通过--attn指定传一个值如--attn fa表示两个阶段都用它传两个值如--attn fa,fi时第一个用于 prefill、第二个用于 decode。源码实现印证了这一点python/minisgl/attention/init.pySUPPORTED_ATTENTION_BACKENDS注册表注册了trtllm、fi、fa三个后端工厂create_attention_backend解析,分隔的混合后端——当两个后端不同时构造HybridBackend(p_backend, d_backend)相同时退化为单一后端并给出告警日志。6.4 CUDA Graph压低解码 launch 开销为最小化解码阶段的 CPU 启动开销Mini-SGLang 支持捕获并重放 CUDA Graph默认开启。捕获的最大 batch 由--cuda-graph-max-bs n设置n为None默认根据 GPU 显存自动调优n 0关闭该特性交互式 Shell 模式下自动被设为 1。6.5 Radix Cache前缀复用继承 SGLang 的原始设计Mini-SGLang 用Radix Cache基数树缓存管理 KV cache从而跨请求复用共享前缀减少冗余计算。默认启用可通过--cache naive切换为朴素缓存管理策略。注册机制见 python/minisgl/kvcache/init.pySUPPORTED_CACHE_MANAGER注册了naiveNaivePrefixCache与radixRadixPrefixCache两种管理器KV cache 池统一由create_kvcache_pool创建MHAKVCache目前仅支持 MHA 结构代码注释注明 MLA 等变体为待办项。6.6 Overlap Scheduling调度与计算重叠为进一步降低 CPU 开销Mini-SGLang 采用 NanoFlow 论文提出的overlap scheduling技术把 CPU 侧调度开销与 GPU 计算重叠提升系统整体吞吐。该特性默认开启在离线评测中可用环境变量MINISGL_DISABLE_OVERLAP_SCHEDULING1关闭用于对照消融实验。6.7 Tensor Parallelism 与 PyNCCL--tp n指定张量并行度将模型权重切分到多张 GPU 上协同推理详见下一章系统架构。并行通信默认使用PyNCCLuse_pyncclTrue可用--disable-pynccl关闭每个 TP rank 通过DistributedInfo(rank, world_size)描述身份python/minisgl/distributed/info.pyZMQ 地址通过tcp://127.0.0.1:{port1}建立分布式控制面见 args.py 的distributed_addr。6.8 显存与 KV cache 容量控制--memory-ratio 0.9KV cache 最多占用 90% 的 GPU 显存默认值来自 engine/config.py--num-pages显式覆盖 KV cache 的最大页数替代按显存自动估算--max-running-requests 256限制并发运行请求数间接控制显存峰值。七、系统架构与请求生命周期7.1 多进程架构Mini-SGLang 被设计为分布式系统由多个独立进程协作完成推理服务。核心组件包括API Server用户入口提供 OpenAI 兼容 API如/v1/chat/completions接收提示并返回生成文本Tokenizer Worker把输入文本转换为模型可理解的 token 数字序列Detokenizer Worker把模型产出的 token 数字序列还原为可读文本Scheduler Worker核心工作进程。多 GPU 场景下每张 GPU 对应一个 Scheduler Worker称为一个TP Rank负责该 GPU 上的计算与资源分配。组件间通信采用ZeroMQZMQ传递控制消息GPU 间重张量数据交换使用NCCL经由torch.distributed/ PyNCCL。启动逻辑在 python/minisgl/server/launch.py 中launch_server()解析参数后以spawn方式按world_size启动 N 个 Scheduler 子进程命名minisgl-TP{i}-scheduler、1 个 Detokenizer 进程以及num_tokenizer个 Tokenizer 进程并通过 multiprocessingack_queue等待所有子进程就绪后才对外提供服务。ZMQ IPC 地址统一形如ipc:///tmp/minisgl_{0..4}.pid{pid}带 PID 后缀避免多实例冲突。7.2 请求生命周期8 步README/docs 给出的请求流转如下用户发送请求到API ServerAPI Server将请求转发给TokenizerTokenizer把文本转成 token发送给SchedulerRank 0SchedulerRank 0将请求广播给其他所有 Scheduler多 GPU 时所有 Scheduler调度请求并触发各自本地的Engine计算下一个 tokenSchedulerRank 0收集输出 token发送给DetokenizerDetokenizer将 token 转成文本送回API ServerAPI Server把结果流式返回给用户。7.3 代码组织minisgl包源码位于python/minisgl模块职责划分清晰详见 docs/structures.md模块职责minisgl.core核心数据结构Req、Batch请求状态、Context全局推理上下文、SamplingParams采样参数minisgl.distributed张量并行的 all-reduce / all-gather 接口与DistributedInfoTP 身份信息minisgl.layersTP 支持的模型基础构件linear、layernorm、embedding、RoPE 等共享minisgl.layers.base基类minisgl.modelsLlama、Qwen3 等模型实现HuggingFace 权重加载与切分工具minisgl.attention注意力后端接口与 FlashAttention / FlashInfer 实现由AttentionLayer调用minisgl.kvcacheKV cache 池与管理器接口实现MHAKVCache、NaiveCacheManager、RadixCacheManagerminisgl.utils工具集日志、ZMQ 封装等minisgl.engineEngine类单进程 TP worker管理模型、上下文、KV cache、注意力后端与 CUDA Graph 重放minisgl.messageAPI Server / Tokenizer / Detokenizer / Scheduler 间 ZMQ 消息定义全部支持自动序列化minisgl.schedulerScheduler类运行于每个 TP worker 进程管理对应Enginerank 0 负责与 tokenizer/detokenizer 通信minisgl.serverCLI 参数定义、launch_server子进程编排、FastAPI 前端/v1/chat/completions等minisgl.tokenizertokenize_worker处理 tokenization 与 detokenization 请求minisgl.llmLLM类Python 侧直连接口便于脚本化调用minisgl.kernel自定义 CUDA 内核经tvm-ffi做 Python 绑定与 JIT 接口minisgl.benchmark基准测试工具其中minisgl.llm.LLMpython/minisgl/llm/llm.py是离线推理的便捷入口继承Scheduler并设置offline_modeTrue提供generate(prompts, sampling_params)方法接受字符串或 token 列表返回{text: ..., token_ids: ...}字典列表适合在脚本内做批量推理。八、支持的模型Mini-SGLang 目前支持以下稠密模型架构Llama-3 系列Qwen-3 系列含 MoE 变体Qwen-2.5 系列。模型实现位于 python/minisgl/models/包括llama.py、qwen2.py、qwen3.py、qwen3_moe.py等register.py维护架构到实现的注册映射weight.py负责 HuggingFace 权重加载与 TP 切分。从源码结构看模型定义与 layersTP 支持的基础算子层、moeMoE 实现支持--moe-backend选择存在清晰的分层依赖关系。九、Benchmark 实测配置README 提供了离线与在线两套可复现的基准测试配置。9.1 离线推理Offline脚本benchmark/offline/bench.py另有 bench_wildchat.py。硬件1x H200 GPU模型Qwen3-0.6B、Qwen3-14B请求总量256 条序列输入长度100–1024 token 随机采样输出长度100–1024 token 随机采样。消融实验设置MINISGL_DISABLE_OVERLAP_SCHEDULING1可关闭 overlap scheduling评估其对吞吐的影响。9.2 在线推理Online脚本benchmark/online/bench_qwen.py另有 bench_simple.py。硬件4x H200 GPUNVLink 互联模型Qwen3-32B数据集Qwen 在线使用轨迹qwen_traceA_blksz_16.jsonl重放前 1000 条请求。启动命令与 SGLang 对照# 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提示--cache naive用于关闭 radix 前缀缓存从而与--disable-radix的 SGLang 配置对齐保证对比公平性。十、进一步探索docs/features.md所有可用特性与命令行参数的完整说明docs/structures.md系统架构与数据流、请求生命周期的深入讲解源码入口python/minisgl/server/launch.py、python/minisgl/server/args.py、python/minisgl/server/api_server.py测试用例tests/ 覆盖核心调度、缓存分配、内核与序列化等模块性能脚本benchmark/offline/bench.py、benchmark/online/bench_qwen.py。按 README 的定位Mini-SGLang 的价值不仅在于开箱即用的推理能力更在于它把 SGLang 这类大型 serving 系统最关键的机制——分页 KV cache、前缀复用、分块 prefill、混合注意力后端、CUDA Graph、调度-计算重叠、张量并行——浓缩进 5000 行可读代码中。对希望深入理解现代 LLM serving 系统、或需要一套可快速二次开发推理框架的研究者与工程师而言从本文的部署与参数章节入手再结合 docs/structures.md 的模块导览逐层阅读源码是一条高效的学习路径。【免费下载链接】mini-sglangA compact implementation of SGLang, designed to demystify the complexities of modern LLM serving systems.项目地址: https://gitcode.com/GitHub_Trending/mi/mini-sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Mini-SGLang 实战指南：从零部署 OpenAI 兼容的高性能 LLM 推理服务
Mini-SGLang 实战指南从零部署 OpenAI 兼容的高性能 LLM 推理服务【免费下载链接】mini-sglangA compact implementation of SGLang, designed to demystify the complexities of modern LLM serving systems.项目地址: https://gitcode.com/GitHub_Trending/mi/mini-sglangMini-SGLang 是 SGLang 的一个紧凑实现用约 5000 行 Python 代码构建出一套完整可用的 LLM 推理与 Serving 系统目标是去神秘化现代 LLM serving 的复杂性。本文以仓库 README.md 为主线结合 docs/features.md、docs/structures.md 与源码实现系统讲解 Mini-SGLang 的安装部署、在线服务、交互式 Shell、全部命令行参数、核心优化机制Radix Cache、Chunked Prefill、Overlap Scheduling、Tensor Parallelism、CUDA Graph以及内部系统架构读完即可独立完成从克隆仓库到多 GPU 集群部署、压测与消融实验的完整闭环。一、Mini-SGLang 是什么Mini-SGLang 是一个轻量级但高性能的大语言模型推理框架其定位非常明确它是 SGLang 的紧凑复刻实现代码量约5000 行 Python在提供可用推理引擎能力的同时也作为研究者与开发者理解现代 LLM serving 系统的透明参考实现。核心设计理念可以概括为三点高性能High Performance通过多项高级优化达到有竞争力的吞吐与延迟表现轻量且可读Lightweight Readable代码库干净、模块化、全程类型注解易于理解与二次修改优化完备Advanced Optimizations内置 Radix Cache、Chunked Prefill、Overlap Scheduling、Tensor Parallelism、FlashAttention / FlashInfer 等现代 serving 系统标配优化手段。从工程结构看pyproject.toml项目以python/minisgl为源码根通过 setuptools 的package-dir { python}完成包映射支持 Python 3.10采用 MIT 许可证测试配置位于 tests/。二、核心特性一览README 明确列出的关键特性如下它们也是后续各章节展开的主线特性作用配置入口Radix Cache跨请求复用共享前缀的 KV cache减少冗余计算--cache radix默认Chunked Prefill长上下文服务中把长提示拆分为小块降低峰值显存、避免 OOM--max-prefill-length n默认 8192Overlap Scheduling将 CPU 调度开销与 GPU 计算重叠隐藏调度延迟默认开启可用环境变量MINISGL_DISABLE_OVERLAP_SCHEDULING1关闭做消融Tensor Parallelism跨多 GPU 扩展推理--tp n默认 1优化内核集成 FlashAttention 与 FlashInfer--attn fa,fi等CUDA Graph捕获并重放 CUDA Graph降低解码阶段 CPU launch 开销--cuda-graph-max-bs n默认开启这些特性并非停留在文档层面而是都有对应的源码与注册机制支撑详见后文高级配置参数详解与系统架构章节。三、环境准备与安装3.1 平台支持重要前提Mini-SGLang 目前仅支持 Linuxx86_64 与 aarch64。Windows 与 macOS 不受支持原因在于其依赖 Linux 专属的 CUDA 内核sgl-kernel、flashinfer。Windows 用户官方推荐两条替代路径使用WSL2使用Docker。3.2 使用 uv 创建虚拟环境项目推荐使用uv进行快速可靠的安装uv与conda不冲突# 创建虚拟环境推荐 Python 3.10以下以 3.12 为例 uv venv --python3.12 source .venv/bin/activate前置条件Mini-SGLang 依赖 JIT 编译的 CUDA 内核因此必须安装NVIDIA CUDA Toolkit且其版本需与驱动版本匹配。可用nvidia-smi查看驱动支持的 CUDA 能力。3.3 从源码安装git clone https://gitcode.com/GitHub_Trending/mi/mini-sglang cd mini-sglang uv venv --python3.12 source .venv/bin/activate uv pip install -e .从 pyproject.toml 可以看到运行时核心依赖包括torch2.10.0、transformers4.56.0, 4.57.3、flashinfer-python0.5.3、sgl_kernel0.3.17.post1、apache-tvm-ffi0.1.4、pyzmq、fastapi、uvicorn、msgpack、modelscope、openai、prompt_toolkit等开发依赖dev则包含pytest、black、flake8、mypy、ruff、pre-commit等质量工具。3.4 WindowsWSL2安装路径以管理员身份在 PowerShell 中执行wsl --install安装 WSL2在 WSL2 内按 NVIDIA 官方指南安装 CUDA并确保 Windows GPU 驱动支持 WSL2在 WSL2 终端内执行与 Linux 相同的安装流程见 3.3 节服务启动后Windows 浏览器与应用可通过http://localhost:8000访问具体端口以实际启动参数为准默认见下文 5.1 节。3.5 使用 Docker仓库根目录提供了 Dockerfile前置依赖为 Docker 与 NVIDIA Container Toolkit。构建镜像docker build -t minisgl .启动在线服务docker run --gpus all -p 1919:1919 \ minisgl --model Qwen/Qwen3-0.6B --host 0.0.0.0启动交互式 Shelldocker run -it --gpus all \ minisgl --model Qwen/Qwen3-0.6B --shell挂载持久化缓存卷推荐可显著加速后续启动JIT 编译与模型缓存HuggingFace、tvm-ffi、flashinfer建议落盘复用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四、快速开始在线服务4.1 单条命令启动 OpenAI 兼容服务Mini-SGLang 的入口为python -m minisgl对应源码 python/minisgl/main.py其仅做一件事调用launch_server()。以下是 README 中的两个典型示例# 单 GPU 部署 Qwen/Qwen3-0.6B python -m minisgl --model Qwen/Qwen3-0.6B # 4 卡 Tensor Parallelism 部署 Llama-3.1-70B-Instruct监听 30000 端口 python -m minisgl --model meta-llama/Llama-3.1-70B-Instruct --tp 4 --port 30000服务启动后即可使用标准curl或任意 OpenAI 兼容客户端发起请求。4.2 服务端点与请求示例在线服务基于 FastAPI 实现见 python/minisgl/server/api_server.py提供以下端点POST /v1/chat/completions标准对话补全端点兼容 OpenAI Chat Completions 协议POST /v1健康检查GET/POST/HEAD/OPTIONS 均返回{status: ok}GET /v1/models列出当前加载的模型POST /generateMini-SGLang 自有的简易生成端点返回 SSE 流。请求体模型OpenAICompletionRequest支持字段包括model、prompt、messages、max_tokens默认 16、temperature默认 1.0、top_k默认 -1、top_p默认 1.0、n、stream、stop、presence_penalty、frequency_penalty、ignore_eos。注意当前SamplingParams实际透传的是ignore_eos、max_tokens、temperature、top_k、top_p等参数源码中留有 TODO 注释说明更多采样参数待支持。服务同时支持流式SSE与非流式两种响应模式。4.3 模型下载源切换如果从 HuggingFace 下载模型遇到网络问题可改用 ModelScope 源python -m minisgl --model Qwen/Qwen3-32B --tp 4 --model-source modelscope该逻辑在 python/minisgl/server/args.py 中实现当--model-source modelscope且模型路径不是本地目录时调用modelscope.snapshot_download下载若配合--dummy-weight则会忽略权重文件*.bin、*.safetensors、*.pt、*.ckpt。五、交互式 Shell 模式对于演示与调试场景Mini-SGLang 提供交互式 Shell直接在终端输入提示词模型实时生成回复并自动维护聊天历史以保持上下文。python -m minisgl --model Qwen/Qwen3-0.6B --shellShell 内可用命令/reset清空聊天历史开启新会话/exit或 Ctrl-D退出。从源码看python/minisgl/server/api_server.py 中的shell()Shell 基于prompt_toolkit实现支持命令自动补全每一轮对话都会把历史消息组装为messages列表发给服务端采样参数由环境变量控制SHELL_MAX_TOKENS、SHELL_TOP_K、SHELL_TOP_P、SHELL_TEMPERATURE见 python/minisgl/env.py。另外在启动解析时args.py--shell会自动把cuda_graph_max_bs与max_running_req强制设为 1、并静默输出以保证交互体验。六、高级配置参数详解源码级所有命令行参数都在 python/minisgl/server/args.py 中解析配置对象继承链为ServerArgs - SchedulerConfig - EngineConfig见 python/minisgl/scheduler/config.py 与 python/minisgl/engine/config.py。执行python -m minisgl --help可查看完整帮助。下表整理自源码默认值与 README/docs 说明参数默认值说明--model-path/--model必填模型权重路径本地目录或 HuggingFace repo ID--dtypeauto可选auto/float16/bfloat16/float32auto对 FP32/FP16 模型用 FP16、BF16 模型用 BF16--tensor-parallel-size/--tp-size1张量并行度--max-running-requests256最大并发运行请求数--max-seq-len-overrideNone覆盖最大序列长度--memory-ratio0.9用于 KV cache 的 GPU 显存比例--dummy-weight关闭测试用随机权重跳过真实权重加载--disable-pynccl关闭禁用 PyNCCL 张量并行通信默认启用use_pyncclTrue--host127.0.0.1服务监听地址--port1919服务监听端口--cuda-graph-max-bs/--graphNoneCUDA Graph 捕获的最大 batch设为0关闭该特性--num-tokenizer/--tokenizer-count0Tokenizer 进程数0表示与 Detokenizer 共享--max-prefill-length/--max-extend-length8192Chunked Prefill 单块最大 token 数--num-pagesNone覆盖 KV cache 最大页数--page-size1系统页大小--attention-backend/--attnauto注意力后端传两个值如fa,fi则前为 prefill、后为 decode--model-sourcehuggingface可选huggingface/modelscope--cache-typeradixKV cache 管理策略可选radix/naive--moe-backendautoMoE 后端可选值见SUPPORTED_MOE_BACKENDS--shell-mode关闭以 Shell 模式运行下面逐一深入这些参数背后的机制。6.1 Chunked Prefill长上下文防 OOMChunked Prefill 源自 Sarathi-Serve 论文提出的思路默认开启。它把长提示在 prefill 阶段拆分为更小的 chunk显著降低峰值显存避免长上下文服务中的 Out-Of-MemoryOOM。块大小由--max-prefill-length n配置默认 8192。注意把n设得非常小如 128不推荐会明显损害性能。源码中max_extend_tokens同时作为max_forward_len返回scheduler/config.py即单次前向的最大长度直接约束调度器切块粒度。6.2 Page Size分页管理单元通过--page-size指定系统的分页大小默认 1。页是 KV cache 池MHAKVCache分配的最小单元。需要特别留意的是某些注意力后端会覆盖用户设置的页大小例如trtllm后端只支持页大小 16、32、64。6.3 Attention 后端prefill 与 decode 可异构Mini-SGLang 集成了三种高性能注意力内核faFlashAttentionfiFlashInfertrtllmTensorRT-LLM 的 FMHA。它支持prefill 与 decode 使用不同后端以最大化效率。例如在 NVIDIA Hopper GPU 上默认组合是 prefill 用 FlashAttention 3、decode 用 FlashInfer。通过--attn指定传一个值如--attn fa表示两个阶段都用它传两个值如--attn fa,fi时第一个用于 prefill、第二个用于 decode。源码实现印证了这一点python/minisgl/attention/init.pySUPPORTED_ATTENTION_BACKENDS注册表注册了trtllm、fi、fa三个后端工厂create_attention_backend解析,分隔的混合后端——当两个后端不同时构造HybridBackend(p_backend, d_backend)相同时退化为单一后端并给出告警日志。6.4 CUDA Graph压低解码 launch 开销为最小化解码阶段的 CPU 启动开销Mini-SGLang 支持捕获并重放 CUDA Graph默认开启。捕获的最大 batch 由--cuda-graph-max-bs n设置n为None默认根据 GPU 显存自动调优n 0关闭该特性交互式 Shell 模式下自动被设为 1。6.5 Radix Cache前缀复用继承 SGLang 的原始设计Mini-SGLang 用Radix Cache基数树缓存管理 KV cache从而跨请求复用共享前缀减少冗余计算。默认启用可通过--cache naive切换为朴素缓存管理策略。注册机制见 python/minisgl/kvcache/init.pySUPPORTED_CACHE_MANAGER注册了naiveNaivePrefixCache与radixRadixPrefixCache两种管理器KV cache 池统一由create_kvcache_pool创建MHAKVCache目前仅支持 MHA 结构代码注释注明 MLA 等变体为待办项。6.6 Overlap Scheduling调度与计算重叠为进一步降低 CPU 开销Mini-SGLang 采用 NanoFlow 论文提出的overlap scheduling技术把 CPU 侧调度开销与 GPU 计算重叠提升系统整体吞吐。该特性默认开启在离线评测中可用环境变量MINISGL_DISABLE_OVERLAP_SCHEDULING1关闭用于对照消融实验。6.7 Tensor Parallelism 与 PyNCCL--tp n指定张量并行度将模型权重切分到多张 GPU 上协同推理详见下一章系统架构。并行通信默认使用PyNCCLuse_pyncclTrue可用--disable-pynccl关闭每个 TP rank 通过DistributedInfo(rank, world_size)描述身份python/minisgl/distributed/info.pyZMQ 地址通过tcp://127.0.0.1:{port1}建立分布式控制面见 args.py 的distributed_addr。6.8 显存与 KV cache 容量控制--memory-ratio 0.9KV cache 最多占用 90% 的 GPU 显存默认值来自 engine/config.py--num-pages显式覆盖 KV cache 的最大页数替代按显存自动估算--max-running-requests 256限制并发运行请求数间接控制显存峰值。七、系统架构与请求生命周期7.1 多进程架构Mini-SGLang 被设计为分布式系统由多个独立进程协作完成推理服务。核心组件包括API Server用户入口提供 OpenAI 兼容 API如/v1/chat/completions接收提示并返回生成文本Tokenizer Worker把输入文本转换为模型可理解的 token 数字序列Detokenizer Worker把模型产出的 token 数字序列还原为可读文本Scheduler Worker核心工作进程。多 GPU 场景下每张 GPU 对应一个 Scheduler Worker称为一个TP Rank负责该 GPU 上的计算与资源分配。组件间通信采用ZeroMQZMQ传递控制消息GPU 间重张量数据交换使用NCCL经由torch.distributed/ PyNCCL。启动逻辑在 python/minisgl/server/launch.py 中launch_server()解析参数后以spawn方式按world_size启动 N 个 Scheduler 子进程命名minisgl-TP{i}-scheduler、1 个 Detokenizer 进程以及num_tokenizer个 Tokenizer 进程并通过 multiprocessingack_queue等待所有子进程就绪后才对外提供服务。ZMQ IPC 地址统一形如ipc:///tmp/minisgl_{0..4}.pid{pid}带 PID 后缀避免多实例冲突。7.2 请求生命周期8 步README/docs 给出的请求流转如下用户发送请求到API ServerAPI Server将请求转发给TokenizerTokenizer把文本转成 token发送给SchedulerRank 0SchedulerRank 0将请求广播给其他所有 Scheduler多 GPU 时所有 Scheduler调度请求并触发各自本地的Engine计算下一个 tokenSchedulerRank 0收集输出 token发送给DetokenizerDetokenizer将 token 转成文本送回API ServerAPI Server把结果流式返回给用户。7.3 代码组织minisgl包源码位于python/minisgl模块职责划分清晰详见 docs/structures.md模块职责minisgl.core核心数据结构Req、Batch请求状态、Context全局推理上下文、SamplingParams采样参数minisgl.distributed张量并行的 all-reduce / all-gather 接口与DistributedInfoTP 身份信息minisgl.layersTP 支持的模型基础构件linear、layernorm、embedding、RoPE 等共享minisgl.layers.base基类minisgl.modelsLlama、Qwen3 等模型实现HuggingFace 权重加载与切分工具minisgl.attention注意力后端接口与 FlashAttention / FlashInfer 实现由AttentionLayer调用minisgl.kvcacheKV cache 池与管理器接口实现MHAKVCache、NaiveCacheManager、RadixCacheManagerminisgl.utils工具集日志、ZMQ 封装等minisgl.engineEngine类单进程 TP worker管理模型、上下文、KV cache、注意力后端与 CUDA Graph 重放minisgl.messageAPI Server / Tokenizer / Detokenizer / Scheduler 间 ZMQ 消息定义全部支持自动序列化minisgl.schedulerScheduler类运行于每个 TP worker 进程管理对应Enginerank 0 负责与 tokenizer/detokenizer 通信minisgl.serverCLI 参数定义、launch_server子进程编排、FastAPI 前端/v1/chat/completions等minisgl.tokenizertokenize_worker处理 tokenization 与 detokenization 请求minisgl.llmLLM类Python 侧直连接口便于脚本化调用minisgl.kernel自定义 CUDA 内核经tvm-ffi做 Python 绑定与 JIT 接口minisgl.benchmark基准测试工具其中minisgl.llm.LLMpython/minisgl/llm/llm.py是离线推理的便捷入口继承Scheduler并设置offline_modeTrue提供generate(prompts, sampling_params)方法接受字符串或 token 列表返回{text: ..., token_ids: ...}字典列表适合在脚本内做批量推理。八、支持的模型Mini-SGLang 目前支持以下稠密模型架构Llama-3 系列Qwen-3 系列含 MoE 变体Qwen-2.5 系列。模型实现位于 python/minisgl/models/包括llama.py、qwen2.py、qwen3.py、qwen3_moe.py等register.py维护架构到实现的注册映射weight.py负责 HuggingFace 权重加载与 TP 切分。从源码结构看模型定义与 layersTP 支持的基础算子层、moeMoE 实现支持--moe-backend选择存在清晰的分层依赖关系。九、Benchmark 实测配置README 提供了离线与在线两套可复现的基准测试配置。9.1 离线推理Offline脚本benchmark/offline/bench.py另有 bench_wildchat.py。硬件1x H200 GPU模型Qwen3-0.6B、Qwen3-14B请求总量256 条序列输入长度100–1024 token 随机采样输出长度100–1024 token 随机采样。消融实验设置MINISGL_DISABLE_OVERLAP_SCHEDULING1可关闭 overlap scheduling评估其对吞吐的影响。9.2 在线推理Online脚本benchmark/online/bench_qwen.py另有 bench_simple.py。硬件4x H200 GPUNVLink 互联模型Qwen3-32B数据集Qwen 在线使用轨迹qwen_traceA_blksz_16.jsonl重放前 1000 条请求。启动命令与 SGLang 对照# 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提示--cache naive用于关闭 radix 前缀缓存从而与--disable-radix的 SGLang 配置对齐保证对比公平性。十、进一步探索docs/features.md所有可用特性与命令行参数的完整说明docs/structures.md系统架构与数据流、请求生命周期的深入讲解源码入口python/minisgl/server/launch.py、python/minisgl/server/args.py、python/minisgl/server/api_server.py测试用例tests/ 覆盖核心调度、缓存分配、内核与序列化等模块性能脚本benchmark/offline/bench.py、benchmark/online/bench_qwen.py。按 README 的定位Mini-SGLang 的价值不仅在于开箱即用的推理能力更在于它把 SGLang 这类大型 serving 系统最关键的机制——分页 KV cache、前缀复用、分块 prefill、混合注意力后端、CUDA Graph、调度-计算重叠、张量并行——浓缩进 5000 行可读代码中。对希望深入理解现代 LLM serving 系统、或需要一套可快速二次开发推理框架的研究者与工程师而言从本文的部署与参数章节入手再结合 docs/structures.md 的模块导览逐层阅读源码是一条高效的学习路径。【免费下载链接】mini-sglangA compact implementation of SGLang, designed to demystify the complexities of modern LLM serving systems.项目地址: https://gitcode.com/GitHub_Trending/mi/mini-sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
