覆盖 ChatModel/AiServices 装配、@Tool 与 MCP、进程内 Embedding、结构化输出与版本升级等 LangChain4j 集成中的高频坑。
版本升级、NoSuchMethodError/NoClassDefFoundError、BOM、starter 兼容
LangChain4j 1.x 将 ChatLanguageModel 改名为 ChatModel，编译报找不到符号，版本不齐则会运行期崩溃。
LangChain4j core 升级后类被删，上层集成仍引用旧类，运行期报 NoClassDefFoundError。
LangChain4j 1.x 编译基线是 JDK 17，丢进 Java 8 运行会在加载类时抛 UnsupportedClassVersionError。
Spring Boot 4 下 LangChain4j starter 自动装配失败，报 Failed to generate bean name。
provider 配置、api-key、baseUrl、模型名
LangChain4j Vertex Gemini 多轮工具调用第二轮抛 400 missing thought_signature，适配层未回传签名。
Ollama 模型名写错时 LangChain4j 抛 NPE，真实原因是 /api/chat 返回 404、响应体为空。
Spring Boot 4 下 LangChain4j starter 自动装配失败，报 Failed to generate bean name。
@Tool、参数映射、MCP、stdio
LangChain4j Vertex Gemini 多轮工具调用第二轮抛 400 missing thought_signature，适配层未回传签名。
MCP stdio 报 JsonParseException 常是子进程没起来：命令拼成单串、路径带空格，stderr 中文报错被当 JSON 解析。
Java 默认不保留参数名，LangChain4j 的 @Tool 映射不到实参：或静默为 null，或抛 MissingArgumentException。
进程内 embedding、DJL/ONNX、原生库
StreamingChatModel、TokenStream、Flux
超时、429、连接、代理
