二、解决什么问题
智能路由的核心是前缀缓存感知：调度器感知各副本已缓存的 Token 前缀，把请求优先路由到"前缀最相似"的副本上，从而：
·提高 KV Cache 命中率，减少重复 Prefill 计算。
·降低首 Token 延迟（TTFT） 与请求端到端延迟。
·提升同等资源下的整体吞吐。
三、两个核心组件：Gateway 与 Scheduler
智能路由开启后，平台会在服务组下额外拉起一组智能路由组件，由两个角色构成：
| 组件 | 命名规则 | 提供的功能 |
| 网关（Gateway） | <LLM 服务名称>-gateway | 流量入口与请求处理中心。接收用户请求，按 Scheduler 的决策转发到目标推理实例。 |
| 调度器（Scheduler） | <LLM 服务名称>-scheduler | 智能调度的大脑。按调度插件为每个请求选择最优目标实例。 |
一次请求的完整调度过程如下：
一次请求的完整调度链路：
1. 解析：Gateway 不做转发的判断，把转发选择权外包给 Scheduler ， EPP 负责解析请求体，读取 model 与 prompt 字段；
2. 过滤（Filter）：剔除不健康、角色不匹配（如 prefill 实例只负责算首 token，decode 实例只负责后续生成，一个 decode 阶段的请求发给 prefill 实例是不合法的）的副本，得到候选集；
3. 打分（Scorer）：EPP 各插件对候选副本打分，按权重加权求和得到 total得分；
4. 选择（Picker）：选 total 得分最高的副本，回给 Envoy 进行转发。
四、适用场景
适合开启智能路由功能的用户场景：
·LLM 文本生成类服务（对话、续写、长文本等），请求间存在可复用的 Prompt 前缀；
·服务部署了多个副本（建议 ≥ 2）；
·有明显的可复用前缀特征，例如：固定 System Prompt、长文档问答、多轮对话、Agent 模板化调用等。
六、新建智能路由
在 在线服务 页面，选择需要开启智能路由的服务进入服务组详情页面，智能路由默认不开启，需用户手动配置后启动。
| 配置项 | 参数解释 |
| 智能路由开关 | 开 / 关；默认关闭，首次开启需填写参数配置 |
| 机器来源 | 用户按需选择“从 CVM 机器中选择/从 TIONE 平台购买”，请注意若选择用户已有资源组中的机器部署智能路由，需保证在线服务的资源组机器和智能路由的资源组机器网络互通。 |
| 网关资源（Gateway） | 建议不少于 4 核 8G ，且至少配置2个副本，确保某副本故障时，流量可自动切换至健康副本以保障服务的高可用。 |
| 调度器资源（Scheduler） | 建议不少于 2 核 4G，调度器故障时网关会自动降级为轮询策略继续转发请求，调度器恢复后再自动切回智能路由。 |
请注意：一旦用户在此开启了智能路由，则原本在公共网关或 CLB 实例上配置的负载均衡调度算法均会失效，统一被智能路由接管。智能路由会同时作用于公共网关与 CLB 直连两种模式下的服务调用。
七、智能路由已开启
智能路由功能开启后，会在服务组列表页面同时展示智能路由的实例列表区域。用户后续也可视线上请求流量情况继续扩容或缩容智能路由的部署资源。
开启智能路由后，在该服务的【服务调用】页面也可看到“智能路由生效中”的文案提示，此处的多种服务调用模式（公共网关、CLB 直连）均会经过智能路由的前缀感知网关统一路由。无论是否开启智能路由，对用户而言服务调用地址都不会发生变化：
·服务的调用 URL / 入口保持现状不变，不会存在"智能路由"和"非智能路由"两个不同入口；
·只要智能路由处于正常运行中，无论走公共网关还是 CLB 模式，请求都会默认经过这层智能路由；
·当智能路由异常停止或被用户手动停止后，调用入口会自动回退到公共网关或 CLB 原生的负载均衡算法。
这意味着：业务侧无需改动任何调用代码即可试用，也无需担心智能路由故障导致服务不可用。
八、智能路由详情
单击智能路由的实例名称可进入详情页，包含 基本信息 / 监控 / 事件 / 日志 / 变更记录 五个页签。详情页的重要信息说明如下：
九、监控指标说明
监控支持下拉选择具体展示哪一个实例（网关 Gateway 或调度器 Scheduler）的指标。
| 指标名称 | 上报实例 | 单位 | 指标解释 |
| QPS | Gateway | 次/秒 | 每秒通过智能路由 Gateway 的请求数 |
| 入流量 | Gateway | Mbps | Gateway 网卡接收的入站带宽，包含请求体（prompt、图片等）的传输量 |
| 出流量 | Gateway | Mbps | Gateway 网卡发出的出站带宽。流式响应下 token 逐个返回，出流量持续较久 |
| 活跃连接数 | Gateway | 个 | 当前保持的 TCP/HTTP 长连接数量，包括 SSE 流式连接和普通请求连接 |
| 路由命中率 | Scheduler | % | 调度器第一次路由即命中最优后端的请求占比。命中率 = 一次命中数 / 总调度次数 |
| 延迟 P50/P95/P99 | Gateway | ms | 从 Gateway 收到请求到返回首个 token（TTFT）或完整响应的端到端延迟分位数 |
| 首 Token 延迟 (TTFT) | Gateway | ms | Time To First Token——从请求到达 Gateway 到流式返回第一个 token 的时间 |
| 请求错误率 | both | % | 返回 4xx/5xx 的请求占总请求的比例。按错误码分类：超时、后端不可用、OOM、模型未找到等 |
| CPU 使用率 | both | % | Gateway / Scheduler 进程的 CPU 占用比例 |
| 内存使用率 | both | % | Gateway / Scheduler 进程的内存占用比例。连接状态、请求缓冲、路由表等数据占用 |
其中，关键指标解读建议：
·路由命中率（Scheduler）是判断智能路由价值的核心指标：命中率持续偏低，说明请求前缀复用度不高，收益有限。
·TTFT / P95 延迟（Gateway）是判断体感收益的核心指标，建议可开启前后对比。
·CPU / 内存使用率接近上限时，说明路由组件本身成为性能瓶颈，应上调资源配置。
十、变更记录
平台会记录智能路由服务的每一次变更操作，包括开启、停止、配置变更，使得用户操作可回溯。
十一、服务请求记录
针对开启了智能路由功能的在线服务，可在服务的服务请求记录页面查看路由策略的生效情况以及具体命中的实例 IP 信息。若推理请求到达时智能路由服务因后台异常等原因未生效，则该列会展示为“智能路由未生效”。
十二、智能路由策略说明
平台的智能路由功能会自动计算每个副本的逐项得分（前缀缓存得分、负载得分），最终将请求路由到得分最高的副本上，例如以下 3 个副本的打分日志：
selectedEndpoint: ep-…-2tnq2-rank-0(172.17.33.141)scores: ep-…-2tnq2-rank-0(172.17.33.141)(shared-approx-prefix-cache-scorer=1.000, token-load-scorer=1.000, total=20.000) ep-…-gbqw2-rank-0(172.17.35.18) (shared-approx-prefix-cache-scorer=0.000, token-load-scorer=1.000, total=10.000) ep-…-kxpnw-rank-0(172.17.33.101)(shared-approx-prefix-cache-scorer=0.000, token-load-scorer=1.000, total=10.000)
这份日志里有 3 个候选副本，每个副本都有 2 个打分字段，外加 1 个合计值：
| 字段 | 说明 |
| shared-approx-prefix-cache-scorer | 近似前缀缓存得分（前缀越匹配得分越高） |
| token-load-scorer | 负载得分（正在处理中的 token 越少分越高） |
| total | 各插件得分 × 权重后相加，选 total 最高者 |
3 个副本的负载分完全相同（都是 1.000），区别只在前缀缓存：只有副本 2tnq2 命中（1.000），另两台为 0。最终 total 为 20 / 10 / 10，选中 2tnq2 副本；也就是说在负载打平的情况下，前缀缓存这一项直接决定了胜负，这正是智能路由加速的来源。智能路由的请求路由决策分为两个阶段：
·阶段一（缓存亲和）：若任一副本的缓存命中，则优先把请求打到命中的副本；
·阶段二（负载均衡）：没有副本达到命中阈值时，退化成按预测负载最低来选。
十四、状态码速查
| 状态码 | 来源 | 典型场景 | 能否重试 |
| 200 | 模型服务 / EPP | 正常推理；/health 通过；/metrics 正常 | – |
| 400 | EPP | 请求体非合法 JSON、缺 model 字段、payload 类型不支持 | 改请求后重试 |
| 429 | EPP | 找不到目标 endpoint、系统饱和丢弃可降级请求、Flow Control 容量拒绝 | ✅ 可重试，需退避 |
| 500 | EPP | 空调度结果、请求体重写 marshal 失败、流控内部错误 | 可重试，需服务端排查 |
| 503 | EPP 或 Envoy | 无 endpoint candidates、排队超时、健康检查不通过、fallback 不可达、Pod 建连失败、熔断 | 视场景 |
| 504 | Envoy | 上游请求超时（主路由 timeout 已配 86400s，正常不应比模型服务更早超时） | 视场景 |
十五、日志关键字速查表
在 Scheduler 日志中搜索以下关键字，可快速定位问题：
| 想看什么 | 搜索关键字 | 关注点 |
| 某个请求的完整调度链路 | <请求头 x-request-id> | 该请求相关日志都会带此字段 |
| 某个请求的调度结果与打分 | Scheduling decision | selectedEndpoint（最终选的）+ scores（各插件打分） |
| 多副本在途负载是否一致 | shared-inflight-load-debug | 看 aggregated 是否一致 |
| 多副本前缀索引是否一致 | Prefix cache state | 看 total entries 是否一致 |
| 精准前缀匹配结果 | lookup v2 finished | podToKeyLen：每个实例上的前缀匹配长度 |
| KVEvent 是否订阅成功 | Subscriber created and started | 无此日志说明订阅失败 |
| KVEvent 订阅被过滤的原因 | Skipping KV-events subscription for non-matching endpoint | 对比 expectLabels 与 actualLabels（标签不匹配是订阅失败的常见原因） |
| 实例重启后缓存是否清空 | All blocks cleared event received | 实例重启应主动发送清空事件 |
| PD 分离的路由决策 | PD disaggregation: prefill+decode routing | decodeEndpoint / prefillEndpoint |
十六、健康检查与指标端点
| 路径 | 说明 |
| /health | 经 Envoy 进入 EPP，由 EPP 直接返回（不转发模型服务）。PD 健康策略：至少一个 prefill-capable + 至少一个 decode-capable endpoint |
| /metrics | Envoy 上会被改写到 EPP 的 /aggregated-metrics 并跳过 ext_proc。Pod 内可直接 curl -s http://127.0.0.1:9090/aggregated-metrics |
十七、常见现象与排查动作
| 现象 | 排查动作 |
| 命中率长期偏低 | ① 查 Prefix cache state 各副本 total entries 是否一致；② 查 APPROX_CACHE_BLOCK_SIZE_TOKENS 是否与引擎 block size 对齐；③ 确认业务前缀是否真的可复用 |
| 出现假 429（看起来没打满却 429） | 检查 SHARED_REQUEST_TRACKER_SYNC：多副本用 gossip 会有同步延迟，建议改 Redis |
| 个别 Pod 超顶 | 同上；并检查 CACHEAWARE_MAX 与 FLOW_CONTROL_MAX 是否错开 |
| 两个服务互相干扰、命中率莫名下跌 | 检查 ETCD_NAMESPACE / REDIS_NAMESPACE / TI_SERVICE_ID 是否按服务隔离 |
| 精准前缀一直不生效 | 查 Subscriber created and started；若无则搜 Skipping KV-events subscription for non-matching endpoint 核对 Pod 标签 |
| KVEvent 有丢失 | 搜 Sequence gap detected，并确认 flush messages after replay 处理正常 |
十九、问题1：为什么我在新建页看不到"智能路由"这个参数？
非 LLM 场景服务。
20、问题2：我用的是自定义镜像，参数展示了，是不是一定能生效？
不一定。自定义镜像模式下参数默认展示，但需由用户自行保证只在 LLM 场景下开启。若非 LLM 场景，即使开启，实际请求路由过程中也不会真正生效，会回退到公共网关或 CLB 原生的默认负载均衡算法。
21、问题3：开启后业务调用需要改代码或换 URL 吗？
不需要，调用入口保持完全一致。
22、问题4：智能路由挂了是否会导致服务不可用？
不会。智能路由异常或停止后，流量自动回退到公共网关 / CLB 原生负载均衡算法。但此期间不享受加速收益。
23、问题5：怎么判断开了到底有没有收益？
你可通过以下三步判断：① 看监控的路由命中率（Scheduler）；② 对比开启前后的 TTFT / P95 延迟（Gateway）；③ 看服务请求记录的"智能路由策略"列是否为具体策略名而非"智能路由未生效"。
24、问题6：路由命中率很低怎么办？
命中率取决于请求前缀的复用程度。若业务前缀高度个性化、复用度低，收益天然有限。可考虑：优化 System Prompt 使其稳定一致、将公共前缀前置、提升并发让副本缓存更"热"。
25、问题7：需要给智能路由配 GPU 吗？
不需要。智能路由组件仅消耗 CPU 与内存。
26、问题8：多模型 / 多服务之间也想做智能路由，支持吗？
本功能不支持。请使用云上 AI 网关产品：将 TIONE 服务注册到 AI 网关后，在 AI 网关侧配置多服务路由策略。
27、问题9：怎么知道某个请求到底被路由到哪台副本了？
你可通过以下三个途径排查：① 看响应头 X-HC-Decode-IP / X-HC-Prefill-IP；② 看服务请求记录的"命中实例"列；③ 在 Scheduler 日志搜该请求的 x-request-id 或 Scheduling decision。