作者:苏渡苇
项目地址:https://github.com/iweidujiang/spring-insight(欢迎 Star)
上一篇把配额拦住了,模型挂了呢?
上一篇讲 tryAcquireQuota:超限不调模型,告警照推指标。
还有另一半更常见——key 没配、接口 401、推理模型只吐思考草稿、JSON 被 max_tokens 截断。
这些如果往上抛,控制台详情页会变成一片红,监测中心看起来像挂了。
Insight 把 AI 当成可选项,约定是:解释失败也走 200,body 里带 degraded=true,把原因写给人看。
本文要讲的技术点就是这套降级:gateOrNull 提前拦、completeExplain 认不认模型原文、Controller 连未预期异常也塞成同一份结构。
代码在此:
InsightAiExplainService、InsightAiExplainSchema、InsightAiController
先过门,过不了就带着说明回来
Trace / 错误 / 拓扑解读进服务后,第一件事不是拼 prompt,而是 gateOrNull:
1private Map<String, Object> gateOrNull(InsightServerAiProperties properties, 2 String kind, 3 Map<String, Object> nav) { 4 if (!properties.isEnabled()) { 5 return InsightAiExplainSchema.buildResponse(kind, true, 6 "AI 未启用。请到控制台「设置」打开 AI,或「复制 Context」粘贴到任意 LLM。", 7 ...); 8 } 9 if (!properties.isInvokeReady()) { /* 缺 base-url / api-key */ } 10 if (!isOpenAiCompatible(properties.getProvider())) { /* provider 不对 */ } 11 return null; 12} 13
返回非 null,就是已经组好的降级体,调用方直接 return。
开关没开、key 没填,根本不会发 HTTP,和上一篇超限 skipped 是同一类:能确定调不成,就别去撞模型。
null 才表示门开了,后面才 callChatCompletions。
门的判断和真正调用拆开,设置页灰掉按钮用的 GET /api/v1/ui/ai/status 也只看 enabled / invokeReady,不必先打一次解释接口。
HTTP 200 加 degraded,不要 5xx
统一响应由 InsightAiExplainSchema.buildResponse 拼:schemaVersion=1、kind、degraded、summary / evidence / suggestions,外加一份兼容旧 UI 的 markdown。
Controller 几乎只做一件事:服务返回 map 就 ResponseEntity.ok,Trace 不存在才 404,那是数据没有,不是模型没有。
连服务里漏掉的异常,接口层也接住再包成降级体:
1@PostMapping("/traces/{traceId}/explain") 2public ResponseEntity<?> explain(@PathVariable String traceId) { 3 try { 4 Map<String, Object> body = explainService.explain(traceId); 5 if (body == null) { 6 return ResponseEntity.notFound().build(); 7 } 8 return ResponseEntity.ok(body); 9 } catch (Exception e) { 10 return ResponseEntity.ok(InsightAiExplainSchema.buildResponse( 11 "trace", true, "内部错误,请稍后重试或复制 Context", ...)); 12 } 13} 14
前端认的是 degraded 和 summary,不是状态码。
模型超时、鉴权失败,页面仍在,提示去改设置或复制 Context。
监测主流程(拓扑、链路、告警推送)不跟这次解释绑死。

模型回了字,也不等于有结论
callChatCompletions 只保证拿到 assistant 文本,非 2xx 直接抛;content 为空时再看 reasoning_content,能抽出带 summary 的 JSON 才用,否则仍抛——推理模型经常把草稿写在思考里,正文是空的。
拿到原文之后走 completeExplain:
1Map<String, Object> parsed = InsightAiExplainSchema.parseStructured(raw, objectMapper); 2if (!InsightAiExplainSchema.isStructuredOk(parsed)) { 3 return InsightAiExplainSchema.buildResponse(kind, true, msg, ..., null, nav); 4} 5return InsightAiExplainSchema.buildResponse(kind, false, null, ..., parsed, nav); 6
parseStructured 本身也是一层降级:完整 JSON、````json 围栏、对象被截断但 ["summary":"..."](https://primers.xplanc.org/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.summary.md) 还在,都能尽量抽出一句给人看,抽不出,或看起来像 we need ... json这种思考草稿,就structured=false`,summary 换成「未能解析」类说明,不会把英文 CoT 糊到结论区。
这里用到的 JDK 写法可以扫一眼:InsightAiExplainSchema 里给 evidence 补跳转时,switch 用了箭头分支(Java 14):case "span" -> { ... },case "status", "exception" -> 还可以多标签共用,比一串 break 短。
告警附带解读是另一条契约:过不了门或配额是 skipped;调了模型但结构不对是 aiDegraded=true,Webhook 仍把指标发出去,只是 aiSummary 写成失败原因。
和详情页的 degraded 名字不同,意思一样:可选能力挂了,主通道继续。
降级看完,解释按钮才敢放在详情页
Insight 把 AI 解释做成 业务结果里的一个字段,而不是一次可能炸的远程调用。gateOrNull 挡住明显调不成的请求,parseStructured 挡住不能当结论的原文,Controller 再兜一层,状态码保持 200。
代价是调用方必须看 degraded,不能默认「200 就是好结论」,换来的是:没配 key、模型抽风、推理模型只思考,控制台都还在,Span 和告警也不跟这次解释一起挂掉。
上一篇讲的滑动窗口管的是钱和频率,本文讲的是失败形态,两道加在一起,可选 AI 才不至于把监测中心变成依赖大模型的系统。

最后:欢迎围观 Spring Insight
Spring Insight 是给 Spring Boot / Spring Cloud 用的轻量监测工具:业务服务加 spring-insight-agent-starter 上报,旁边跑一个 insight-server,控制台就能看服务拓扑和链路详情。
仓库在这:
跪求 Star,遇到问题直接开 Issue。
参考文档
《如何让 AI 解释失败也不拖垮控制台》 是转载文章,点击查看原文。
