Gateway API Inference Extension 请求路由全景:HTTPRoute 到 EPP 选点的 5 步完整流程详解
Gateway API Inference Extension 请求路由全景:HTTPRoute 到 EPP 选点的 5 步完整流程详解
在 Kubernetes 上部署自托管大模型后,"请求到底发给哪个模型副本"成了绕不开的性能难题。Gateway API Inference Extension 是 Kubernetes 官方推理扩展项目,它在标准 Gateway API 之上引入 InferencePool 与 EPP(Endpoint Picker,端点选择器),让 Inference Gateway 具备模型感知的智能路由能力。本文将用 5 个步骤,带你完整看懂一个推理请求从 HTTPRoute 匹配到最终由 EPP 选中具体端点的全过程。
核心概念:谁在参与这次路由?
在拆步骤之前,先认识 4 个关键角色:
- Gateway(Inference Gateway):支持 ext-proc 协议的数据面代理,如 Envoy、kgateway、GKE Gateway,负责转发请求并执行选点结果
- HTTPRoute:Gateway API 的标准路由规则,负责把请求"分到池子"
- InferencePool:本项目定义的 CRD,把运行模型服务器的 Pod 逻辑分组(类似 Service,但多了推理扩展配置)
- EPP(Endpoint Picker):推理路由器的可插拔实现,负责在池内"挑出最优的那台"
三者分工非常清晰,见上图:平台管理员管理 InferencePool,应用开发者编写 HTTPRoute,集群运维者部署 Gateway。它们之间的关系在 site-src/index.md 中定义了完整请求流程。
InferencePool 和 Service 到底差在哪?一张对比图说清:
共同点是都有 Pod 选择器和端口配置;InferencePool 额外携带 Extension Config(EPP 部署配置)与推理专用配置,这正是"智能选点"的入口。API 类型定义可参考 api/v1/inferencepool_types.go。
完整请求路由流程总览
从官方文档的流程描述(site-src/index.md)可知,一次推理请求共经历 5 步:选池 → 转发请求信息 → EPP 拉取指标决策 → EPP 告知端点 → 网关转发。下面逐步展开。
步骤 1:Gateway 通过 HTTPRoute 选中 InferencePool
这是标准的 Gateway API 行为,与任何 Gateway 用户熟悉的流程一致:
- 客户端发起推理请求,例如 OpenAI 兼容格式的
GET /completions或POST /v1/chat/completions - Gateway 按域名、路径等规则匹配 HTTPRoute
- HTTPRoute 的
backendRef指向一个 InferencePool(而非普通 Service),Gateway 据此确定目标"池子"
✅ 关键点:这一步只决定"发给哪个池",不决定"发给池里哪台机器"。池的选择逻辑完全复用 Gateway API 现有能力,零额外学习成本。
步骤 2:Body-based 路由——模型感知的路由
这是推理网关区别于普通网关的第一处魔法:
- 普通网关只能按路径/Header 路由,而推理请求的关键信息藏在 Body 里——OpenAI 协议中的
model字段指明了要调用的模型名 - Gateway 解析请求体中的模型名(可映射到 LoRA 适配器名),实现"按模型名路由到对应 InferencePool"
- 由此支持模型灰度发布、流量切分等场景,例如把
sql-code-assist和npc-bot两个逻辑模型路由到同一个池内的不同适配器
参考提案 docs/proposals/002-api-proposal/README.md 中对模型名映射与池间路由的完整设计说明。
步骤 3:Gateway 将请求信息转发给 EPP(ext-proc 协议)
当请求应路由到某个 InferencePool 时,Gateway 通过 Envoy 的 ext-proc(External Processing)协议把请求信息交给该池对应的 EPP:
- EPP 实现的是标准 ext-proc gRPC 服务,Gateway 与 EPP 之间全双工通信,支持流式(token 级)透传
- Gateway 还可通过 filter metadata 传递
x-gateway-destination-endpoint-subset,告诉 EPP"本次只能从这些候选端点里选" - EPP 收到的信息包括请求 Header、Body 摘要等,是后续决策的全部依据
协议细节定义在 docs/proposals/004-endpoint-picker-protocol/README.md,其中"Endpoint Subset"一节说明了候选子集如何传递。
步骤 4:EPP 拉取指标并选点——最"聪明"的一步
EPP 的核心价值在于:它不看"过去平均负载",而看"此刻谁最能打"。
- 指标采集:EPP 异步抓取模型服务器的 Prometheus 指标,包括排队请求数(TotalQueuedRequests)、运行中请求数(TotalRunningRequests)、KV Cache 利用率(KVCacheUtilization)等
- 智能决策:基于指标运行打分算法,例如:
- Least Loaded:选负载最轻的副本
- Prefix Cache 感知:优先把请求发给已缓存相同前缀的副本,大幅减少首 token 延迟
- LoRA 亲和:优先发给 GPU 内存中已加载目标适配器的副本,避免冷加载
- 输出结果:EPP 通过
x-gateway-destination-endpoint元数据/请求头把选定的一个或多个<ip:port>端点(有序列表,供重试逐一下探)返回给 Gateway
模型服务器需要暴露哪些指标,见 docs/proposals/003-model-server-protocol/README.md。EPP 内部调度器的循环机制(Filter → Score → Select 三阶段流水线)在架构图中有直观呈现:
请求控制层还包含 PreRequest(入队/直接派发)与 PostResponse(请求结束释放资源、更新指标)两个阶段,确保"选点—服务—反馈"闭环。
步骤 5:Gateway 按选点结果转发,并回报真实服务端点
最后一步是执行与回执:
- Gateway 按 EPP 返回的端点列表转发请求;若配置了重试,则按顺序逐个尝试列表中的端点
- 关键回执:响应阶段,Gateway 必须通过
x-gateway-destination-endpoint-served元数据告知 EPP"这次请求真正由哪个端点服务完成"——因为实际命中的端点可能因重试与 EPP 首选不一致 - EPP 据此校准内部状态(在途请求计数、队列长度等),为下一次选点提供精确依据
如果没有 ready 端点,EPP 会以 503 立即响应;若请求标记为可丢弃(Sheddable)且服务器过载,则返回 429。这些约束均定义在 docs/proposals/004-endpoint-picker-protocol/README.md。
异常场景:EPP 挂了怎么办?
生产环境中必须考虑选点组件的可用性。项目采用 fail-open 策略:当 EPP 不可用时,Inference Gateway 仍会把流量发往池内后端,保证业务不中断。该行为由一致性测试覆盖,参见 conformance/tests/epp_unavailable_fail_open.go 及其声明:"Inference gateway should send traffic to backends even when the EPP is unavailable"。
一图速览:5 步流程清单
| 步骤 | 执行者 | 核心动作 | 关键机制 |
|---|---|---|---|
| 1 | Gateway | 按 HTTPRoute 选中 InferencePool | 标准 Gateway API 匹配 |
| 2 | Gateway | 按 Body 中模型名做感知路由 | Body-based routing |
| 3 | Gateway → EPP | 通过 ext-proc 传递请求信息与候选子集 | x-gateway-destination-endpoint-subset |
| 4 | EPP | 拉取指标、打分选点并返回端点 | KV Cache / Prefix Cache / LoRA 亲和 |
| 5 | Gateway | 转发请求并回报实际服务端点 | x-gateway-destination-endpoint-served |
总结
Gateway API Inference Extension 的请求路由设计可以概括为一句话:Gateway 负责"选池",EPP 负责"选点"。
- 前两步完全复用 Gateway API 生态(HTTPRoute + Body 模型感知),对现有用户零破坏
- 中间通过标准 ext-proc 协议解耦,EPP 是可插拔组件,可替换为任意实现了协议的推理路由器
- 选点决策建立在实时指标(KV Cache、队列、LoRA 状态)之上,配合响应端点回执形成反馈闭环
理解了这个 5 步流程,你再去阅读 api/v1/inferencepool_types.go 中的字段定义、config/crd/bases/inference.networking.k8s.io_inferencepools.yaml 的 CRD 声明,就会一目了然:每个字段都在为这 5 步流程中的某一步服务。



