> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokios.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel. > Use 'connector' for the local tokios-connector process. > Use 'deployment' for the public model name in the API model field. > Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend. > API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-. # SGLang 配置及使用时机 > 为 RAG 和 Agent 工作负载配置 SGLang —— RadixAttention 前缀缓存、vLLM 与 SGLang 决策矩阵以及 SGLang 专用优化参数。 SGLang 是一款面向吞吐量优化的高性能推理运行时。其核心特性 RadixAttention 采用树状 KV 缓存，可在共享 token 前缀的请求之间复用计算。这使得 SGLang 成为以下工作负载的最佳开源选择：大量请求携带相同的系统提示词、工具 schema 或检索上下文 —— RAG 流水线、多轮对话和 Agent 循环。 本指南介绍何时选择 SGLang 而非 vLLM、关键的配置参数，以及常见场景的即用启动命令。 > [!NOTE] > > 最后验证：2026-10-14。本页反映 SGLang **v0.5.21**（2 日发布，2026 年）。参数名称和默认值可能在不同版本之间发生变化 —— 运行 `python -m sglang.launch_server --help` 确认你的已安装版本。 ## RadixAttention SGLang 的 KV 缓存不是扁平的表 —— 它是一棵以 token 序列为键的**基数树**。每个请求曾经处理过的所有前缀都存在于这棵树中。当新请求到达时，SGLang 遍历树以找到最长的匹配前缀，并复用其已缓存的 KV 状态，而不是重新计算。 具体来说，如果 10 个请求共享一个 2,000 token 的系统提示词，该提示词只需预填充一次。其余 9 个请求直接进入解码阶段。随着对话产生分支，每个分支获得自己的缓存节点，任意深度的共享前缀都会被独立复用。 对于前缀密集型工作负载，性能差异显著。在 50 个并发请求、80% 前缀共享的情况下，SGLang 的**首 token 时间 (TTFT) 降低 37%**（与 vLLM 相比）。前缀重叠越高，优势越大；每个请求都不同时，优势缩小。 > [!TIP] > > RadixAttention 不需要你手动启用 —— 它是 SGLang KV 缓存的默认工作方式。每个请求都会自动受益。配置参数控制的是淘汰策略、内存限制和基于 Rust 的存储后端。 ## SGLang 的优势场景 当工作负载具有**高前缀重叠**特征时，选择 SGLang： * **RAG 流水线** —— 相同的系统提示词和检索片段出现在多个查询中。RadixAttention 将提示词 + 文档前缀缓存一次，然后为每个问题复用。 * **多轮对话** —— 每一轮都在前一轮的上下文基础上扩展。直到最后一轮的完整对话历史都是共享前缀。 * **带有工具 schema 的 Agent 循环** —— Agent 在每次调用时发送相同的工具定义、少样本示例和编排提示词。SGLang 缓存这些前缀，仅预填充新的工具结果。 * **长共享系统提示词** —— 数十或数百用户共享大型系统提示词的任何部署（客服机器人、编码助手、文档问答）。 * **批量评估** —— 使用不同的变量替换运行相同的提示词模板。模板前缀被缓存；仅填充部分需要预填充。 ## vLLM 的优势场景 当工作负载优先考虑**广度而非深度**时，选择 vLLM： * **每个请求独特的提示词** —— 如果每个请求的提示词完全不同且没有共享前缀，RadixAttention 无可复用。vLLM 的 PagedAttention 同样高效地处理独立请求。 * **广泛的模型支持** —— vLLM 更快地添加对新模型架构的支持。如果你需要上周刚发布的模型，vLLM 可能率先支持。 * **Blackwell GPU 优化** —— vLLM 拥有针对 NVIDIA Blackwell（B100/B200/GB200）硬件的专用优化路径。如果你在 Blackwell 上部署，vLLM 能提取更高的吞吐量。 * **EAGLE3 推测解码** —— vLLM 的 EAGLE 集成更加成熟。如果推测解码是你主要的延迟优化手段，vLLM 是目前更稳妥的选择。 * **生产环境加固** —— vLLM 拥有更大的部署规模和更长的生产服务记录。如果稳定性和社区支持比前缀缓存更重要，vLLM 是默认选择。 ## 配置参数 以下是 `python -m sglang.launch_server` 的关键 SGLang 专用参数： | 参数 | 默认值 | 用途 | | - | - | - | | `--model-path` | （必需） | HuggingFace 仓库 id 或模型的本地路径 | | `--port` | `30000` | OpenAI 兼容服务器的监听端口 | | `--host` | `127.0.0.1` | 绑定地址 —— 除非反向代理前置 SGLang，否则保持回环地址 | | `--tp` | `1` | 跨 GPU 的张量并行度 | | `--mem-fraction-static` | `0.88` | 启动时分配给 KV 缓存的 GPU 内存比例。如果有余量，长上下文工作负载可增至 `0.90`-`0.92`。 | | `--context-length` | 模型最大值 | 覆盖模型的最大上下文长度。将此值设为低于模型最大值以减少每个请求的 KV 缓存内存。 | | `--chunked-prefill-size` | `-1`（自动） | 将大型预填充分块以避免阻塞解码。对于包含长输入的混合工作负载，设为 `2048`-`4096`。 | | `--disable-radix-cache` | `false` | 完全禁用 RadixAttention。你几乎永远不需要这样做 —— 它会移除 SGLang 的核心优势。 | | `--enable-metrics` | `false` | 在 `/metrics` 暴露 Prometheus 指标。在生产环境中启用。 | | `--api-key` | （无） | 要求对 SGLang 自身服务器的请求携带 bearer token。作为回环地址上的纵深防御措施。 | ### 基于 Rust 的前缀缓存 从 **v0.5.21** 开始，RadixAttention 缓存后端使用 Rust 实现并默认启用。Rust 后端取代了早期的 Python 实现，在缓存查找、插入和淘汰方面开销更低。你不需要使用参数来启用它 —— 它就是默认路径。 如果遇到问题，你可以使用 `--disable-cuda-graph` 回退到 Python 实现，并查阅 SGLang 发布说明以确认你的版本对应的确切回退参数。实际上，Rust 后端稳定且更快。 ## 决策矩阵 | 工作负载 | 推荐运行时 | 原因 | | - | - | - | | 重复上下文的 RAG | **SGLang** | RadixAttention 缓存系统提示词 + 检索片段 | | 多轮对话（10+ 轮） | **SGLang** | 每一轮扩展共享前缀 | | 带有工具 schema 的 Agent 循环 | **SGLang** | 工具定义在首次调用后被缓存 | | 长共享系统提示词 | **SGLang** | 一次预填充服务多个请求 | | 每个请求独特的提示词 | **vLLM** | 无前缀复用优势；PagedAttention 同样快速 | | 最新模型架构 | **vLLM** | 更快地支持新模型 | | Blackwell GPU（B100/B200） | **vLLM** | 专用 Blackwell 优化路径 | | EAGLE3 推测解码 | **vLLM** | 更成熟的推测解码支持 | | 批量评估（相同模板） | **SGLang** | 模板前缀在所有变体间共享 | | 单用户、低并发 | 均可 | 两者表现都很好；按熟悉度选择 | ## 示例配置 ### 长检索上下文的 RAG 流水线 服务一个针对 RAG 优化的 70B 模型，每个请求携带相同的系统提示词和大型检索文档片段： ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} python -m sglang.launch_server \ --model-path meta-llama/Llama-3.1-70B-Instruct \ --port 30000 \ --tp 4 \ --mem-fraction-static 0.92 \ --context-length 16384 \ --chunked-prefill-size 4096 \ --enable-metrics ``` `--mem-fraction-static 0.92` 为长检索上下文分配更多 GPU 内存给 KV 缓存。`--chunked-prefill-size 4096` 防止大型文档预填充阻塞并发解码请求。RadixAttention 处理其余部分 —— 系统提示词和文档前缀在首次请求后即被缓存。 ### 带工具 schema 的多轮对话 Agent 服务一个在每次调用时发送相同工具定义的 Agent 模型： ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} python -m sglang.launch_server \ --model-path meta-llama/Llama-3.1-8B-Instruct \ --port 30000 \ --tp 1 \ --mem-fraction-static 0.90 \ --context-length 32768 \ --chunked-prefill-size 2048 \ --enable-metrics ``` Agent 的工具 schema、系统提示词和少样本示例在每次调用中完全相同。RadixAttention 缓存整个前缀。只有每轮末尾的新工具结果和用户消息需要新的预填充。在 32K 上下文下，多轮对话可以运行数十轮才触及限制。 ### 高吞吐批量评估 以最大吞吐量在数千个输入上运行相同的提示词模板： ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} python -m sglang.launch_server \ --model-path meta-llama/Llama-3.1-70B-Instruct \ --port 30000 \ --tp 8 \ --mem-fraction-static 0.90 \ --context-length 8192 \ --chunked-prefill-size 4096 \ --enable-metrics ``` 提示词模板被预填充一次并缓存。每个请求仅预填充其独特的变量替换。在 8 个 GPU 的张量并行下，批量吞吐量主要由解码主导 —— 预填充开销几乎被消除。 > [!WARNING] > > **安全公告 —— Qwen VL 视频预处理。** 截至 v0.5.21，SGLang 在 Qwen VL 视频预处理中存在内存耗尽拒绝服务漏洞。精心构造的请求可在视频帧解码期间触发无限制的内存分配。如果你服务 Qwen VL 模型，请应用上游补丁或升级到包含修复的版本。如果无法立即升级，请将 SGLang 服务器的访问限制为仅受信任的调用方。 ## 原生决策 API SGLang v0.5.21 新增了**原生决策 API**，遵循与 Ollama 和 LM Studio 相同的模式。这让客户端可以查询可用模型、检查模型状态，并通过一致的接口管理部署 —— 如果你构建的工具需要与多个本地后端通信，这会很有用。 请查阅 SGLang 发布说明以获取确切的端点路径和请求/响应格式，因为该 API 接口较新，可能会演进。 ## 通过 Tokios 连接 SGLang SGLang 运行后，Tokios 连接器无需开放任何入站端口即可将其暴露给远程客户端。连接器拨出到 `https://api.tokios.com`，并将请求转发到 localhost 上 SGLang 的 OpenAI 兼容 `/v1` 端点。完整设置流程请参阅 [SGLang 远程访问](/zh/guides/sglang-remote-access.md)。 > **[SGLang 远程访问](/zh/guides/sglang-remote-access.md)** > > 通过 Tokios 连接 SGLang，实现认证远程访问。 > **[vLLM 远程访问](/zh/guides/vllm-remote-access.md)** > > vLLM 采用相同模式 —— 并排比较两种设置。 > **[推测解码](/zh/guides/speculative-decoding.md)** > > 使用草稿模型、n-grams、MTP 和 EAGLE 加速解码。 > **[基准测试你的部署](/zh/guides/benchmark-your-deployment.md)** > > 测量不同配置下的 TTFT、吞吐量和延迟。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.