SGLang：结构化生成语言与推理引擎

为什么需要 SGLang：服务吞吐、结构化输出、Agent 编排难以兼得 → 一体化框架

传统 LLM 服务框架（如 vLLM、TGI）把「一次生成」当作基本单元：多轮对话、批量 few-shot、Agent 工具调用这类请求之间存在大量共享前缀（系统提示词、检索到的上下文、对话历史），但每个请求都会重新计算这些前缀的注意力，KV 缓存互不共享，显存与算力被重复消耗，吞吐始终上不去。结构化输出则更麻烦：通用框架先生成自由文本再做 JSON 解析，格式出错只能重试，每轮重试都重新走一遍 prefill，成本成倍放大。对 RAG/Agent 业务，这两点直接决定系统能否扛住生产流量。

SGLang 把「生成过程」抽象成一段可编程的 Python 编排（前端语言），编译器把编排解析成执行计划；后端引擎用 RadixAttention 在基数树上维护所有请求的 KV 缓存，前缀相同的请求自动复用缓存，调度器按缓存命中优先排布请求。约束解码侧，SGLang 接入 XGrammar 并把 JSON Schema/正则编译为压缩有限状态机（FSM），在采样阶段直接屏蔽非法 token，保证输出符合 schema，不需要生成后重试。「高吞吐」与「结构化」因此可以在同一套引擎内同时解决。

与 vLLM 的「纯服务优化」路线不同，SGLang 是「语言 + 引擎」双层结构：你可以完全不用 DSL，直接把它当 OpenAI 兼容服务用；也可以写 DSL 获得跨请求缓存复用和多步编排能力。这一设计带来更高上限，也让新手需要多学一层前端概念。

安装与环境配置：3 步就绪

步骤一·安装。SGLang 要求 Linux + Python 3.10+，CUDA 11.8 或 12.x；本文验证用的 1.1B 小模型 8GB 显存即可运行。官方推荐 pip 安装完整依赖（含 FlashInfer、Triton、XGrammar 等加速内核）。若编译环境不满足，直接使用官方 Docker 镜像 lmsysorg/sglang（已内置全部依赖，最省事）。

步骤二·配置。下载 Hugging Face 模型需要认证。拉取 Llama、Qwen2.5 等 gated 模型前，先执行 huggingface-cli login 或设置环境变量 export HF_TOKEN=你的token；公开小模型（如 TinyLlama）可跳过此步。

步骤三·验证。启动一个 1.1B 小模型验证整条链路：

另开终端执行 curl http://localhost:30000/v1/models，返回模型列表即安装成功。首次启动会从 Hugging Face 下载模型权重，请保持网络通畅。

pip install --upgrade pippip install "sglang[all]"

python -m sglang.launch_server \  --model-path TinyLlama/TinyLlama-1.1B-Chat-v1.0 \  --port 30000

快速上手：10 分钟跑通第一个结构化生成服务

最小可用闭环：启动服务 → 调 OpenAI 兼容接口对话 → 用 response_format 拿 JSON → 用 DSL 写多步提取链。前三步不需要写业务代码，第四步展示 SGLang 与 vLLM 的差异点。

1. 启动服务（命令见上一节），等待日志出现「The server is fired up and ready to roll!」即就绪。

2. 普通对话：向 POST http://localhost:30000/v1/chat/completions 发请求，字段与 OpenAI 完全一致（model、messages、temperature）。

3. 结构化输出：在请求体加 "response_format": {"type": "json_schema", "json_schema": {...}}，返回的 content 保证是合法 JSON 且字段符合 schema。

4. DSL 多步提取：写一个 Python 文件运行（见下方代码），体会「生成内容参与下一轮拼接」的编排方式。

运行结果形如 {"name":"张三","company":"字节跳动","title":"算法工程师"}，且必然符合 schema。进阶用法：服务端加 --enable-tools 可启用工具调用；DSL 中连续多次 sgl.gen 即可串起「先提取、再判断、再生成」的 Agent 链。

