覆蓋 ChatClient 設定、Tool Calling、RAG 向量庫、流式輸出等 Spring AI 集成中的高頻坑。
provider 設定、api-key、endpoint、模型名
對接 Azure OpenAI 的 404：不是 endpoint 錯，而是把底層模型名當 deployment name 傳給了 Azure。
問題大多不在 Java 程式碼，而在本地 Ollama 根本沒拉到對應模型，或模型名/tag 寫錯。先確認 ollama list 再處理。
用 openai starter 時一啟動就報錯，手動 new OpenAiChatModel 傳 key 也攔不住：自動設定啟動即校驗設定項。
調用 OpenAI 拋 404 model_not_found，多是模型設定 key 寫錯被靜默忽略、回退預設 gpt-4o，或賬戶沒有該模型權限。
ChatClient/EmbeddingModel 裝配、NoSuchBean、版本升級
Spring AI 1.1.6 / 2.0 起 PromptChatMemoryAdvisor 被移除，聊天記憶 advisor 必須顯式傳會話 ID。
報 NoSuchBeanDefinitionException，缺的是 VertexAiEmbeddingConnectionDetails 自動設定導入缺失。
OpenAI starter 與 WebFlux 一起啟動就報缺少 RestClient.Builder：早期自動設定寫死注入它。
ChatModel 注入不到，常見是沒引廠商 starter、api-key 寫錯、模型名拼錯，或版本沒走 BOM 管理。
Spring AI 1.0 前後破壞性變更密集：ChatClient 併入 ChatModel、EmbeddingClient 改名、設定屬性重排。
ChatClient、prompt、結構化輸出
第二輪起必現 400：MessageChatMemoryAdvisor 把歷史 prepend 到 messages，SystemMessage 被擠到第二位。
多輪問答加 RAG 突然報 400，重啟又正常。根因是 MessageWindowChatMemory 只按條數截斷、完全不管 token。
用 Map 接結構化輸出時泛型被擦除，字段類型全看模型；模型返回陣列而非字符串就拋 MismatchedInputException。
本地 H2 正常，換 MySQL 或 PostgreSQL 就報表不存在。JdbcChatMemoryRepository 預設只對嵌入式庫自動建表。
模型偶爾把 JSON 包在 Markdown 圍欄裡返回，BeanOutputConverter 直接拋 RuntimeException。
Tool Calling、MCP、SSE 端點
用 stdio 接 MCP server 時子進程報 npx not found。根因是 JVM 進程 PATH 不等於交互式 shell 的 PATH。
MCP stdio 服務端往 stdout 打日誌，客戶端就報 JSON 解析失敗。stdout 是 JSON-RPC 專用通道，日誌必須走 stderr。
MCP 客戶端報 404，多半不是服務端掛了，而是客戶端還按舊的 SSE 端點連。Spring AI 1.1.8 已提供 Streamable HTTP 客戶端，端點預設 /mcp。
工具調用不觸發，多是 defaultOptions 類型不對，或 .tools() 重載吞掉 FunctionToolCallback。
VectorStore、PGvector、embedding、召回
similarityThreshold 必須是 0～1 的小數；越界會被 SearchRequest.Builder 攔下，閾值過高則召回為空。
啟動建表就報錯，問題不在實體或 SQL，而在 PostgreSQL 沒啟用 pgvector 擴展。先裝擴展、再建表、再初始化 schema。
向量維度是 pgvector 的硬約束，建表後不能 ALTER。報維度衝突，多半是 embedding 模型沒固定、舊錶還留著，改設定也無效。
SSE、WebFlux、流式輸出
超時、429、代理、連接重置
報 Connection refused 是連不上 11434 端口，不是模型不存在。根因：服務沒起、只綁 127.0.0.1 或容器 localhost。
429 不全是限流，error.code 還可能是餘額或限額耗盡；Spring AI 預設對 4xx 不重試，直接拋例外。
國內直連 OpenAI 常撞 SocketTimeoutException 讀超時與 Connection reset 連接重置；配代理、調超時或走流式可解。
圖片/音頻/文檔解析
