覆盖 ChatClient 配置、Tool Calling、RAG 向量库、流式输出等 Spring AI 集成中的高频坑。
ChatModel 注入不到，常见是没引入厂商 starter、api-key 写错、模型名拼错、或版本没走 BOM 管理。本文讲清依赖、配置、自动配置三层排查路径。
向量维度是 pgvector 的硬约束，建表后不能 ALTER。报维度冲突，多半是 embedding 模型没固定、或者换了模型，而旧表还留着。改了 dimensions 配置不生效，得 DROP 表重建。
用 .stream() 得到 Flux，再通过 SseEmitter（MVC）或直接返回 Flux（WebFlux）推给前端。坑点：某些版本的 OpenAI stream 被内部 collectList 缓冲、SseEmitter 不设超时会挂死、produces 配置漏了连接提前关闭。
工具调用不触发，常是这些原因：defaultOptions 用了 DefaultChatOptions 而不是 ToolCallingChatOptions、.tools() 的重载只吃 MethodTool 却吞掉 FunctionToolCallback、或者中途换了 options 实例把 callback 丢了。
Spring AI 迭代极快，pre-1.0 到 1.0 有一大批 breaking change：旧的 ChatClient 功能挪进 ChatModel、EmbeddingClient 改成 EmbeddingModel、starter 命名标准化、配置属性去掉了 .options。升级前先读 upgrade notes。