如何让 AI 解释失败也不拖垮控制台

作者:苏渡苇日期:2026/10/17

作者:苏渡苇

项目地址: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,控制台就能看服务拓扑和链路详情。

仓库在这:

🔗 GitHub:https://github.com/iweidujiang/spring-insight

跪求 Star,遇到问题直接开 Issue。


参考文档


《如何让 AI 解释失败也不拖垮控制台》 是转载文章,点击查看原文。


相关推荐


量化回测为什么不能随便选前复权?从收益率计算到成交价格的三个误区
高频因子挖掘机2026/10/14

一句话结论:前复权适合许多基于历史价格变化的研究,但回测必须区分价格序列、投资收益和实际成交价格。复权数据选错会扭曲收益率计算,而不恰当使用前复权数据也可能引入历史时点不可获得的信息。 摘要 股票回测中,前复权数据经常被用于计算历史收益率、构建趋势指标和分析策略表现。但前复权价格并不天然等于真实投资收益,也不代表历史成交价格。本文从收益率定义、公司行为和回测时间轴三个方面,解释前复权的适用范围,比较前复权、后复权与不复权数据的使用场景,并介绍如何使用 QuantDash 获取前复权日 K 线,


Qt 文件操作详解:从基础类到读写实战
时间的拾荒人2026/10/5

📑 目录 🚀 1. 引言📁 2. 输入输出设备类✏️ 3. 文件读写类📖 4. 示例1:读取文件内容📝 5. 示例2:写文件📂 6. 文件和目录信息类☁️ 7. 总结🌲 8. 经典面试题 🚀 1. 引言 文件操作是应用程序必不可少的部分。Qt 作为一个通用开发库,提供了跨平台的文件操作能力。Qt 提供了很多关于文件的类,通过这些类能够对文件系统进行操作,如文件读写、文件信息获取、文件复制或重命名等。本文将系统介绍 Qt 中文件操作相关的核心类、继承关系以及实际应用示例。


CTF题目《UnserializeThree》(BUUCTF Web 困难 反序列化)
Hum8le2026/9/27

DASCTF 上传题(Hack Me)—— phar 反序列化 getshell 详细题解 面向零基础读者的一步步解析。每一步都会先说明「看到什么」,再说明「为什么这样做」,最后给出「具体怎么做」。 〇、先看结论(TL;DR) 考点:文件上传 + phar:// 反序列化 触发 __destruct,配合 eval 执行任意命令。绕过点:preg_match 只过滤了换行符 \n,但 PHP 的 # 注释遇到回车符 \r(0x0D) 也会结束,于是用 \r 就能「逃出注释」执行代码。关键坑


改了工作流引擎的流程定义,在跑的审批单有的跟着变、有的不变
mldong2026/9/21

做过工作流引擎的,都遇到过这么一个瞬间: 周一把审批流程从"两级审批"改成"三级审批",发布了。周二早上,业务同学问:昨天那 20 张还在审批中的单子,现在走两级还是三级? 如果你的引擎回答不了这个问题,或者回答得很随意——那多半是设计时就没想过"定义"和"正在用这份定义跑着的实例"是两回事。 这篇文章做的事,就是把这个问题在 jeeflow 里拆到底:一条在跑的审批单,它到底"记着"流程定义的什么;改了定义之后,下一次它走到引擎时,引擎读到的到底是新版还是旧版。拆完你会发现一个反直觉的结论——


Python 进阶:海象运算符与模式匹配,让你的代码更优雅!
90后晨仔2026/9/13

摘要:Python 3.8 引入的海象运算符 := 和 3.10 引入的模式匹配 match-case,是近年来 Python 语法层面最重要的两次革新。本文将从实战角度出发,详解这两个特性的核心用法、最佳实践及避坑指南,助你写出更简洁、更具表现力的 Pythonic 代码。 💡 前言 作为一名 Python 开发者,你是否经历过以下场景: 为了在 if 判断后复用某个计算结果,不得不提前写一行赋值语句; 面对复杂的嵌套数据结构,写了一长串 if-elif-else 来判断类型和解包数据,


NestJS 12升级踩坑:从Webpack到Rspack,我折腾了一整个周末
Flynt2026/9/5

说实话,看到NestJS 12的changelog时我是有点兴奋的。 8月27号发布,ESM-first、Rspack替代Webpack、Standard Schema验证、@nestjs/observe原生可观测性——每一条都戳在痛点上。特别是Rspack替代Webpack那条,我心想:终于不用等turbopack慢吞吞地编译了。 然后我花了整个周末才把项目跑起来。 先说下项目情况:一个中等体量的B端后台系统,NestJS 11.2.0 + Webpack monorepo架构,用了NATS消


别把豆包当聊天用了,现在的豆包和以前不一样了
程序员晓凡2026/8/28

大家好,我是晓凡。 豆包算是全民 AI 应用了,上班族、老人、小孩,手机里基本人手一个。我很早就给爸妈装上了,他们用得特别顺手,用他们的话说,豆包正好用,什么都懂。以前手机字体怎么调大、照片怎么发到家庭群、体检报告上的箭头是什么意思,这些事他们都要打电话来问我,现在直接跟豆包语音聊,问完自己就能搞定。 不过最近我才发现,豆包又悄悄更新了一大波东西:能操作本地电脑、使用浏览器,支持调用 Skills 技能和定时任务,内置了 Office 办公套件,还支持专业的图片视频设计。 不知道你是不是和我一样


Android 架构进阶:为什么项目越大,越需要把对象创建权拿走
潜龙勿用之化骨龙2026/8/20

刚开始写 Android 项目的时候,我其实不太理解 DI 有什么必要。 一个对象而已: val repository = UserRepositoryImpl() 直接创建不就完了吗? 如果只是一个小项目,确实没什么问题。 甚至我觉得,这时候为了 Hilt、Koin 再引入一套依赖注入体系,反而有点重。 真正让我改变想法的,是项目开始变大以后。 你会发现,项目变复杂以后,麻烦来了: 到处都是创建对象。 一、项目小的时候,直接创建对象没有问题 比如: class UserRepository


Java对象头Mark Word状态与锁膨胀过程剖析
wuminyu2026/8/6

Java对象头Mark Word状态与锁膨胀过程剖析 前言对象头Mark Word状态与锁膨胀过程剖析1. 64位 HotSpot JVM 下 Mark Word 内存布局64位 JVM Mark Word 位结构图表C++ 头文件位常量定义 (`markOop.hpp`) 2. 状态机迁移全景与锁演进路线3. 偏向锁(Biased Locking)的加锁与撤销源码解析3.1 偏向锁的快速进入(Fast Path)3.2 偏向锁的撤销(Revocation) 4. 轻量级锁(Lig


2026 哪个远程控制软件好用?国内海外 6 款主流远程软件深度测评(附评分表与选型建议)
禁止默2026/7/28

2026 年了,远程控制软件早就不是"偶尔帮老妈修电脑"的低频工具了——居家连公司工位改方案、出差路上用平板回邮件、周末秒回 OA、被控端跑训练任务、远程串流玩 3A,这些场景已经把远程软件变成了天天开的生产力底座。 但"哪个好用"这个问题在 2026 年变得更难回答了,原因是市场出现了三条暗线: 国内三巨头分层明显:UU 远程靠网易的网络底子杀进来,把 4K/144fps、端口映射、远程终端全做成了免费;ToDesk 免费版开始卡时长;向日葵免费版广告越塞越多,并且开始排队收费。

首页编辑器站点地图

本站内容在 CC BY-SA 4.0 协议下发布

Copyright © 2026 聚合阅读