覆盖 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 连接重置；配代理、调超时或走流式可解。
图片/音频/文档解析
