1.1 SGLang 是什么：面向大模型推理与结构化生成的服务框架
我最初听到 SGLang 这个名字，以为它只是另一个大模型推理框架。后来在几个项目里用它部署聊天服务和批量生成任务，才慢慢理解它的定位。SGLang 全称是 Structured Generation Language，它把大模型推理服务和结构化生成能力打包在一起，目标是让开发者既能获得高吞吐，又能方便地控制输出格式。它不是一个模型，也不是简单的 API 封装，而是一套运行时和前端语言组合起来的服务框架。
从我的使用体验看，SGLang 最特别的地方是它把“生成”这件事看得很重。传统推理服务往往只关心把 token 吐出来，SGLang 会关心这些 token 如何组织成 JSON、如何遵循正则表达式、如何在多轮对话里复用缓存。它适合那些对输出结构有要求的场景，比如让模型返回固定字段的 JSON，或者按照模板生成报告。这种定位让它在 RAG 和 Agent 工作流里显得很顺手。
如果从团队协作角度说，SGLang 降低了后端和算法之间的沟通成本。算法同学可以用 Python 写生成逻辑，后端同学直接启动兼容 OpenAI 的服务。我们不用为了一个结构化输出单独写解析和重试代码，SGLang 运行时已经处理了约束解码。它像一个中间层，把模型能力以更可控的方式暴露给业务系统。
1.2 核心机制解析：RadixAttention、前缀缓存与连续批处理
我花了一些时间才搞懂 SGLang 的 RadixAttention 到底在做什么。简单说，它把注意力计算里的 KV 缓存用基数树管理起来，相同的前缀只存一份。多轮对话里，用户反复发同一个系统提示词，或者 RAG 场景里多个问题共享同一段检索文档，这些重复前缀就能被复用。以前每个请求都要重新算一遍，显存和时间都浪费了。
前缀缓存是 RadixAttention 带来的直接好处。我在测试多轮对话时发现，第二轮开始的响应速度明显比第一轮快。模型不需要重新编码历史对话，直接从缓存里读取 KV。连续批处理则是在时间维度上做优化，新请求可以随时加入正在运行的批次，不用等当前批次全部结束。这两者结合，让 GPU 利用率保持在高位，吞吐量比朴素实现高出一截。
从系统设计角度看，连续批处理对延迟和吞吐的平衡很关键。短请求不会被长请求拖住，长请求也不会在等待中空转。SGLang 的调度器会动态安排计算，让每个批次的 token 数量尽量饱满。我在压测时观察到，开启这些机制后，同样一张 A100 能支撑的并发会话数明显增加。这些机制不是孤立的，它们共同构成了 SGLang 高性能推理的底座。
1.3 关键特性：高吞吐推理、结构化输出、前端 DSL 与运行时
SGLang 的高吞吐推理给我留下很深印象。我们做过一个批量生成任务，几千条提示词同时提交，SGLang 能在可接受的时间内全部跑完。它支持张量并行、流水线并行，还能结合量化。对于需要大规模离线推理的团队，这种吞吐能力直接决定成本。我比较喜欢它的一点是，吞吐提升没有牺牲太多易用性，启动服务还是几条命令的事。
结构化输出是另一个让我愿意继续用的特性。通过前端 DSL，我可以写类似 gen 和 select 的语句，让模型按照指定格式生成。比如让模型从几个选项中选一个，或者生成符合 JSON Schema 的对象。运行时会把约束编译成有限状态机，在解码时屏蔽非法 token。这样得到的输出不需要额外解析，也不会出现格式错误导致下游系统崩溃。
前端 DSL 和运行时是配套的。DSL 负责描述生成流程，运行时负责高效执行。我可以用 Python 写复杂的控制流，比如循环、条件分支、并行生成，再交给 SGLang 运行时调度。它把“提示词工程”变成了“程序化生成”，对于 Agent 和复杂工作流特别有用。运行时还负责缓存、批处理和约束解码，开发者不用关心底层细节。
1.4 典型应用场景：聊天、RAG、Agent、多轮对话与批量生成
我在聊天场景里用 SGLang 最多。启动一个 OpenAI 兼容服务，前端直接调用，多轮对话的上下文自动缓存。用户连续提问时，首 token 延迟很低，体验很流畅。对于客服机器人或者个人助手，这种低延迟很重要。SGLang 的连续批处理还能同时服务很多用户，不用为每个会话单独开进程。
RAG 场景也让我觉得 SGLang 很合适。检索回来的文档经常被多个问题共享，RadixAttention 的前缀缓存能大幅减少重复计算。我试过把同一篇长文档作为前缀，再问十个不同问题，整体耗时比没有缓存时少很多。Agent 场景里，模型需要反复调用工具、生成结构化动作，SGLang 的 DSL 可以把这些步骤串起来，减少手工拼接提示词的麻烦。
批量生成是另一个亮点。我们做数据标注时，需要模型对大量样本生成摘要或分类。SGLang 可以一次性提交所有请求，运行时自动批处理，吞吐量很高。多轮对话和批量生成看起来是两种负载，SGLang 都能处理。它不像有些框架只针对单一场景优化，而是试图覆盖从在线服务到离线推理的多种需求。
1.5 生态与兼容性：OpenAI API、Hugging Face 模型与部署形态
SGLang 兼容 OpenAI API 这点帮了大忙。我现有项目里很多代码都是按 OpenAI 接口写的，切换到 SGLang 只需要改 base_url 和 api_key。客户端库不用换，LangChain、LlamaIndex 这些框架也能直接对接。对于想从闭源模型迁移到开源模型的团队，这种兼容性减少了大量改造工作。
模型方面，SGLang 支持 Hugging Face 上的主流架构，比如 Llama、Qwen、Mistral、DeepSeek 等。加载模型时指定模型路径或名称就行，它内部会处理权重格式和 tokenizer。我试过加载量化模型，也能正常工作。部署形态很灵活，可以单机单卡、单机多卡，也可以用 Docker 容器化部署。社区还提供了官方镜像，方便在云环境中快速拉起服务。
从生态角度看，SGLang 正在吸引越来越多贡献者。它的文档和示例覆盖了常见用法，GitHub 上也有活跃的 issue 讨论。我遇到问题时，通常能在社区找到类似案例。它和 vLLM 等框架有竞争也有互补，很多概念相通。对于想要高性能推理又需要结构化输出的团队，SGLang 是一个值得尝试的选择。兼容性和部署灵活性让它容易融入现有技术栈。
2.1 环境准备：Python、CUDA、PyTorch 与硬件要求
装 SGLang 之前，我踩过不少坑。最麻烦的一次是服务器上 CUDA 版本和 PyTorch 对不上，折腾了大半天。我现在养成的习惯是先查清楚三件事：显卡型号、驱动版本、CUDA 版本。这三者不匹配，后面装什么都是白搭。SGLang 对 NVIDIA 显卡支持最好，官方推荐 CUDA 11.8 或 12.1 以上。如果你的机器是 A100、H100 或者 4090，基本都没问题。老一些的 V100 也能跑，只是某些优化用不上。
Python 版本我建议用 3.9 到 3.11。3.12 我试过一次，有些依赖包还没跟上，装起来会报错。PyTorch 这边，SGLang 会自己带依赖，但如果你想自己控制版本，最好提前装好和 CUDA 匹配的 torch。我一般用 torch==2.1.2 配 CUDA 12.1，比较稳。硬件方面，7B 模型大概需要 16GB 显存，13B 要 24GB 以上，70B 就得靠多卡了。内存最好 32GB 起步，不然加载模型时会很慢。
驱动版本也容易忽略。我用 nvidia-smi 看驱动，发现是 470 的时候，CUDA 12 根本装不上。更新驱动之后才顺利。如果你在云服务器上，选镜像时直接挑带 CUDA 12.1 和 PyTorch 2.1 的，能省很多事。本地机器的话，先 nvidia-smi 确认驱动，再决定装哪个版本的 CUDA。
2.2 pip 安装：创建虚拟环境、安装 sglang 与依赖
pip 安装是最省事的路子。我一般先用 conda 建个虚拟环境，conda create -n sglang python=3.10，激活之后装 PyTorch。这里有个小技巧，PyTorch 的安装命令最好去官网查，别直接 pip install torch，那样可能装到 CPU 版本。确认 torch 能调用 GPU 之后，再 pip install sglang。这个命令会拉一堆依赖，比如 transformers、vllm、flashinfer 这些，耐心等几分钟。
装完之后我习惯跑个简单测试，python -c "import sglang; print(sglang.__version__)"，没报错就说明基础环境通了。有些依赖是 optional 的，比如 flashinfer，不装也能跑，但性能会差一些。我一般会补上 pip install flashinfer，不过它编译比较久，得看机器配置。如果公司网络慢，可以换清华源或者阿里源，加 -i 参数就行。
虚拟环境的好处是隔离。我之前图省事在系统 Python 里装，结果和别的项目冲突，torch 版本被降级，差点把另一个服务搞挂。现在不管多小的项目，我都单独建环境。装 SGLang 的时候，如果 pip 报依赖冲突，先看看是不是环境里已经有旧版本的包。pip list 排查一下，该卸的卸掉。
2.3 源码编译安装：克隆仓库、安装依赖与常见问题
有些时候 pip 版本不够新，或者你想改源码，就得从 GitHub 克隆。我克隆过几次，流程不算复杂：git clone https://github.com/sgl-project/sglang.git，进目录，pip install -e ".[all]"。这个 -e 是开发模式，改了代码不用重装。[all] 会把所有可选依赖都装上，包括测试和文档工具。如果你只想要核心功能，可以不加 [all]。
源码编译最容易卡在 flashinfer 和 sgl-kernel 上。这俩需要编译 CUDA 扩展，对 nvcc 版本有要求。我有一次 nvcc 是 11.8，但 torch 是 CUDA 12.1 编译的，直接编译失败。解决办法是让 nvcc 和 torch 的 CUDA 版本一致。可以 export CUDA_HOME=/usr/local/cuda-12.1，再把 $CUDA_HOME/bin 加进 PATH。编译时间比较长，十几分钟到半小时都正常。
还有个坑是 gcc 版本。SGLang 某些扩展需要 gcc 9 以上，CentOS 7 默认是 4.8.5，得先升级。我一般用 scl enable devtoolset-9 bash 切到新版本。如果编译到一半报错，先看错误信息里有没有 nvcc 或者 gcc 关键字。实在搞不定，退回 pip 安装也是明智选择，没必要死磕源码。
2.4 Docker 部署：镜像选择、GPU 挂载与端口映射
Docker 部署是我在生产环境里最常用的方式。官方镜像 lmsysorg/sglang:latest 已经配好了 CUDA、PyTorch 和 SGLang，拉下来就能用。我一般指定版本号，比如 lmsysorg/sglang:v0.4.0-cu121，避免 latest 突然更新导致不兼容。拉镜像的时候注意体积，好几个 G，网络不好得等一会儿。
启动容器要加 --gpus all，不然容器里看不到显卡。我还会挂载模型目录和缓存目录，-v /data/models:/models，这样模型不用每次重新下载。端口映射用 -p 30000:30000，SGLang 默认监听 30000。如果要多卡，加 --shm-size 32g，不然共享内存不够，多进程通信会出问题。我遇到过没设 shm-size 导致服务启动后卡死的情况，排查了好久。
容器里启动服务和宿主机一样，python -m sglang.launch_server --model-path /models/Qwen2-7B。我比较喜欢把启动命令写成脚本，挂在容器里执行。这样换模型或者改参数不用重新构建镜像。Docker 的好处是环境隔离，坏处是调试麻烦。如果容器里报 CUDA 错误，先确认宿主机驱动版本和镜像里的 CUDA 是否兼容。nvidia-container-toolkit 也得装好，不然 --gpus 不生效。
2.5 快速启动：加载模型、启动服务与 OpenAI 兼容调用
第一次成功启动 SGLang 服务的时候，我盯着日志看了半天。命令很简单，python -m sglang.launch_server --model-path Qwen/Qwen2-7B-Instruct --port 30000。它会先下载模型，再从 Hugging Face 拉 tokenizer 和配置。下载速度取决于网络，国内的话可以提前用 huggingface-cli download 拉到本地，再用本地路径启动。日志里会显示加载进度、显存占用和监听地址，看到 Uvicorn running on http://0.0.0.0:30000 就说明好了。
服务起来之后，调用方式和 OpenAI 几乎一样。我用 openai 这个 Python 包，把 base_url 改成 http://localhost:30000/v1，api_key 随便填一个。然后 client.chat.completions.create 就能用。第一次调用会触发编译，首 token 延迟会高一些，之后就正常了。我试过流式输出，stream=True，效果和 OpenAI 没差别。多轮对话只要把历史消息传进去，SGLang 会自动利用前缀缓存。
如果你不想写代码，直接用 curl 也行。curl http://localhost:30000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "Qwen/Qwen2-7B-Instruct", "messages": [{"role": "user", "content": "你好"}]}'。返回的 JSON 结构跟 OpenAI 一致。我有时候用 Postman 调，方便调试参数。服务默认支持 /v1/models 接口，可以查当前加载的模型。启动时加 --api-key 能设置鉴权，生产环境建议加上。
2.6 常用参数与调优：显存占用、并发、上下文长度与多卡并行
SGLang 启动参数挺多，我常用的就那么几个。--mem-fraction-static 控制静态显存占比，默认 0.9，显存紧张可以降到 0.8。--max-running-requests 限制并发请求数，调大了吞吐高但延迟可能上升。--context-length 设最大上下文，默认跟模型配置走，但你可以改小来省显存。我有一次跑长文本任务，把 context-length 设成 8192，显存直接多占了好几个 G。
多卡并行用 --tp-size，比如两张卡就 --tp-size 2。张量并行对显存和吞吐都有帮助，但通信开销也会增加。我试过 4 卡跑 70B 模型，tp=4，效果不错。还有 --dp-size 做数据并行，适合请求量大的场景。--schedule-policy 可以选 lpm 或 fcfs，lpm 更倾向于复用前缀，对 RAG 和对话友好。我一般保持默认，除非有特殊需求。
量化也能省显存。--quantization fp8 或者 awq，加载时就量化。fp8 在 H100 上效果很好，A100 支持差一些。我用 AWQ 量化跑过 7B 模型，显存从 16G 降到 6G 左右，速度损失不大。调参这件事没有标准答案，得根据你的模型、显卡和业务负载试。我通常先跑个基准，再慢慢调 mem-fraction 和并发数，找到吞吐和延迟的平衡点。
2.7 安装排错：CUDA 版本、驱动、依赖冲突与模型加载失败
CUDA 版本不匹配是第一大坑。报错通常是 CUDA error: no kernel image is available for execution on the device，意思是编译时的 CUDA 架构和你的显卡不匹配。解决办法是确认 torch 的 CUDA 版本和系统 CUDA 一致。python -c "import torch; print(torch.version.cuda)" 看一下。如果不一致，重装 torch 或者换 SGLang 的安装方式。
驱动太旧也会出问题。nvidia-smi 报 Failed to initialize NVML: Driver/library version mismatch，说明驱动和内核模块版本对不上。重启机器一般能解决，不行就重装驱动。Docker 里如果报 could not select device driver，是 nvidia-container-toolkit 没装好。nvidia-ctk --version 检查一下，没有就按官方文档装。
依赖冲突比较隐蔽。我遇到过 transformers 版本太高，SGLang 调用某个 API 报 AttributeError。pip check 可以查冲突，但不够全。我一般看报错里提到哪个包，然后 pip install 包名==版本号 降级。模型加载失败的话，先看路径对不对，再看模型格式支不支持。有些模型需要 trust_remote_code=True，启动时加 --trust-remote-code。如果显存不够，日志会提示 OOM，这时候换小模型或者加量化。
3.1 对比背景：为什么关注 SGLang 与 vLLM
我最早接触 vLLM 大概是在 2023 年，那时候它就是推理加速的代名词，PagedAttention 这套机制几乎成了行业标配。后来 SGLang 冒出来，一开始我以为它只是又一个套壳项目，直到看见它的 RadixAttention 论文和一批实测数据，才意识到这东西不太一样。现在团队里新上推理服务，大家都会问一句：到底用 vLLM 还是 SGLang？
这个问题没有统一答案。我见过有人把 vLLM 用得很顺手，也见过 SGLang 在特定场景下把吞吐拉高好几倍。差异不在于谁绝对强，而在于你的业务长什么样。vLLM 更早成熟，生态广，社区大，很多云厂商的推理服务底层就是它。SGLang 相对年轻，可在前缀复用和结构化生成这两块确实有独到之处。
我后来养成一个习惯，选型之前先把自己的业务拆开：是单轮短问答为主，还是长上下文多轮对话？有没有大量共享前缀的 RAG 请求？需不需要约束输出格式？这些问题想清楚了，对比才有意义。盲目比 benchmark 数字，容易被带偏。
3.2 基准测试设计：吞吐、首 token 延迟、端到端延迟、显存与并发
我设计对比测试的思路很朴素：同一个模型、同一张卡、同一批请求，只换推理引擎。模型我一般选 Qwen2-7B-Instruct 或 Llama-3-8B，硬件用 A100 80G 或 4090，这样结果有参考价值。测试工具我用 vLLM 自带的 benchmark_serving，也用过 evalscope，SGLang 那边有 sglang.bench_serving，输入输出都能对齐。
指标我关注四类。吞吐看 tokens/s 和 requests/s，首 token 延迟（TTFT）决定用户第一感觉，端到端延迟（E2E）关系到整体体验，显存占用决定你一张卡能塞多少业务。并发我会从 1 拉到 64 甚至 128，观察曲线拐点。很多宣传数据是在高并发下测的，可真实业务未必一直满载，我不太看单点峰值。
有一次我拿 8B 模型在 4090 上测，vLLM 在并发 32 时吞吐接近饱和，SGLang 还能往上顶一顶。首 token 延迟两边差距不大，几乎是毫秒级。真正拉开差距的是长上下文场景，那是下一节要聊的事。测试环境里我习惯固定 --max-running-requests 和 context-length，不然参数一变结果就没法比。
3.3 长上下文与多轮对话：RadixAttention 与前缀缓存的影响
长上下文是 SGLang 最能打的地方。它的 RadixAttention 本质是把前缀 cache 组织成一棵基数树，多个请求只要共享前缀就能复用 KV。多轮对话特别吃这一套，因为每轮请求都带着前面所有历史，前缀几乎完全重复。我实测过一个 8 轮对话的场景，SGLang 的吞吐能比 vLLM 高出两三倍，vLLM 虽然也有 prefix caching，但早期版本默认不开，开了之后命中率和复用粒度都不如 RadixAttention 细。
RAG 场景同样明显。用户问不同问题，但 system prompt、检索到的文档片段往往大量重叠。SGLang 能自动把这些公共前缀缓存住，减少重复计算。我做过一个实验，1000 条带相同 system prompt 加不同问题的请求，SGLang 的首 token 延迟比 vLLM 低一大截，越往后越明显，因为缓存命中率上来了。
不过前缀缓存也不是万能。如果你的请求前缀几乎都不重复，比如每一条都带着完全不同的长文档，那 RadixAttention 的优势就发挥不出来。SGLang 维护这棵树也有开销，短请求、高随机性场景下，vLLM 有时反而更稳。我现在的判断标准很简单：看你的请求里有多少共享前缀，占比越高，越该考虑 SGLang。
3.4 结构化输出与复杂工作流：SGLang DSL 的优势与限制
SGLang 有个我觉得很实用的东西，就是前端 DSL。你可以用类似 Python 的语法写生成逻辑，比如强制 JSON 输出、分支、循环、正则约束，甚至多步推理串起来。以前做结构化抽取，我得在服务外面写一堆解析和重试代码，现在直接写在 SGLang 程序里，编译完丢给运行时执行，省事不少。
举个我实际用过的例子。做商品信息抽取，要求模型输出固定 schema 的 JSON。用 vLLM 的话，我得配 outline 或者 lm-format-enforcer，再自己处理失败重试。SGLang 里一句 gen 带上 regex 或 JSON schema 就搞定，约束在解码时生效，基本不会输出脏格式。多步工作流更明显，状态机、条件分支都能在 DSL 里表达，代码可读性比裸调 API 好很多。
限制也有。DSL 是新东西，学习曲线存在，团队里不看文档直接上手容易懵。复杂逻辑写深了，调试比普通 Python 麻烦，报错信息有时候不够直观。还有生态问题，围绕 DSL 的示例和社区问答不如 vLLM 的 API 调用丰富。我用它做中等到复杂度的任务没问题，特别复杂、频繁变更的流程，我还是倾向于用应用层代码编排。
3.5 部署与运维对比：易用性、扩展性、监控与社区生态
部署这块，两个项目都在往简单方向走。vLLM 的 vllm serve 一行命令起服务，OpenAI 兼容接口开箱即用，文档和教程铺天盖地，新人几乎零门槛。SGLang 现在也是 python -m sglang.launch_server，接口同样兼容 OpenAI，但参数命名和默认值跟 vLLM 有差异，切过来需要适应一下。
扩展性上，vLLM 支持的量化格式更多，AWQ、GPTQ、FP8、INT4 基本都有，多卡张量并行、流水线并行都成熟。SGLang 主推 FP8 和 AWQ，在 H100、A100 上表现好，但一些小众量化格式支持还不全。监控方面，vLLM 有 Prometheus 指标暴露，SGLang 也有，不过指标命名和覆盖范围没 vLLM 细。我上生产的时候，vLLM 的 Grafana 面板能直接找到现成的，SGLang 得自己拼一些。
社区生态差距更明显。vLLM 背靠伯克利，贡献者多，issue 响应快，遇到奇怪 bug 搜一下通常有人踩过。SGLang 团队也很活跃，更新频率高，但中文资料和第三方集成相对少。我有时候碰到 SGLang 的边界问题，翻 GitHub issue 得翻半天。两个项目我都在用，选型时会把团队技术栈和维护成本算进去，不光看性能数字。
3.6 选型建议：不同业务场景下的 SGLang 与 vLLM 取舍
聊了这么多，落到选型我会给几条实际建议。批量生成、离线任务、对吞吐极度敏感、请求前缀高度重复的场景，我会优先 SGLang，尤其是多轮对话、RAG、Agent 这类带大量共享上下文的工作流。它的 RadixAttention 和 DSL 在这类任务里带来的收益是实打实的，省下来的 GPU 时间就是钱。
单轮问答、接口调用简单、需要快速上线、团队对推理引擎不熟的情况，我倾向 vLLM。它的文档、示例、社区支持更厚，出问题容易找到答案，量化选项和部署方式也更全。很多云厂商的托管推理服务底层就是 vLLM，直接用能省不少运维精力。
复杂结构化输出、需要约束解码和多步编排的场景，SGLang 的 DSL 优势明显。反过来，如果业务逻辑全在应用层，推理引擎只负责生文本，那 vLLM 的简洁接口就够用。我自己的做法是小规模先各搭一套，用真实流量压一压，看哪个更契合，再决定主用哪个。别光看别人博客里的数字，你的负载才是唯一标准。
3.7 性能优化清单：批处理、量化、并行策略与参数调优
不管用哪个引擎，优化思路是共通的。批处理是第一优先级，--max-running-requests 调大能显著提升吞吐，代价是延迟可能上升。我一般从 32 开始试，逐步加到 128，找到延迟还能接受的那个点。连续批处理两个引擎都支持，开就完事了。
量化能直接省显存。FP8 在 H100 上几乎无损，AWQ 在消费卡上很香。我用 AWQ 跑 7B 模型，显存从 16G 降到 6G 左右，吞吐损失大概一两个百分点。显存松了，就能把 context-length 开大，或者塞更多并发。量化格式选哪个，得看你的卡和模型，A100 上 AWQ 稳，H100 上 FP8 更合适。
并行策略要看模型大小和卡数。7B、8B 单卡足够，13B 单卡 24G 勉强，70B 就得上张量并行。--tp-size 设成卡数，通信开销随卡数增加，不是越多越好。我试过 2 卡跑 13B，吞吐比单卡高不少，4 卡跑 70B 也顺。参数调优没有银弹，我习惯先跑基准，再一项一项改，每次只动一个变量，记录结果。这样虽然慢，但能找到真正适合自己业务的配置。
