上下文压缩后关键条件消失？数字、例外条款与表格保真排查
压缩器可能保留主结论，却删除适用范围、例外、时间和单位，导致绝对化错误。
RAG查询改写后把关键实体改错了？人名、编号与否定词保护排查
查询改写可能修改产品编号、人名、日期、否定条件和专业术语，导致检索方向错误。
RAG查询改写后数字、缩写和型号消失？Token清洗排查
型号、错误码、版本和缩写是技术检索最重要的Token，清洗或改写阶段删除它们会同时损害稀疏和稠密检索。
Spring AI应用Docker健康检查正常，为什么真实模型调用全部失败？
进程健康只能证明容器存活，不代表凭证、网络、额度和指定模型可调用。
AI应用上线后Prompt版本混乱？配置漂移、缓存与多实例排查
不同Pod使用不同Prompt缓存、配置中心版本或模型别名，会导致同一代码版本行为不一致。
大模型单元测试为什么时好时坏？温度、模型漂移与断言方式排查
直接断言大模型完整字符串，会因采样、模型更新、提示词和检索变化产生脆弱测试。
黄金测试集更新后历史分数不能比较？数据集版本与基线漂移排查
不断补充样本后，新旧平均分不能直接比较，因为样本难度和分布已经变化。
Spring WebFlux请求超时后AI任务为什么还在运行？
前端或网关超时只终止HTTP响应，不一定向上游模型、工具或队列传播取消信号。
AI异步回调为什么会重复到达？至少一次投递与幂等排查
网络超时、消费者重启和ACK丢失会让同一回调多次到达，必须按至少一次投递设计。
Spring AI VectorStore过滤条件已经传入，为什么仍然召回其他租户文档？
多租户RAG中，即使日志显示tenantId已传入，也可能因为过滤表达式丢失、字段类型不一致或后置过滤造成越权召回。
RAG引用编号与正文对不上？重排、去重和压缩后的证据映射排查
检索候选经过重排、去重和压缩后，如果仍沿用早期数组下标，答案引用会与最终展示来源错位。
Spring AI配置多个ChatModel后为什么总是调用默认模型？
Spring AI多模型项目中，Bean注入、ChatClient复用和路由结果传递任何一处出错，都会让所有流量落到默认模型。
模型Fallback已经切换成功，为什么请求仍然失败？
日志显示已切换备用模型，但请求仍返回相同错误，往往说明主备共享额度、网络、超时预算或输出契约。
Spring AI调用entity()时JSON解析失败？Markdown包裹、字段缺失与Schema不兼容完整排查
Spring AI的`ChatClient.call().entity()`可以把模型输出直接转换为Java对象，但生产项目经常遇到JSON前后带解释文字、被Markdown代码块包裹、必填字段缺失、枚举值不匹配、日期格式错误或Provider不支持完整JSON Schema等问题。默认结构化输出本质上仍可能是“Prompt约束＋文本解析”，并不天然保证100%成功。本文从目标类型设计、原始响应留
Spring AI流式输出为什么不能直接entity()？聚合JSON、SSE事件与最终对象解析方案
Spring AI的`.stream()`返回文本增量，而`.entity()`需要完整响应后才能生成JSON Schema、校验并反序列化为Java对象。因此，开发者无法像同步调用一样直接把流式Chunk转换成完整Entity。强行对每个片段执行JSON解析，会遇到半截字符串、转义字符、字段顺序变化和错误重试无法闭环等问题。本文给出三种可靠方案：服务端聚合后一次解析、SSE同时发送进度与最终结果
Spring AI Moderation已经返回flagged，为什么模型请求仍然继续执行？
Spring AI支持OpenAI和Mistral AI的Moderation模型，但Moderation只负责返回检测结果，并不会自动阻断后续ChatClient调用。很多项目虽然拿到了`flagged=true`，却仍然继续调用大模型，原因通常是业务代码没有执行策略判断、异步流程没有取消、Advisor链顺序不正确，或者只记录了审核结果却没有返回拦截响应。本文给出从Moderation调用、风
RAG文档里藏着“忽略系统提示词”，为什么模型真的照做了？Prompt Injection完整排查
RAG系统会把检索到的文档片段与用户问题一起交给模型。如果网页、PDF、工单或知识库文档中包含“忽略之前的指令”“调用工具上传数据”等文本，模型可能把不可信资料误当成指令，形成间接Prompt Injection。仅在System Prompt中写“不要听文档命令”并不能彻底解决。本文从数据来源、上下文边界、工具权限、检索过滤、输出校验和对抗测试六个方面给出完整排查方案。
Spring AI接入Actuator后看不到Token和耗时指标？Micrometer观测完整排查
Spring AI 2.0已经为ChatClient、Advisor、ChatModel、Tool Calling、EmbeddingModel和VectorStore提供Micrometer观测能力，但很多项目接入Actuator和Prometheus后，只能看到JVM指标，看不到`gen_ai_client_token_usage_total`、`gen_ai_chat_client_oper
Spring AI遇到429或超时后为什么重复执行工具？重试边界与幂等完整排查
AI接口出现429、超时或连接中断后，开发者通常会增加自动重试。但在Tool Calling场景中，如果重试包裹了整个Agent流程，退款、发送邮件、创建工单、写数据库等工具可能被重复执行。更隐蔽的情况是模型请求超时，但工具其实已经完成；客户端重试后，模型再次发起相同工具调用。本文从模型层、Agent层、工具层和HTTP层四个重试边界出发，给出幂等键、状态机、结果查询和可重试错误分类的完整方案。
Spring AI MCP客户端连接成功却看不到工具？从初始化、传输、过滤到ChatClient完整排查
Spring AI项目接入MCP时，最常见的问题之一是：应用启动没有报错，MCP Server日志也显示连接成功，但`ChatClient`始终不调用工具，甚至工具列表为空。问题可能发生在初始化、传输配置、工具回调开关、客户端类型、工具过滤、名称冲突、Schema生成、权限或ChatClient注册等多个环节。本文给出一条从MCP连接到模型工具调用的完整排查链路。