Standalone 模式
概要
新增 standalone 模式:Router 自己作为 OpenAI 兼容的入口和反向代理,路由流水线在进程内执行,不经过 Envoy 和
ext_proc。vllm-sr serve 默认使用它。Envoy 仍以显式模式 --gateway extproc 提供:vllm-sr 在 Router 前面起
Envoy,Router 和今天一样提供 ext_proc。Kubernetes 也默认 standalone 模式;要接入已有的 Envoy 类网关,仍用 extproc。
两种模式共用同一个路由核心。核心与传输无关,ext_proc 和 HTTP 是它的两个薄适配器。在核心之外,standalone gateway 增加:借鉴 Envoy cluster/endpoint 的上游层;一等公民的 timeout、retry、fallback;在 Router 内部 执行 looper 算法、不再绕回 Envoy 的请求图执行器;以及基于不可变、版本化快照的配置体系,支持预热、原子 切换、drain、历史和回滚。
本提案取代 独立 HTTP Gateway。那份设计把网关做成单独的实验性二进制;本设计让 Router 二进制同时承担两种角色,只保留一份配置文档,并把 standalone 设为默认模式。它对共享引擎、统一响应流水线和 looper 执行器的分析继续适用。
已确认的决定
- Router 新增 standalone 模式:接收 OpenAI 兼容流量,在进程内执行路由流水线,并自己代理到模型后端。
--gateway standalone|extproc在所有 target 上选择模式,默认standalone。docker 上 standalone 只起 Router 容器, 模型 runtime 在容器内,由 Router 自己提供 listener;extproc就是今天的栈:vllm-sr在 Router 前面起一个 Envoy 容器,Router 提供 ext_proc。- Kubernetes 也默认 standalone。Helm chart 里 Router pod 提供配置中的 listener,Service 对外暴露它们,readiness 用
/ready。operator 也默认 standalone,它的spec.gateway集成会选择 extproc。接入 Envoy Gateway、AI Gateway、 Istio、KServe 时仍可选extproc(50051 端口上的 ext_proc Service 和那条五个 header 的规则)。 - 一切都跑在容器里:
--target docker(默认)或--target kubernetes(v0.4.0 已发布的k8s保留一个版本作为隐藏 别名,使用时给出警告),没有裸机 target。--platform cpu|rocm|cuda对两个 target 都生效:docker 上选择镜像和 GPU 透传,kubernetes 上选择同一个镜像,并在生成的 Helm values 里加上 GPU 资源请求(amd.com/gpu或nvidia.com/gpu)。engine 模式(vllm-sr serve MODEL --engine)在 docker target 上用同一个镜像在容器里跑模型 runtime, 使用发布版本固定的 ROCm 或 CUDA 依赖;数值一致性仍须按硬件与 profile 验证。 - PyPI 上只发布
vllm-sr。Router 二进制和模型 runtime(vllm-srun)只随一个镜像家族发布:vllm-sr(CPU, amd64 和 arm64)、vllm-sr-rocm和vllm-sr-cuda(amd64),覆盖 docker 和 kubernetes、两种模式以及 engine 模式。 原来的extproc和extproc-rocm镜像在一个版本内作为同一 digest 的别名 tag。上游 Envoy 只用于 docker 上的extproc。 - Router 与模型 runtime 之间仍是 Unix 域套接字上的 HTTP/JSON;测出开销之后再考虑二进制快路径。在 CPU 上测得 传输约占一次 runtime 调用的 2%,所以不做快路径(见结果)。
- 首发必须支持 timeout、retry、fallback。
- looper 请求图完全在 Router 内部闭环,不再绕回 Envoy。
- 配置体系模块化、版本化,支持热更新和回滚,借鉴 Envoy 配置设计的核心思想。
背景
standalone 实现前的请求链路:
client -> Envoy -> ext_proc(gRPC,默认整包缓冲 body)-> Router(Go)-> 通过 Unix 套接字调用模型 runtime
<- header 和 body 修改 <-
Envoy -> 按 x-selected-model 选中的后端 -> Envoy -> ext_proc(响应阶段)-> Router -> Envoy -> client
默认 Envoy 模板会 处理请求头、请求体、响应头、响应体,因此每个请求要经历四条 ext_proc 消息,并对请求体和响应体 各做一次整包缓冲。
looper 请求图(fusion、quorum、置信度升级、ReMoM、ratings、grounding、workflows)的每一个中间调用,都带着内部
header x-vsr-looper-request、x-vsr-looper-secret、x-vsr-looper-decision、x-vsr-looper-iteration 打回本地
Envoy listener,再进入 ext_proc,被识别为内部请求后才派发到后端:每一跳都是 Router -> Envoy -> Router -> Envoy ->
后端。
这条链路的问题:
- 部署和排障都要同时理解两套配置、两种心智模型:Envoy 的和 Router 的。
- looper 的回环只是因为 ext_proc 无法发起经过 Envoy 路由的上游调用;它拉长了每一跳,让语义变绕,还需要内部密钥 header 防伪造。
- 每个本地栈都要在 Router 前面起一个由第二套模板渲染的 Envoy 容器,即使只是一台机器、一个用户。
模式
网关传输(--gateway)与服务能力(--engine)是独立选择。默认 Router 模式;传入 MODEL 只改变判断模型,不会关闭路由。Engine 模式禁用 recipe 路由,仍保留前端和原生模型 API。
| 命令 | 运行什么 | 客户端流量入口 | 适用 |
|---|---|---|---|
vllm-sr serve(= --gateway standalone,默认) | Router 容器,它托管的 runtime 进程在容器内 | Router 自己的 OpenAI 兼容端口 | 单机、开发、边缘、多数自托管 |
vllm-sr serve --gateway extproc | vllm-sr 起的 Envoy 容器,在 Router 容器(ext_proc)前面 | Envoy | 需要限流、mTLS、复杂路由匹配等 Envoy 能力 |
vllm-sr serve MODEL --engine | 持久前端与模型 worker(Engine 模式) | 前端的 System One API | 在自己的代码里调用模型 |
两种 gateway 模式共用一个路由核心:standalone 使用 HTTP 适配器,extproc 模式(下文称 Envoy 模式)使用 ext_proc
适配器。Kubernetes 上 --target kubernetes 以任一模式安装 Helm chart,你自己运行的 Envoy 类网关(Envoy
Gateway、AI Gateway、Istio、KServe)以 extproc 模式接入。
正交参数:
--target docker|kubernetes:默认docker。--platform cpu|rocm|cuda:两个 target 上都选择镜像;docker 上透传 GPU,kubernetes 上加 GPU 资源请求。--container-runtime docker|podman(原--runtime,保留一个版本作为隐藏别名,使用时给出警告)。serve的每个参数属于一个分组,分组写明它适用于哪里:docker、kubernetes、engine 模式或其中几种。--platform、--image、--log-level三者通用;--minimal、--readonly两个 target 通用;--image-pull-policy、--container-runtime用于 docker 和 engine 模式。--help按分组列出,在分组不适用 的地方使用其参数会报错。--minimal:不起 dashboard 和观测栈。