知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Endpoint 端点与模型路由 > 导读:本文从"报错说 Endpoint 已关闭,但 URL 和 API Key 看着都对,问题到底出在哪"这个具体痛点出发,把 Endpoint(端点)的构成、多端点的动机、四类路由策略、端点状态机与健康检查,以及 ClosedEndpoint 类报错的定位思路讲透,最后给出工程实现参考与踩坑。适合正在做模型接入层、被"模型调不通"反复困扰的后端同学。 ## 一、先建立全局认知 ### Q:Endpoint(端点)到底是什么? A:结论先行——Endpoint 是一个"可调用的模型服务地址",由 URL + 认证信息 + 模型标识(+ 状态)共同构成,它代表"一个可以打过去的模型服务入口"。 ```text Endpoint = { url: "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation", model: "qwen-max", apiKey: "sk-xxx", status: ACTIVE / CLOSED / DEGRADED } ``` 逐字段解读: - **url**:请求打到哪里。注意不同厂商的路径风格差异很大,所以接入层必须做协议转换。 - **model**:这个端点背后具体是哪个模型。同一个厂商地址可以挂不同模型,所以 model 是端点身份的一部分。 - **apiKey**:认证凭证,属于敏感信息,只应存在于接入层配置中。 - **status**:运行状态,决定这个端点当前能不能被选中。这是"路由"和"治理"的抓手。 **类比**:Endpoint 就像一个"电话号码",你通过它联系到具体的模型服务。电话号码本身不代表对方一定在线,所以还需要状态字段和探活机制。 ### Q:为什么需要多个 Endpoint? A:结论先行——四个动机:多模型分工、高可用、灰度发布、成本控制。任何一个动机都足以让你不能只配一个端点。 1. **多模型**:不同任务用不同模型。简单问题用小模型省钱、跑得快;复杂问题用大模型保质量。这是最常见也最直接的动机。 2. **高可用**:一个端点挂了切另一个。同一个模型可能有多个供应商或多个区域入口,互为备份。 3. **灰度**:新模型先接 5% 流量测试,观察效果和稳定性,再逐步放量。 4. **成本控制**:按优先级选便宜的。能小模型解决的就不要用大模型,这是长期成本优化的核心手段。 反面论证:如果只配一个端点,上述四件事你一件都做不了——挂了你只能等,想省钱只能改代码,想灰度只能另起服务。 ### Q:Router(路由器)的职责是什么? A:结论先行——Router 根据请求特征和端点状态,决定这次请求发给哪个 Endpoint,并在没有可用端点时快速失败。 ```text 用户请求 → Router → 选择 Endpoint → 调用模型 → 返回结果 ``` 关键点: - **Router 是纯决策组件,不负责调用**。它输出"用哪个端点",调用由后续的客户端完成。职责分开,才好测试和替换策略。 - **Router 必须考虑状态**。一个"已关闭"的端点即使权重最高也不能选。 - **Router 要有"无可用端点"的明确出口**(如抛 `NoAvailableEndpointException`),而不是随便挑一个死马当活马医。 ## 二、模型路由策略 ### Q:按任务类型路由怎么设计? A:结论先行——先做一次轻量的意图/任务分类,再按分类映射到不同端点,核心思想是"把合适的活儿交给合适的模型"。 ```text 意图分类 → qwen-turbo(便宜快) 知识问答 → qwen-max(准确) 代码生成 → deepseek-coder(专业) ``` 实现要点: - **分类器要便宜**:不要让"路由分类"本身成为瓶颈。可以用规则、关键词、小模型或轻量分类器。 - **映射表要可配置**:任务类型到端点的映射应放在配置中心,能热更新,而不是硬编码。 - **要留兜底**:分类失败时要有默认端点,不能因为分类器异常导致整个链路不可用。 权衡:任务分类路由能显著降低成本(大量简单请求走小模型),但引入了"分类错误"的风险——把复杂问题分到小模型,会导致质量下降。因此分类器要有可观测性,能统计"各类型占比"和"兜底比例"。 ### Q:按负载均衡路由怎么设计? A:结论先行——把请求按权重分散到多个同质端点上,用于分流和提升整体吞吐,常见形态就是加权轮询。 ```text Endpoint A(权重 70%) Endpoint B(权重 30%) ``` 要点: - 权重通常反映"容量差异"或"灰度比例"。新端点权重低,验证通过后逐步提高。 - 同质端点是前提:A 和 B 最好能提供"等效"的服务,否则同一个请求走 A 和走 B 的结果质量可能不同,用户会感知到不一致。 - 负载均衡要和健康检查联动:不可用的端点要立即被摘出轮询集合,不能继续分流量。 ### Q:按优先级 + 降级路由怎么设计? A:结论先行——优先用高质量端点,不可用时自动降级到次优端点,最后用兜底端点保证"至少能回答"。 ```text 优先:qwen-max 降级:qwen-plus(max 不可用时自动切) 兜底:本地小模型 ``` 要点: - **降级要有触发条件**:端点不可用、超时、熔断打开,都应触发降级。 - **降级要有"降级标记"**:告诉业务方"这条回答是降级产生的",便于后续质量分析和用户提示。 - **兜底质量要能接受**:兜底端点通常质量一般,它的目标是"有结果",而不是"结果很好"。所以要评估"降价后质量下滑"是否可接受。 ### Q:灰度路由怎么设计? A:结论先行——用稳定的分流键(如用户 ID)做哈希或取模,把固定比例流量导向新端点,保证同一用户始终走同一条链路。 ```text 用户 ID % 100 < 5 → 新模型(5% 流量) 其他 → 旧模型 ``` 为什么强调"稳定分流键": - 如果用随机数分流,同一个用户一会儿走新模型一会儿走旧模型,体验会来回抖动,也不好对比效果。 - 用用户 ID 取模,能保证"受影响的用户群体稳定",方便做 A/B 对比和问题回滚。 灰度必须配套的能力: - **一键回滚**:只要把灰度比例调回 0,应立即恢复。 - **双路指标对比**:对新旧端点分别统计质量、延迟、失败率、token 成本。 - **可观测的用户标识**:出问题能定位"是哪些用户遇到了新模型的问题"。 ## 三、Endpoint 状态管理 ### Q:Endpoint 有哪些状态? A:结论先行——常见四态:ACTIVE(正常)、CLOSED(已关闭)、DEGRADED(降级中)、DISABLED(管理员手动禁用)。 ```text ACTIVE → 正常可用 CLOSED → 已关闭 DEGRADED → 降级中(响应慢但还能用) DISABLED → 管理员手动禁用 ``` 逐项说明: - **ACTIVE**:健康、可被路由选中。 - **CLOSED**:不可用,路由时必须过滤掉。它可以是"自动熔断导致"的,也可以是"上游服务下线导致"的。 - **DEGRADED**:还能用,但表现变差(如延迟升高、失败率上升)。这个状态的工程价值在于"提前预警"——在彻底不可用前先减少流量,而不是等到 CLOSED 才被动切换。 - **DISABLED**:人为操作,通常用于临时下线维护、合规下线、配置错误时的紧急止血。它与 CLOSED 的关键区别是"来源是人而不是系统自动"。 ### Q:状态之间怎么转换? A:结论先行——主要靠"连续失败次数"触发下行,靠"定时探活成功"触发上行。  *图:熔断器 ACTIVE / DEGRADED / CLOSED 流转* ```text ACTIVE → 连续失败 N 次 → DEGRADED → 继续失败 → CLOSED CLOSED → 定时探活成功 → ACTIVE ``` 关键点解读: - **N 要调**:N 太小会导致网络抖动就误判下线(频繁切换反而更不稳);N 太大则故障发现太慢。需要结合失败率阈值和观测窗口来定,具体参数应结合压测与线上观测确认。 - **DEGRADED 是缓冲带**:它让系统在完全关闭前有一段"减少流量、观察恢复"的窗口,避免状态在 ACTIVE 和 CLOSED 之间反复跳变。 - **恢复要保守**:探活成功后不一定立刻恢复满流量,可以先恢复到 DEGRADED 或小比例流量,确认稳定后再回 ACTIVE。 ### Q:健康检查该怎么设计? A:结论先行——主动探活 + 被动观察双管齐下:主动探活用于恢复判定,被动观察(真实请求的成功率/延迟)用于故障发现。 设计要点: - **探活请求要轻**:不要用一次完整的模型生成做探活,成本和延迟都太高。可以用轻量的列表/校验类接口,或用极短 prompt 的最小生成(**具体可用哪个接口需结合厂商能力确认**)。 - **探活频率要合适**:太频繁会产生额外成本和噪声,太稀疏则恢复慢。通常几十秒到几分钟一次。 - **要区分错误类型**:认证失败(401)和限流(429)性质完全不同——前者应快速摘除,后者应短暂退避而不是永久关闭。健康检查如果不能区分错误类型,就会把"临时限流"误判成"服务下线"。 - **探活要有日志**:状态变化必须留痕,"某个端点什么时候被摘除、什么时候恢复"是排查用户投诉的关键证据。 ### Q:为什么"自动摘除 + 自动恢复"比手动运维更重要? A:结论先行——因为模型端点的故障是高频且瞬时的,人工响应速度跟不上,只有自动化才能保证可用性。 对比: | 方式 | 故障发现速度 | 恢复速度 | 人力成本 | |------|------------|---------|---------| | 手动运维 | 依赖告警和人工反应 | 慢 | 高 | | 自动摘除/恢复 | 秒级到分钟级 | 探活后自动 | 低 | 补充:自动化的前提是"状态判断足够准"。如果判断不准,自动切换会带来"来回抖动",反而比稳定不可用更糟。所以自动化的重点不是"切得快",而是"判得准"。 ## 四、ClosedEndpoint 报错的本质 ### Q:"Endpoint is CLOSED"这类报错的本质是什么? A:结论先行——本质是"路由选中了一个状态为 CLOSED 的端点",也就是接入层认为这个端点不可用,但请求还是打到了它。 ```text 你的请求 → Router 选了一个 Endpoint → 但它状态是 CLOSED → 报错 ``` 这里有个值得注意的矛盾点:如果 Router 真的过滤掉了 CLOSED 端点,就不该选中它。所以出现这个报错,通常意味着以下之一: - Router 没有过滤状态(策略实现缺失)。 - 端点在"被选中之后、调用之前"状态发生了变化(竞态)。 - 请求绕过了 Router,直接指定了某个固定端点。 - 路由缓存里存的是旧的状态快照。 ### Q:这个报错的常见原因有哪些? A:结论先行——四类原因:模型服务下线、API Key 过期、被限流后熔断、配置错误。 1. **模型服务下线了**:上游把该模型/该区域入口关了,你的配置没同步更新。 2. **API Key 过期**:凭证失效后连续认证失败,被健康检查标记为不可用。 3. **被限流后熔断**:短时间内被上游限流(429)导致失败率飙升,熔断器把端点置为 CLOSED。这种情况下"端点本身是好的",是流量模式的问题。 4. **配置错误**:URL 写错、模型名写错、环境串了(把测试 Key 配到生产),都会表现为调用失败并最终被标记关闭。 ### Q:这类问题该怎么排查和根治? A:结论先行——排查先看状态来源(是自动熔断还是人为禁用),根治靠"多端点 + 健康检查 + 自动降级"。 排查顺序: 1. **看状态是怎么变成 CLOSED 的**:查状态变更日志,区分"自动熔断"还是"人工禁用"。 2. **看失败原因**:401 说明凭证问题,429 说明限流,5xx 说明上游故障,连接超时说明网络或地址问题。 3. **看是否有多端点**:如果只有一个端点,那单点故障就是必然而非偶然。 根治手段: - **配置多个 Endpoint 做降级**:单一端点等于单点故障,必须至少有一个备份。 - **加健康检查自动摘除不可用节点**:让系统自己发现并绕过坏端点。 - **区分错误类型再决定状态**:限流导致的失败应该短退避重试,而不是直接关闭端点。 - **告警要先行**:端点进入 DEGRADED 就应告警,不要等到 CLOSED 才通知。 ## 五、工程实现与踩坑 ### Q:一个 ModelRouter 的实现骨架长什么样? A:结论先行——先过滤不可用端点,再按策略选一个,空集合时明确抛错。 ```java public class ModelRouter { private List<Endpoint> endpoints; public Endpoint route(ChatRequest request) { // 1. 过滤掉不可用的 List<Endpoint> available = endpoints.stream() .filter(e -> e.getStatus() == ACTIVE) .collect(toList()); if (available.isEmpty()) { throw new NoAvailableEndpointException(); } // 2. 按策略选一个 return loadBalance(available, request); } } ``` 关键点解读: - **先过滤再选择**:顺序很重要。先选再校验会出现"选中了不可用端点"的尴尬,也就是前文那种报错的成因之一。 - **空集合要显式抛错**:这比返回 null 或随便挑一个更好,因为调用方能明确收到"当前无可用端点",可以走降级。 - **loadBalance 是策略入口**:加权、优先级、灰度都可以在这一层接入,实现"策略可插拔"。 踩坑提醒:`endpoints` 这个列表如果是可变集合且被并发修改,`stream` 遍历时可能抛并发修改异常,或者读到不一致的快照。状态更新应该走"不可变快照替换"或加读写锁,不要原地改元素。 ### Q:路由决策要不要缓存? A:结论先行——可以缓存,但缓存的是"路由规则"而不是"路由结果",且必须能快速失效。 - 缓存**规则**(任务类型 → 端点映射、权重表)是安全的,且能显著减少每次请求的决策开销。 - 缓存**结果**(这个请求该走哪个端点)风险高:一旦端点状态变化,缓存的决策会把你导向已关闭的端点,正是前文报错的成因之一。 - 折中方案:可以缓存"候选端点集合",但在真正调用前仍要校验一次状态,形成"缓存 + 最终校验"的双保险。 ### Q:多租户场景下路由要注意什么? A:结论先行——要保证"租户隔离"和"配额隔离",不能让某个租户的流量把共享端点打满导致其他租户不可用。 要点: - **租户维度的配额**:每个租户在共享端点上的并发/速率要有上限。 - **可选的专属端点**:对高价值租户可分配专属端点,避免被邻居影响("吵闹邻居"问题)。 - **路由决策要带租户上下文**:同一任务类型,不同租户可能被路由到不同端点,这要求 Router 的输入里包含租户信息。 - **计费要能按租户归集**:路由层是记录"这个请求走了哪个模型"的最佳位置之一。 ### Q:路由层的可观测性该记录什么? A:结论先行——至少记录"决策输入、决策输出、端点状态、降级情况"四类信息。 | 记录项 | 用途 | |--------|------| | 请求特征(任务类型、租户、灰度标识) | 复现路由决策 | | 选中的端点与策略 | 定位"为什么走了这个模型" | | 端点当时的状态 | 判断是否命中了降级 | | 是否降级、降级到哪 | 质量分析、用户提示 | | 各端点失败率/延迟 | 容量规划、权重调整 | 理由:路由是"隐蔽的决策点"——用户看到的是一句回答,但背后可能已经经历了"主模型不可用 → 降级到备用 → 结果稍差"。如果路由层不记录,这个质量下降将完全不可归因。 ### Q:路由失败时应该"快速失败"还是"逐个试一遍"? A:结论先行——要分场景:用户同步请求倾向快速失败 + 有限降级;后台批处理可以逐个尝试。 | 场景 | 策略 | 理由 | |------|------|------| | 在线同步请求 | 快速失败 + 一次降级 | 用户不想等,多试一轮可能超出耐心 | | 在线流式请求 | 首字前允许一次切换 | 首字前切换代价低;已开始输出则不宜切换 | | 后台批处理 | 可逐个尝试 | 无人实时等待,成功率优先 | | 关键任务 | 逐个尝试 + 记录失败链 | 需要可追溯每次失败原因 | 关键判断依据是"**用户能不能等**"和"**切换的代价有多大**"。流式场景尤其要注意:一旦已经开始输出,切换端点会导致"两段内容拼接",用户体验很差,所以只能在首字之前切换。 ### Q:端点权重该怎么定? A:结论先行——权重应反映"实际容量与质量"的组合,并且必须动态可调、可观测,而不是拍脑袋写死。 定权重的依据: - **容量差异**:不同端点或不同供应商的配额与吞吐不同,权重应与之匹配,否则高权重端点会被打爆。 - **质量差异**:质量更好的端点可以给更高权重(在成本可接受的前提下)。 - **灰度需要**:新端点从低权重起步,验证后逐步提高。 - **成本**:便宜且够用的端点可以承担更多流量。 可观测要求:必须按端点维度看成功率、延迟、错误类型分布。如果某个端点权重高但失败率也高,说明权重设置有问题——这是权重调优的数据依据。 ### Q:端点配置变更怎么做到不停机生效? A:结论先行——配置外置 + 热更新 + 变更校验 + 灰度,四步缺一不可。 - **配置外置**:端点列表(URL、模型、Key 引用、权重、状态)放在配置中心,而不是硬编码在代码里。 - **热更新**:变更后不重启即可生效;但更新要走"不可变快照替换",避免并发中出现"半个新配置"的中间态。 - **变更校验**:新配置上线前要校验(URL 可达性、Key 有效性、模型名合法性)。**大量线上事故就是"配错了 URL"或"把测试环境的 Key 配到了生产"。** - **灰度**:先小流量验证,再全量。 ### Q:怎么评估路由策略是不是真的有效? A:结论先行——用"成本、成功率、质量、延迟、兜底比例"这几个维度的对比数据说话,而不是凭感觉。 - **成本**:路由策略上线前后,单位请求的平均 token 成本是否下降? - **成功率**:是否因为路由到某些端点导致失败率上升? - **质量**:可以通过抽检或 LLM as Judge 比较"新旧路由策略下回答的质量评分"。 - **延迟**:P50 / P99 是否改善(尤其是小模型承接简单任务后)。 - **兜底比例**:多少请求最终走了兜底端点?如果比例很高,说明主端点不稳定或任务分类器不准。 ### Q:跨区域、跨云路由要考虑什么? A:结论先行——要考虑网络延迟、数据合规、配额独立、故障域隔离四件事。 - **网络延迟**:跨区域调用会引入额外往返时延,对流式首字延迟影响尤其明显。 - **数据合规**:数据出境的合规要求可能直接限制"能不能路由到某个区域的模型"(**具体需结合所在行业的合规要求确认**)。 - **配额独立**:不同区域的配额通常独立计算,路由时要按区域分别限流。 - **故障域隔离**:不要把所有端点放在同一个云或同一个区域,否则一次区域性故障会同时打掉主备,等于没有冗余。 ### Q:端点健康检查用"真实请求"还是"专门探活接口"? A:结论先行——优先专门探活接口(轻量、低成本),必要时叠加"真实请求成功率"作为补充,两者都不完美。 | 方式 | 优点 | 缺点 | |------|------|------| | 专门探活接口 | 成本低、频率可控 | 可能探活通过但生成接口已坏 | | 真实请求统计 | 反映真实可用性 | 需要足够流量才能判断,故障发现滞后 | | 极短 prompt 生成 | 最贴近真实链路 | 每次探活都有 token 成本 | 推荐组合:用轻量接口做高频探活(快速发现恢复),用真实请求的成功率做校准(发现"探活通过但业务失败"的情况)。 ### Q:端点"连续失败 N 次"的 N 怎么定? A:结论先行——不能只靠次数,建议用"失败率 + 最小请求数 + 滑动窗口"三要素;单纯数次数容易被低流量场景误导。 - **只看次数的问题**:如果某个端点一分钟只有 1 个请求,"连续 3 次失败"意味着 3 分钟,故障发现太慢;反之如果流量很大,3 次失败可能只是几毫秒内的网络抖动,会误判。 - **加入最小请求数**:样本不足时不做判定,避免"1 个请求失败 = 100% 失败率"的误熔断。 - **滑动窗口**:只看最近一段时间(如 1 分钟)的数据,避免历史失败干扰当前判断。 - **按错误类型区分**:认证失败应立即摘除;限流(429)应短暂退避而非永久摘除。 - 具体阈值需结合流量规模与压测结果确认,没有通用答案。 ### Q:为什么端点状态要能被"人工强制设置"? A:结论先行——因为自动判断有盲区,人工干预是必要的兜底,尤其在"已知上游要维护"或"配置错误需紧急止血"时。 人工设置的典型场景: - **上游提前通知维护窗口**:与其等探活失败,不如提前把端点置为 DISABLED。 - **配置错误需紧急止血**:新配置上线后第一时间发现问题,必须能立刻禁用。 - **合规要求下线**:某些模型可能因合规原因必须立即停止使用,自动机制不会知道这个原因。 - **演练需要**:主动禁用某个端点,验证降级链路是否有效。 设计要求:人工状态要能被区分(DISABLED),并且不能被自动恢复逻辑无条件覆盖——否则"人工禁用"会被下一次探活成功冲掉。 ### Q:端点数量是不是越多越好? A:结论先行——不是。端点越多,路由决策空间越大、状态管理越复杂、观测越难聚焦,边际收益会迅速下降。 - **决策复杂度**:候选集变大后,权重与优先级更难调,也更容易出现"某个端点长期吃不到流量"或"某个端点被打爆"的失衡。 - **状态管理**:每个端点都要健康检查、状态机、告警,运维成本线性增长。 - **观测难度**:端点过多会让指标看板失去可读性,问题定位变慢。 - **建议**:按"主 + 备 + 兜底"三层设计,通常 2-4 个端点足以覆盖绝大多数场景;更多端点按需引入,并定期清理长期无流量的端点。 ## 小结 - Endpoint 是模型服务的"电话号码",由 URL + 认证 + 模型 + 状态构成;单端点等于单点故障。 - 多端点的四个动机:多模型分工、高可用、灰度、成本控制。 - Router 只负责决策不负责调用;正确顺序是"先过滤不可用端点,再按策略选择,空集合显式抛错"。 - 四类路由策略各有用途:任务类型路由省钱、负载均衡提升吞吐、优先级+降级保可用、灰度路由控风险。 - 端点四态中 DEGRADED 是关键的缓冲带;状态下行靠连续失败,上行靠探活成功,参数需结合观测确认。 - ClosedEndpoint 之类报错的本质是"选中了不可用端点",常见成因包括 Router 未过滤、状态竞态、绕过路由;根治靠多端点 + 健康检查 + 自动降级。 ## 思考题 1. 如果 Router 已经过滤掉了 CLOSED 端点,为什么还会出现"选中了 CLOSED 端点"的报错?请列出至少三种可能的实现缺陷。 2. 限流(429)导致的失败,应该把端点标记为 CLOSED 吗?为什么?更合理的处理是什么? 3. 灰度路由为什么强调"用用户 ID 取模"而不是"随机分流"?两者在效果对比上有什么本质差异? 4. DEGRADED 状态解决了什么问题?如果去掉这个状态、只保留 ACTIVE 和 CLOSED,会出现什么行为? 5. 路由决策缓存应该缓存什么、不该缓存什么?如果缓存了错误的东西会导致什么故障? 6. 多租户共享端点时,"吵闹邻居"问题该怎么在路由层缓解?请给出至少两条措施。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入