操作场景
前缀缓存路由根据请求 Prompt 的前缀相似度，将具有相同或相似前缀的推理请求稳定路由到同一推理实例，使该实例上已生成的 KV Cache 能被持续命中，从而跳过 prefill 阶段、降低首 Token 延时（TTFT）。
前置条件
1. 已创建 AI 网关实例且处于运行中状态，网关版本 ≥ 3.9.5；
2. 已创建多个模型服务（至少 2 个），且下游推理服务支持 KV-Cache（键值缓存）能力；
3. 了解所选模型服务是否支持 KV-Cache（请查阅推理引擎或模型供应商文档确认）。
操作步骤
步骤 1：进入模型 API 配置页
1. 登录 微服务平台控制台 ，左侧导航栏选择 AI 网关进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的"ID"，进入该网关实例的基本信息页面；
3. 选择左侧导航栏模型管理 > 模型 API；
4. 单击新建或编辑已有 API；
5. 完成基本信息配置后，进入第二步：选择模型服务。
步骤 2：选择服务类型和路由策略
1. 选择服务类型为多模型服务；
2. 在路由策略区域，选择前缀缓存路由（缓存感知路由）。
步骤 3：配置目标模型服务
1. 在目标模型服务区域，系统自动拉取已注册的推理实例列表；
2. 通过勾选参与前缀缓存路由的模型服务（可多选，至少选 2 个）；
3. 每个服务展示以下信息供参考：
服务名称（如
sglang-horizon-01）协议类型（custom 协议 / openai 协议）
在线状态（在线/离线）
4. 未勾选的服务显示半透明状态，提示“未勾选的服务仍可正常接收请求，但不会执行前缀缓存匹配逻辑”；
5. 头部显示已选数量
配置项 | 说明 |
模型服务池 | 从已注册模型服务中勾选，至少选择 2 个 |
候选数量范围 | 2 ~ 50 个 |
步骤 5：保存配置
单击确定保存模型 API 配置，前缀缓存路由立即生效。
运行指标查看
配置完成后，可在模型 API 详情页的“路由策略”Tab 查看运行指标：
指标 | 说明 |
缓存命中率 | 命中数 / 总路由数，反映 KV Cache 复用效果 |
节省 Token | 引擎侧累计缓存的 Token 数量 |
降级次数 | 因负载不均退化为普通路由的次数 |
注意事项
1. KV-Cache 能力依赖：前缀缓存路由的效果取决于下游推理服务是否支持 KV-Cache。不支持的服务选择后仍可保存配置，但前缀缓存不生效，请求退化为普通负载均衡，不会报错。
2. 双策略动态切换：当检测到实例间负载严重不均时，路由器自动从"前缀匹配模式"切换到"最少连接模式"，避免单实例过载。负载恢复后立即回到前缀匹配。
3. 超长 Prompt 处理：超过一定长度的 prompt 将截取首部参与前缀匹配，不影响正常转发。
4. 路由记录自动维护：网关内部自动维护前缀路由记录表，无需手动干预。当推理实例下线或健康检查失败时，该实例的路由记录会被自动清理。
5. 手动清除路由记录：在详情页支持手动清除全部或指定实例的路由记录，适用于模型热更新、缓存污染、灰度完成流量切换等场景。清除过程不阻塞正在处理的请求。
6. 与 Fallback 的配合：前缀缓存路由可与全局跨服务 Fallback 配合使用，当候选服务不可用时自动触发 Fallback 切换到备用服务。
