SGLang核心解析：Radix Attention与DSL如何优化长上下文推理

在部署基于长上下文对话的服务时我遇到过一个特别典型的问题用户多次编辑同一个提示词模型服务每请求的时延却像坐了火箭一样往上涨但GPU的算力利用率又低得离谱。查到最后才发现问题不是模型本身变慢了而是前缀缓存完全没有命中。那段时间我仔细研究SGLang的实现把Radix Attention和它的领域特定语言DSL前端都翻了个底朝天最终把同类场景的token消耗压低了将近一半。这篇文章就围绕SGLang的这两个核心设计展开顺带聊聊和vLLM的选型差异、Ubuntu部署时的坑以及长序列服务里显存和性能的真实权衡。1. Radix Attention如何解决共享前缀场景的缓存浪费1.1 KV Cache为什么不能只存最新一轮先聊最基础的问题我们平时说的KV Cache到底是什么。Transformer在生成每个token时都要拿当前的Query和前面所有token的Key、Value做注意力计算。如果不缓存Key和Value每生成一个新token就得把之前所有token重新算一遍这等于每次说话前都把前面说过的话重新念一遍效率极其低下。所以推理框架都会把已经算过的K和V缓存下来这就是KV Cache。但KV Cache有个麻烦它会被新的请求覆盖。传统的连续缓存方式一般只保留最新一段对话的KV一旦用户改了前面的提示词后续所有的缓存都作废整个前缀必须重新计算。实际业务里这个场景一点都不少见很多人会在同一个文档上反复提问或者用同一个system prompt前缀发起大量请求共享前缀往往能占到请求总长度的70%到80%。这里就容易产生一个误解很多人以为只要开启--enable-prefix-caching之类的选项框架就会自动复用所有前缀。实际上vLLM的prefix caching是基于block哈希的它能把一段完整的、经过哈希计算的前缀缓存起来但缓存命中的前提是前缀完全一致。如果两个请求共享的是前80%的内容仅仅因为第200个token之后有一点修改那后半段缓存就全部失效仍然要重新计算。SGLang的Radix Attention思路不太一样它把前缀组织成树节点粒度可以非常细改动的部分只影响从改动位置开始的子树前面改动之前的部分依然能复用。1.2 从线性前缀缓存到前缀树Radix Attention的核心数据结构是Radix Tree中文一般叫基数树或前缀树。它和普通Trie的区别是如果一个节点只有一个子节点那就把边上的token片段合并起来减少树的高度和节点数量。你可以把它理解成Linux的目录结构/usr/local/bin和/usr/bin共享/usr/路径绝对路径越长目录层级越深但共享部分永远落在更上层。放到推理场景里每次新请求进来时SGLang会沿着Radix Tree匹配当前请求的前缀能匹配上的节点直接复用对应的KV Cache匹配不上或者部分匹配的节点则重新计算。关键点在于重新计算的节点只会挂在已有的父节点下面而不是把整棵子树推倒重来。举个例子。请求A是今天天气怎么样SGLang计算出这5个token的K和V在树里插入一条路径[今天, 天气, 怎么, 样]。请求B是今天天气怎么样适合跑步吗前缀[今天, 天气, 怎么, 样]已经存在就直接复用再在末尾插入[, 适合, 跑步, 吗]。这时候树里不会有两条重复的前缀路径而是共享前四个token的同一份缓存。如果请求C是今天天气好不好只能匹配到[今天, 天气]两个token那就从这里开始重新计算。这种做法的收益在批量推理时尤其明显。多个请求只要有一段共同前缀哪怕后面分叉的路线完全不同前缀部分的显存占用和计算量都能省掉。这也是我在实际部署时最看重的特性多轮对话、系统提示词、RAG场景下的文档前缀天然就是一棵大树的形状用Radix Tree来管理比线性缓存合理得多。1.3 缓存淘汰时的最长片段优先策略Radix Tree如果无限制增长显存迟早会被占满所以必须配合淘汰机制。SGLang的缓存淘汰算法我认为很值得单独说因为它不是简单按照LRU逐条清理而是尽量优先淘汰那些只会破坏最少复用的节点。基本策略是每个节点带有访问时间和引用计数当KV Cache占用的显存超过阈值时从树的末端开始淘汰访问最久远的叶子节点。如果某个叶子节点被淘汰后它的父节点变成了叶子节点并且同样长期没人访问也会被继续回收。实际上我们观察到的行为更像按最后一次访问时间排序优先删除整棵子树中最近最少使用的分支。这个设计的好处是它不会因为某个中间节点访问频率低就直接删掉因为删掉中间节点会把整棵子树全部废掉损失太大。SGLang尽量只淘汰叶子节点让共享的中间节点继续留在内存里。我在压测时观察过一个现象即使在淘汰压力很大的情况下600条请求里公共前缀的命中率依然能维持在60%以上就是靠这个策略保住的。实际调优时有个参数要关注就是最大前缀缓存容量。SGLang里可以通过--max-radix-keys或显存比例参数控制缓存上限如果设置得太小树会被频繁淘汰命中率上不去设置得太大则会挤压留给生成序列的空间可能导致并发数下降甚至OOM。我通常的做法是先看单条请求的平均前缀token数乘上预估的业务并发量再结合KV Cache的单token显存占用算出一个大概值留20%冗余。2. DSL的作用远不只是少写代码2.1 一次gen调用背后发生了什么SGLang的领域特定语言是一套嵌在Python里的约束解码工具。第一次看到gen和select这些原语时我心想这不就是个封装好的生成函数吗后来认真读了一遍源码才发现它真正做的事情远比少写代码复杂。在SGLang里一个典型的生成流程不是一次性把整段文本丢给模型而是通过DSL描述一个生成计划。比如你要让模型输出一个JSON对象中间某个字段只能从固定的枚举值里选那你可以在Python脚本里拆成多步先让模型生成一个开场标记再让模型从候选列表里选一个值最后生成剩余字段。每一步都对应一次前向计算但它们的KV Cache是共享的不会因为拆开写就重复计算。这个设计的关键在于它的编译过程。DSL会把你的Python函数转成一个有向图每个节点代表一个采样操作节点之间可以并行执行。模型不是每走一步就等网络请求回来而是一次请求里按图执行多个采样点。这和普通的分步调用有本质区别后者在每一步之间都要做进程间通信把中间结果送回服务端再发起下一次调用延迟会成倍增加。我在一个结构化信息抽取的项目里做过对比不拆步骤、让模型自由输出再用正则解析和校验整体成功率大概在82%左右而且经常出现JSON语法正确但字段缺失的情况。改用SGLang的DSL约束后把每个字段单独用gen描述输出格式不合法的问题基本绝迹。这个收益来自约束解码让模型只能在满足格式的token集合里做采样而不是先生成再纠错。2.2 正则约束与结构化输出如何和前缀树配合DSL有一个很有意思的地方是它可以和Radix Attention形成正向联动。传统的约束解码是在采样时把不符合正则的token mask掉这会让采样路径更窄但这和缓存有什么关系关系在于当你用DSL约束输出时如果同一类型的请求反复执行模型生成的分支会相对集中树结构里可复用的中间状态就更多。举个例子我在日志分析场景里定义了一个DSL函数输入是同一批系统日志要求模型输出时间、级别、事件类型、建议处理方式四个字段。由于DSL把每个字段的生成都做了约束不同请求生成的字段名和结构完全一致模型在处理相似日志时前面的结构token也是一样的。这种情况下Radix Tree里就能形成很多共享节点第二个请求开始就有大量缓存可以直接命中。更直观的配合是fork机制。DSL里可以用fork并行生成多个候选SGLang会同时保留多个候选路径的KV Cache然后在主路径上继续执行。这些并行候选之间共享同一个主前缀所以不会导致前缀重复计算。如果用原生采样自己实现这种生成多个候选再打分的逻辑每个候选都要从起点重新算代价完全不同。所以我的建议是如果你的业务需要对输出做严格校验别只把它当成一个生成JSON的辅助工具把DSL和Radix Attention放在一起理解才能发挥最大价值。它约束的不只是输出格式还有缓存树的分支结构。2.3 我建议先掌握的四条基础原语SGLang的DSL学习成本不算高但真正常用到的原语我认为主要是下面几个。我把它们整理成了一张表方便对照理解原语作用典型使用场景gen采样生成一段文本可指定max_tokens、temperature、正则约束等生成字段、生成摘要select从给定字符串列表中强制选择一个分类、判断题fork并行创建多个生成分支候选生成后打分把一个生成的返回值拼接进上下文构造多轮对话、链式调用我在教团队新同学的时候通常让他们先只掌握gen和select把业务里80%的格式化输出场景跑通再上fork处理候选排序最后才追求把完整的复杂流程写成自定义Python函数。因为fork一旦用得不好会在一个请求里并行产生很多分支显存和计算量都可能成倍上涨反而把Radix Attention省下来的优势抵消掉。这里还要提一个细节DSL函数不只是文本生成脚本它里面对请求帧的控制也会影响缓存。比如你可以把system prompt、用户输入这些共享部分放在同一个字符串模板里尽量不动让Radix Tree复用而把每次变化的业务参数放在gen里。如果模板本身经常变动那DSL再怎么优化也救不了缓存命中率。3. 和vLLM对比之后我对选型的判断3.1 两者都在做前缀缓存差别在记忆粒度这几年部署推理服务绕不开SGLang和vLLM的对比。先说结论两者都是优秀的框架但设计取向确实有区别。vLLM的PagedAttention解决了KV Cache的显存碎片问题前缀缓存是建立在PagedAttention之上的一个优化选项它把连续的token块哈希成固定大小的块匹配粒度是块级别。SGLang的Radix Attention则是直接从如何最大化复用历史计算这个角度出发设计的数据结构匹配粒度是token级别的片段。这种差异在共享前缀很长但没有完全对齐的情况下体现得特别明显。比如一个文档有3000个token两个请求的差异只在第2900个token以后vLLM如果按128个token一块来哈希从第2816个token开始就会因为内容变化导致整块失效前面27个块虽然能用但最后一个边界不太优雅而SGLang会把前2900个token都尝试匹配起来直到真正发生变化的位置才分叉。这并不是说vLLM不够好。vLLM在生态成熟度、文档完善度和API兼容性上做得非常出色很多生产环境已经用它稳定跑了大半年没有必要为了缓存命中率微小的提升去迁移。我认为SGLang的优势主要集中在两类场景一是共享前缀比例很高的对话、RAG、多租户Agent场景二是需要结构化输出、约束解码的复杂业务逻辑场景。这两点正好对应它的两个核心设计。3.2 什么时候不需要换我也见过一些情况强行从vLLM切到SGLang后收益不大。如果你的业务请求几乎都是独立短文本没有长期共享的system prompt也没有反复修改的多轮上下文那Radix Attention能复用的前缀就很有限架构选型上的优势自然体现不出来。另外如果团队已经基于vLLM的LLM类封装了一大套推理、监控、灰度逻辑迁移成本会远高于缓存命中的收益。SGLang虽然API和OpenAI兼容协议接得很好但它的扩展点、请求队列、调度参数和vLLM不完全一样迁移一次免不了踩坑。我的建议是先用一段时间的流量日志做离线分析统计每个请求的前缀长度和共享情况。如果公共前缀超过总token数的一半再考虑SGLang如果前缀占比不到20%用哪个框架差别不大选团队最熟的就行。不要为了追新而迁框架推理服务最值钱的东西永远是稳定和可预测。3.3 部署Qwen3-Reranker时的实际操作与注意点SGLang Qwen3-Reranker这个组合最近被问得挺多我在这里多说一句。Qwen3-Reranker是用于文本相关性打分的重排序模型它的目标输出是得分而不是生成自然语言。SGLang本身主要面向文本生成推理但对有交叉编码器架构支持的模型也能通过兼容模式加载并提供打分接口。实际部署时我建议先确认你拿到的权重格式是不是SGLang后端支持的类型。像Qwen3-Reranker这类模型权重转换和加载路径与普通LLM不完全一样启动服务前最好先在本地用一个小测试集跑一遍确认输出的是预期得分而不是一段生成的文字。我踩过的一个坑就是模型加载成功了、接口也通了但返回结果始终是随机token组成的文本后来发现是服务端把它当生成模型处理了需要显式指定评分任务相关的启动参数。如果你只是需要一个独立的reranker服务不一定非要上SGLang用专门的跨编码器推理框架可能更省事。但如果你的架构本身已经有了SGLang服务希望能在一个端口里同时承担生成和排序两类任务那把它作为一个附加能力接入是合理的。重点是提前做接口契约的约定生成接口走/v1/chat/completions排序接口走自定义的/v1/rerank别混在一起否则后续监控和压测都会很难受。3.4 Ubuntu环境下的安装与踩坑记录Ubuntu上装SGLang官方推荐的方式是pip install sglang[all]但如果你不提前检查环境大概率会卡在依赖冲突上。我装了好几台机器后总结的顺序是这样的。先用nvidia-smi确认驱动支持的CUDA版本再确认torch版本和CUDA一致。SGLang对PyTorch版本比较挑剔尤其当你需要同时使用FlashInfer或其他加速后端时。我踩过最典型的一个坑是系统里已经装了一个较新的torchSGLang安装时为了满足自身依赖版本又拉了一个不同版本的torch两个版本相互覆盖结果服务一加载就报符号找不到。我的做法是建一个干净的Python虚拟环境Python版本用3.10或3.11然后先手动装torch指定和主CUDA版本匹配的index再装SGLang。装完以后跑一下python -c import sglang; print(sglang.__version__)做冒烟测试能过再启动服务。如果机器上有多个CUDA toolkit务必在环境变量里写清楚CUDA_HOME和LD_LIBRARY_PATH否则编译扩展时会连到错误的库上出现一些莫名其妙的段错误。还有一点Ubuntu的glibc版本会影响部分预编译轮子的可用性。如果安装时出现GLIBCXX_3.4.XX not found通常不是SGLang的问题而是系统库版本太老或Anaconda环境里的libstdc太旧。换到系统Python或更新conda的libstdc-ng包就能解决。4. 显存优化与dflash长上下文服务的收益边界4.1 dflash到底是什么时候该开dflash这个名词在SGLang社区里出现频率不低本质上它和长序列下的注意力计算优化有关。简单说当序列长度变得很长时标准多查询注意力在解码阶段的显存和访存压力会大幅度上升dflash这类优化的思路是利用更激进的融合和稀疏化策略减少中间矩阵的显存占用让长上下文场景下也能塞进更大的batch。但我不建议一上来就开。dflash的优化效果和模型结构、显卡架构、上下文长度都有关系。我做的实测里当平均请求长度超过4096个token、batch size大于16时开启后显存占用能降15%到25%左右但如果请求长度普遍在1024以下收益非常有限反而可能在部分显卡上因为内核选择导致首token时延略微变慢。所以我的建议是分两步走。先不开dflash把业务流量按请求长度分布统计一下。如果P50请求长度在2048以上再开dflash做A/B对比重点看三个指标显存峰值、每请求时延、吞吐量。不要只看显存下降就欢呼因为显存降了但吞吐没提升的话对用户感知没有直接帮助。更重要的是看单位显存下能处理的并发数有没有变多。4.2 显存预算与并发数的联动计算调优SGLang的显存和并发参数我一直用一个简单的估算公式。先算单条请求的KV Cache占用公式大致是2K和V两份 × 层数 × 注意力头数 × 头维度 × 序列长度 × 每个元素的字节数。如果是半精度存储一个元素2字节一个8层、12头、每头64维的模型单token的KV Cache大约是2 × 8 × 12 × 64 × 2 24576字节也就是24KB。但这只是思路具体模型要用实际配置文件里的层数和头数替换。假设一张80GB显卡模型权重占了40GB剩下40GB给KV Cache和激活。如果平均序列长度是2048请求并发数是32那么KV Cache占用就是24KB × 2048 × 32 ≈ 1.5GB看起来不大。但如果你把序列长度拉到32768同样并发32就会变成约24GB预算一下子紧起来。这也是为什么长上下文场景下Radix Attention的命中率和dflash这类显存优化同时开效果才会最大化。实际配置时我建议先用小并发把模型跑起来逐个增加--max-running-requests或者其他控制并发的参数观察显存曲线。如果出现OOM优先降低最大并发或者调小radix缓存上限而不是直接砍dflash。因为砍掉dflash可能只影响长序列场景而调小缓存上限会影响所有请求的命中率。4.3 实测数据命中率与服务吞吐变化下面这组数据来自我在一台8卡A100机器上用开源模型跑的压力测试不算严谨的基准测试但能反映趋势仅供参考。配置前缀命中率吞吐token/s显存峰值无前缀缓存0%约220约58GB仅开Radix Attention约47%约310约54GBRadix Attention dflash约45%约350约46GB调整请求顺序两者全开约63%约380约45GB可以看到Radix Attention的核心收益是让同一批请求里重复的前缀不再重复计算因此吞吐提升比较明显。开启dflash后显存占用继续下降腾出来的空间让更多请求可以同时进入batch吞吐又有小幅上涨。最后一行的调整请求顺序其实是个很讨巧的方法在业务允许的情况下把共享前缀相似的请求在队列里排到一起让Radix Tree的复用率进一步提升。这一点很多资料里不会提但在实际压测中效果很显著。需要说明的是如果你只有一两张卡或者序列长度普遍很短整体收益不会这么夸张。调优前务必结合自己的负载特征来判断别人的测试数据只能当参考线。5. 排查SGLang性能问题时我建议的三种路径5.1 先看命中率日志再看时延SGLang自带的前缀缓存命中信息是排查性能问题的第一站。我在压测时发现很多时候业务方反馈模型变慢了其实不是模型推理变慢而是原本应该命中的缓存没有命中。这时候只要看一眼前缀命中率如果从50%以上掉到10%以下问题大概率出在请求形状上要么system prompt频繁变化要么客户端把时间戳、随机ID这类每次变化的内容放在了前缀位置。这里的关键动作是检查请求体的组装逻辑。很多客户端会在每次请求时重新拼接system prompt并追加当前时间戳这会让整个前缀每次都变化。我的做法是把公共信息做成静态模板变化内容尽量放在prompt的末尾或用户消息里这样Radix Tree才能命中前面的大段共享部分。如果命中率正常但时延还是高再往下看调度队列。SGLang的请求调度是连续的一个大请求可能会长时间占据执行插槽导致后续小请求排队。这时候可以考虑调整最大批处理大小或者给不同请求设置不同的优先级。我在生产环境里用过按请求长度分队列的方式短请求和长请求分开处理效果立竿见影。5.2 按业务前缀分组一个容易忽略的优化点Radix Attention的命中率和请求到达顺序强相关。树是慢慢长起来的如果两个共享前缀很长的请求在时间上错开很远中间可能已经被其他请求挤占淘汰了。所以如果你的业务能接受一定程度的排队延迟把共享前缀相似的请求在调度前做一次小规模聚合会让Radix Tree的复用率明显上升。具体做法是在服务入口处维护一个极简的hash表key是请求的静态前缀段value是一个小队列。调度线程每隔一小段时间从同一个key的队列里批量取请求一起发给SGLang。这个逻辑不用做得很重只要保证同一个业务线、同一个文档ID、同一轮对话的请求尽量挨在一起就可以。我在实践中发现这个请求分桶策略比单纯调大radix缓存容量更有效。因为缓存容量再大也架不住请求交织得乱七八糟。分桶之后同样容量的缓存能装下更多有效的前缀片段相当于把缓存用在刀刃上。5.3 多副本部署时的缓存一致性陷阱最后说一个分布式环境下容易踩的坑如果你用多个SGLang副本做负载均衡每个副本的Radix Tree是独立维护的。同样的提示词打到不同副本上就可能重复计算多次命中率被均摊掉整体收益打折扣。解决办法有两种。第一种是让负载均衡器按请求的静态前缀做哈希同一类请求尽量路由到同一个副本这样每个副本内部都能建立起长期有效的Radix Tree。第二种是接受跨副本重复计算的现实靠dflash和显存优化来弥补毕竟Radix Tree本身不跨节点共享除非用额外组件做全局前缀缓存但那样又会引入新的复杂度和延迟。我的个人经验是在多数业务场景下第一种办法成本最低收益也最直接。只要在网关层对system prompt或文档ID做一个一致性哈希副本内的缓存命中率就能稳定很多。如果业务流量特别大再做更细粒度的路由策略比如按租户隔离避免一个租户的高频请求把另一个租户的缓存全部挤掉。最后再分享一个我在实际操作中养成的习惯每次调整SGLang的缓存参数或dflash配置后不要只看平均时延一定把缓存命中率首token时延每token解码时延拆开看。因为平均时延被缓存命中率掩盖得太厉害有时命中率低了平均时延却因为batch变大显得还行但用户感知到的首token时延其实已经劣化了。把这三个指标放在一起观察才能判断调整到底是在补齐短板还是制造新的瓶颈。