第一次用 SGLang：把本地模型接进聊天应用

你已经有一个聊天页面，后端也会调用 /v1/chat/completions。现在想把远程模型换成自己机器上的模型，卡住的地方通常很具体：权重下载完了，谁来把它变成一个能接请求、能连续返回文字的服务？

SGLang 可以承担这件事。应用把消息发给它，它负责把消息变成模型输入，安排 GPU 计算，再把生成结果返回。用户身份、对话存档和业务操作仍由你的应用管理。

先把一条请求跑通，比先记住 RadixAttention、连续批处理和各种并行策略更有用。等这一条链路看得见，后面的优化才有位置可放。

权重文件和模型服务之间，还差一个执行程序

权重保存的是模型参数。要拿它回答问题，还需要加载参数、读取分词器、按模型要求组织消息、执行计算，并把输出的 token 转回文字。Token 是模型处理的基本单位，一段汉字或英文可能被拆成多个 token。

SGLang 的快速入门展示了两种用法：启动 HTTP 服务，让其他应用调用；或者在 Python 进程中创建 Engine，直接做离线生成。聊天后端通常先用前一种，因为它可以沿用已有的 HTTP 客户端。

这也说明，接入 SGLang 不要求你先把业务写成一套新的 Agent 编程语言。官方仍保留前端语言，用于表达生成、选择和分支等程序，但普通聊天请求可以直接走服务端 API。

假设聊天应用原来调用外部服务，接入后的调用关系可以写成：

text 复制代码

聊天页面 → 你的后端 → SGLang HTTP 服务 → 模型计算
              ↓
         对话存档、用户权限

这是一张职责示意图，不是经过压测的部署方案。它要说清的是：换掉模型执行端，不必同时搬走业务状态。

先确认环境，再启动一个小模型

官方快速入门的 NVIDIA 示例以 Linux、CUDA 环境和受支持的 GPU 为前提；其他硬件有各自的安装说明。本文没有在你的 GPU 上运行下面的命令，不能据此保证驱动、显存和模型兼容性。

先按官方安装入口选择与你的硬件匹配的版本。记录实际安装的 SGLang 版本和模型 revision，后面排错时会用到。不要把文档里的 latest 当作可以长期复现的版本号。

安装完成后，可用快速入门中的小模型检查链路。下面将监听地址限制在本机：

bash 复制代码

python3 -m sglang.launch_server \
  --model-path qwen/qwen2.5-0.5b-instruct \
  --host 127.0.0.1 \
  --port 30000

小模型只是帮助你确认服务能工作，不代表它适合你的实际任务。如果模型下载失败，先解决仓库访问问题；如果加载时显存不足，先处理环境和模型容量。此时连请求都还没进入服务，修改聊天页面没有帮助。

用一条请求确认返回的究竟是什么

等服务就绪，再发送请求：

bash 复制代码

curl --fail-with-body http://127.0.0.1:30000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen/qwen2.5-0.5b-instruct",
    "messages": [{"role": "user", "content": "用一句话解释什么是缓存。"}],
    "max_tokens": 80,
    "stream": false
  }'

这段调用示例依据官方接口改写，尚未在本文环境中实跑。你要检查返回体中的消息内容、结束原因，以及是否出现错误；HTTP 请求返回了，并不代表生成内容一定完整。

messages 也不是原封不动地送进模型。服务会按模型的聊天模板，把角色和内容组织成模型认识的输入格式。官方快速入门说明，默认使用分词器携带的聊天模板，也允许覆盖模板。换模型后回答异常时，这条转换链值得先检查，不能仅凭"同样都是 Chat API"断定输入完全一致。

如果上述请求工作，再把它接回聊天应用：修改模型服务地址和模型名，检查原客户端用到的参数是否被当前接口支持。对于工具调用、推理内容或特殊采样参数，逐项验证，别把"接口兼容"理解为所有行为都相同。

页面想边生成边显示，要再走一遍流式链路

把请求的 stream 改成 true，服务就可以通过流式响应发送生成片段。页面仍一次性显示整段文字时，还要检查你的后端有没有先读完整个响应，再转发给浏览器。

这里有两个不同的等待：模型什么时候开始产出文字，应用什么时候把文字交到用户眼前。只看到服务端在输出，不能证明浏览器已及时收到。

同样，用户关闭页面后，你的后端需要处理连接结束；对话是否保存、工具是否继续执行，也要由业务层明确安排。SGLang 能提供模型执行能力，但它看不到应用里的"这个订单已经取消"意味着什么。

接通以后，先留下这次请求

第一次接入的交付物，可以只是一份很小的记录：实际软件版本、模型 revision、启动命令、脱敏请求、完整返回和客户端看到首段文字的时刻。

它能让你区分"服务没起来""请求格式不对""回答不完整"和"页面没有及时显示"。这些情况看起来都是"聊天不好用"，处理位置却不同。

等同一条请求能稳定重现，再接入真实对话。缓存、并发和多卡优化都可以逐步加上；这个能够重放的请求会一直是你判断变化是否有效的起点。