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连接到模型工具调用的完整排查链路。
MCP Server新增工具后客户端一直看不到？ttlMs、cacheScope与listChanged缓存排查
MCP 2026-07-28为工具、资源和Prompt列表增加了缓存语义。客户端可以根据`ttlMs`缓存`tools/list`结果，并根据`cacheScope`决定是否允许共享。新机制能够减少频繁列表请求，但也带来新问题：服务端新增工具后客户端长期不可见、权限撤销后旧工具仍显示、不同租户获得错误工具列表。本文给出缓存键、TTL、`listChanged`通知、权限隔离和灰度更新的完整排查方法
Spring AI工具明明注册了，模型为什么不调用？描述、Schema与Advisor完整排查
Spring AI项目中经常出现：工具已经通过`@Tool`或`ToolCallback`注册，ChatClient调用也没有报错，但模型始终直接回答、调用错误工具，或者生成根本不存在的参数。根因通常不在工具执行代码，而在工具是否绑定到实际ChatClient、描述是否清晰、输入Schema是否准确、模型是否支持Tool Calling、Prompt是否限制工具使用，以及`ToolCallingA
Spring AI工具已经调用成功，为什么最终回答仍为空？返回值、循环与上下文完整排查
有些Spring AI项目可以在日志中看到工具已经被调用，数据库查询或HTTP请求也成功执行，但客户端最终收到空字符串、模型重复调用同一工具，或者回答完全没有使用工具结果。这类问题与“模型没有选择工具”不同，通常发生在工具返回值序列化、异常处理、Tool Calling循环、流式事件拼接、结果过长、消息持久化和终止条件等环节。本文给出从工具执行结果到最终Assistant回答的完整排查路径。
Spring AI 2.0 Chat Memory报conversationId不能为空？升级后的完整排查方法
Spring AI 2.0升级后，使用`MessageChatMemoryAdvisor`或`VectorStoreChatMemoryAdvisor`的项目可能直接抛出`conversationId`不能为空、缺少`ChatMemory.CONVERSATION_ID`或历史对话突然失效。原因是新版本要求每次经过内置Memory Advisor的调用都显式提供会话ID，旧版默认会话ID和Buil
多租户Chat Memory为什么会串话？会话ID、缓存与数据库隔离完整排查
企业AI应用中最严重的问题之一，是用户A看到用户B的对话内容，或租户A的上下文进入租户B的回答。根因通常不是模型“自己记住了别人”，而是会话ID重复、默认Memory、缓存键缺少租户字段、数据库查询遗漏条件、异步上下文丢失或向量长期记忆过滤不完整。本文提供从入口认证、conversationId、ChatMemoryRepository、Redis缓存、向量库到日志脱敏的完整排查路径。
Spring AI流式接口经过Nginx后不再逐字输出？缓冲、压缩与超时完整排查
Spring AI在本地通过`Flux<String>`和SSE可以正常逐段返回，但部署到Nginx、网关或CDN后，经常变成等待几十秒再一次性输出。根因通常不是模型没有流式返回，而是代理缓冲、响应压缩、错误的Content-Type、连接超时或业务代码中出现阻塞操作。本文给出从Spring WebFlux、SSE响应头、Nginx配置、网关链路到前端读取方式的完整排查流程。
用户取消AI流式输出后，模型为什么还在继续生成？前端Abort、Reactor取消与上游计费排查
前端点击“停止生成”后，页面虽然不再显示内容，但后台日志、Token统计或模型控制台仍显示请求继续执行。这是因为停止前端渲染、关闭HTTP连接、取消Reactor订阅和通知模型Provider停止生成是四个不同层次。本文解释取消信号如何沿前端、网关、Spring WebFlux和模型SDK传播，并给出任务状态、`doOnCancel`、幂等关闭、超时和计费监控的完整实现思路。
RAG文档更新后仍然检索到旧内容？增量索引、版本字段与缓存完整排查
# RAG文档更新后仍然检索到旧内容？增量索引、版本字段与缓存完整排查 ## 文章摘要 企业RAG知识库更新制度、产品资料或合同后，经常出现“后台已经上传新版本，问答却仍引用旧内容”的问题。根因可能来自旧向量没有删除、文档ID变化、增量任务失败、检索过滤缺失、缓存未失效，或者新旧版本同时处于有效状态。本文提供从源文件、解析结果、Chunk、向量库、缓存到生成上下文的完整排查路径，并给出安全的版