# demo_extract.py — 需要服务已在 30000 端口运行import sglang as sgl sgl.set_default_backend(sgl.OpenAIEndpoint("http://localhost:30000")) schema = {    "type": "object",    "properties": {        "name": {"type": "string"},        "company": {"type": "string"},        "title": {"type": "string"},    },} @sgl.functiondef extract_json(s, text):    s += "从以下文本提取人物信息，只输出 JSON：\n" + text + "\n"    s += sgl.gen("info", max_tokens=256, json_schema=schema) state = extract_json.run(text="张三就职于字节跳动，担任算法工程师。")print(state["info"])

核心能力详解：3 大支柱

支柱一·RadixAttention 缓存复用。KV cache 是 LLM 生成时保存的历史注意力键值对，决定理解长上下文所需的内存。RadixAttention 用基数树（一般前缀树，即前缀共享的树结构）统一管理所有请求的 KV 缓存，多轮对话、共享系统提示词的请求自动复用公共前缀，并配合缓存感知调度（优先调度可命中缓存的请求）减少显存碎片。多轮与 Agent 场景收益最明显；论文在公开 benchmark 上报告最高 6.4 倍于既有系统的吞吐提升。

支柱二·结构化输出与压缩 FSM。约束解码把 JSON Schema、正则、EBNF 编译成有限状态机（FSM，一种状态转移图），采样时只允许当前状态合法的 token。XGrammar 负责把 schema 快速编译，SGLang 的压缩 FSM 进一步压缩状态表，使约束解码性能不低于甚至高于无约束采样——非法 token 被提前排除，生成长度更短。对外通过 response_format 暴露 OpenAI 风格接口，内部一次性生成合法 JSON，免去重试。

支柱三·服务能力与多卡扩展。连续批处理之外，SGLang 支持张量并行（--tp-size）、数据并行（--dp-size，含 DP attention 降低多卡通信开销）、PD 分离（prefill 与 decode 独立部署），并支持 EAGLE 投机解码、LoRA 服务、多模态模型（Qwen2-VL、Llama-3.2-Vision 等）以及 --enable-tools 工具调用。离线批量任务可直接用 from sglang import Engine 创建引擎。

生产部署与监控：从上线到运维

部署方式一·Docker 单节点。官方镜像已内置 CUDA/FlashInfer 等依赖，注意共享内存与 IPC 参数：

部署方式二·Kubernetes 多卡。单节点 8 卡时可用 --tp-size 4 --dp-size 2 组合张量与数据并行。liveness/readiness 探针指向 /health，真实生成探活用 /health_generate（会实际跑一次微型生成）；滚动更新时先摘流再删 Pod；Hugging Face 缓存目录挂 PVC，避免每次重启重新下载模型。

可观测性。服务默认暴露 Prometheus 格式指标（/metrics），可采集吞吐、TTFT（首 token 延迟）、缓存命中率等；官方仓库提供 Grafana 面板模板；/get_server_info 返回并行配置与版本号，适合发布后校验。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>容器共享内存不足：Docker/K8s 默认 /dev/shm 过小会导致采样线程报错，必须设置 --shm-size（K8s 用 emptyDir medium=Memory）并开启 --ipc=host。</li><li>gated 模型拉取失败：Llama、Qwen2.5 等模型需先到 Hugging Face 接受协议，再通过 huggingface-cli login 或 HF_TOKEN 认证，否则服务启动阶段反复报 401/404。</li><li>版本与参数不匹配：response_format 的 json_schema 与 --enable-tools 是 v0.4+ 才支持，旧版本只支持正则约束；用新文档配置旧版本会报 unrecognized argument。</li><li>缓存命中率决定收益：RadixAttention 只在请求存在共享前缀时见效，随机独立短请求场景请先观察指标中的缓存命中率再谈优化。</li></ul>

docker run --gpus all --shm-size 32g --ipc=host -p 30000:30000 \  -v ~/.cache/huggingface:/root/.cache/huggingface \  lmsysorg/sglang:latest \  --model-path Qwen/Qwen2.5-7B-Instruct --host 0.0.0.0 --port 30000

版本迭代

SGLang 于 2024 年 1 月随论文开源，随后以月级节奏迭代。v0.1-v0.3 完成从原型到多卡可用的演进；v0.4 是关键节点——多卡数据并行、结构化输出与工具调用三项能力落地；v0.5 转向延迟优化与部署基础设施（PD 分离、缓存生成）。以下版本记录整理自官方 Release 与博客，截至训练数据（2025-07），可能已有更新版本。

AI 应用场景

常见误区

面试题