这次我们来看一个 Java 开发者如何快速接入 AI 能力的实战选型方案。如果你是一名 Java 后端工程师面对层出不穷的 AI 框架和概念感到无从下手或者想在自己的 Spring Boot 项目中集成智能对话、知识库问答RAG或构建 AI Agent那么这篇文章就是为你准备的。核心问题很直接在 Java 技术栈里有哪些成熟、稳定且能快速上手的 AI 集成方案答案是围绕 Spring AI、LangChain4j、阿里云灵积平台Spring AI Alibaba以及 RAG 技术栈展开的组合拳。这些方案能让你在不深入 Python 生态的情况下用熟悉的 Java 和 Spring 风格调用大模型、管理对话记忆、处理文档知识库并构建具备逻辑推理能力的智能体Agent。本文不会空谈概念而是聚焦于实战。我们将逐一拆解每个组件的核心能力、硬件/环境门槛、启动方式并通过一个“智能航空客服”的模拟场景串联起从环境搭建、接口调用、知识库构建到 Agent 编排的完整流程。读完你就能知道用 Java 搞 AI 应用到底行不行、怎么用、以及最先该验证什么。1. 核心能力速览下表快速对比了当前 Java 生态中主流的 AI 集成方案帮助你快速建立认知框架组件/技术核心定位与功能启动/集成方式硬件门槛是否支持批量/异步关键接口能力Spring AISpring 官方 AI 集成框架提供统一的 API 抽象层简化对不同模型供应商OpenAI, Azure, Ollama等的调用。通过 Spring Boot Starter 依赖引入配置application.yml即可。无特殊要求依赖后端服务资源和模型 API 网络。支持依托 Spring 的异步编程模型。ChatClient,PromptTemplate,EmbeddingClient等。Spring AI Alibaba阿里云对 Spring AI 的扩展实现主要对接阿里云灵积平台上的通义千问等模型。同 Spring AI需额外引入阿里云 starter 并配置阿里云 AK/SK。无特殊要求依赖阿里云 API 调用。支持。与 Spring AI 接口兼容专有模型参数。LangChain4jJava 版的 LangChain专注于构建基于大模型的应用程序链Chain、智能体Agent和记忆Memory。作为库引入通过 Builder 模式编程式构建链和 Agent。无特殊要求可本地或远程调用模型。支持链式异步执行。AiServices,ConversationalRetrievalChain,Tool等。RAG (检索增强生成)技术范式非具体库。用于结合向量数据库与 LLM实现基于私有知识的精准问答。需组合文档加载器 文本分割器 嵌入模型 向量库如 Chroma, Redis。向量库内存/磁盘开销嵌入模型计算资源可调用云 API。支持批量文档入库、批量检索。文档索引、语义检索、上下文组装。AI Agent应用架构非具体库。让 AI 具备使用工具、规划步骤、持续学习的能力。基于 LangChain4j 的Agent或 Spring AI 的Function Calling构建。依赖底层模型和工具链的性能。支持多轮复杂任务编排。工具调用Tool、规划Planner、记忆Memory。总结一下对于 Java 开发者Spring AI是你的“模型调用统一网关”LangChain4j是你的“应用逻辑编排引擎”RAG是你的“知识大脑”而AI Agent是最终呈现的“智能体”。它们可以组合使用并非互斥。2. 适用场景与使用边界适合谁能解决什么问题Java/Spring Boot 后端团队希望以最小学习成本将大模型能力集成到现有微服务中。企业级应用开发需要稳定、可控、易于监控和集成的 AI 能力例如智能客服、内部知识助手、报告生成、数据洞察等。快速原型验证利用 Spring Boot 的快速启动特性在几天内搭建一个具备对话、知识库查询能力的 Demo。规避 Python 运维复杂性在纯 Java 技术栈中完成 AI 功能开发避免引入 Python 环境带来的部署和运维复杂度。不适合什么场景模型训练与微调这些框架主要用于推理和应用开发不涉及底层模型的训练。超大规模、低延迟的纯向量计算虽然 RAG 涉及向量检索但对于每秒数万次的检索请求可能需要专门优化的 C/Rust 向量库Java 生态的客户端可能成为瓶颈。完全离线的本地模型部署虽然 Spring AI 支持 Ollama本地模型但 LangChain4j 等框架的核心价值在于编排如果模型完全离线且计算密集整体架构需要额外考虑。合规与安全边界数据隐私调用云端模型 API如 OpenAI, 通义千问时你的提示词Prompt和对话数据会发送到第三方服务器。涉及敏感数据时务必使用符合数据驻留要求的云服务或部署私有化模型。内容安全集成的大模型本身具备内容过滤机制但在构建 RAG 知识库时需确保入库文档内容合法合规。Agent 所调用的工具如数据库查询、API 调用也需做好权限控制。版权与授权RAG 知识库的文档来源必须拥有合法版权或使用授权。Agent 生成的内容若用于商业发布需注意是否侵犯第三方权益。3. 环境准备与前置条件在开始编码前请确保你的开发环境满足以下基础要求。这是一个通用清单具体版本可能随项目发展而变。操作系统Windows 10/11, macOS, 或 Linux (推荐 Ubuntu 20.04)。无特殊限制。Java 开发套件JDK: 版本17 或 21(LTS 版本)。Spring AI 对 Java 版本有要求。构建工具: Maven (3.6) 或 Gradle (7.x)。本文示例使用 Maven。IDE: IntelliJ IDEA (推荐), Eclipse 或 VS Code with Java 插件。Spring Boot: 版本3.2.0或更高。Spring AI 紧密集成 Spring Boot。模型访问权限方案A (云端API)准备一个可用的模型 API Key 和 Endpoint。OpenAI: 准备OPENAI_API_KEY。阿里云通义千问准备阿里云账号的AccessKey ID和AccessKey Secret。其他Azure OpenAI, Ollama (本地), 百度千帆等根据 Spring AI 支持列表选择。方案B (本地模型)如需本地推理需部署如Ollama服务并拉取所需模型如qwen2.5:7b这需要一定的 GPU/CPU 和内存资源。向量数据库 (用于 RAG)选择一款并准备运行实例。轻量级/测试Chroma(内存模式)Redis(with Redis Stack)。生产级PgVector(PostgreSQL 扩展)Milvus,Weaviate。首次体验可跳过先用内存模拟。网络能稳定访问你选择的模型 API 服务地址。4. 项目初始化与依赖配置我们以一个名为smart-aviation-assistant的 Spring Boot 项目为例演示如何集成这些技术。4.1 创建 Spring Boot 项目使用 Spring Initializr 或 IDE 创建项目选择Project: MavenLanguage: JavaSpring Boot: 3.2.5 (示例)Dependencies:Spring Web,Lombok(可选简化代码)生成项目后打开pom.xml文件添加以下关键依赖。4.2 添加 Spring AI 及相关依赖我们将引入 Spring AI 的核心依赖、阿里云扩展以及 LangChain4j。?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd !-- ... 其他父项目、属性等配置 ... -- dependencies !-- Spring Boot 基础依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency !-- Spring AI 核心 - 统一AI模型调用 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId !-- 请查看官网使用最新版本 -- version0.8.1/version /dependency !-- Spring AI Alibaba - 阿里云通义千问 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-ai-spring-boot-starter/artifactId !-- 请查看官网使用最新版本 -- version1.0.0-M2/version /dependency !-- LangChain4j - AI应用编排与Agent -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.31.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version0.31.0/version /dependency !-- 向量数据库连接器 (以Redis为例) -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-store-embedding-redis/artifactId version0.31.0/version /dependency !-- 测试依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies !-- ... -- /project注意版本号可能更新请以 Spring AI Project 和 LangChain4j GitHub 官方文档为准。4.3 配置应用程序属性在src/main/resources/application.yml中配置模型连接信息。这里配置两个模型连接OpenAI 和 阿里云通义千问你可以根据实际情况启用其中一个。spring: application: name: smart-aviation-assistant # OpenAI 配置 (示例二选一) spring: ai: openai: api-key: ${OPENAI_API_KEY:your-openai-key-here} # 建议使用环境变量 chat: options: model: gpt-4o-mini # 或 gpt-3.5-turbo temperature: 0.7 # 阿里云通义千问配置 (示例二选一) # spring: # ai: # alibaba: # ai: # access-key-id: ${ALIBABA_ACCESS_KEY_ID:your-access-key-id} # access-key-secret: ${ALIBABA_ACCESS_KEY_SECRET:your-access-key-secret} # chat: # options: # model: qwen-max # 或 qwen-plus, qwen-turbo # endpoint: dashscope.aliyuncs.com # LangChain4j 配置 (可选用于更精细的控制) langchain4j: open-ai: chat-model: api-key: ${OPENAI_API_KEY:your-openai-key-here} model-name: gpt-4o-mini temperature: 0.7 timeout: 60s # Redis 配置 (用于RAG向量存储如果使用) # spring: # data: # redis: # host: localhost # port: 6379 # password: # database: 0关键点API Key 安全切勿将密钥硬编码在代码中。务必使用环境变量如OPENAI_API_KEY或配置中心管理。模型选择根据需求成本、性能、功能选择模型。gpt-4o-mini或qwen-turbo适合对话text-embedding-3-small或text-embedding-v3适合生成向量。配置冲突如果同时配置了 Spring AI 和 LangChain4j 的 OpenAI 连接注意它们可能相互影响。建议初期只使用一套。5. 核心功能测试与效果验证环境就绪后我们通过编写简单的测试类或 Controller来验证各个组件的核心功能是否工作正常。5.1 测试1Spring AI 基础对话创建一个ChatController注入 Spring AI 的ChatClient进行对话测试。import org.springframework.ai.chat.ChatClient; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import lombok.RequiredArgsConstructor; RestController RequiredArgsConstructor public class ChatController { private final ChatClient chatClient; // Spring AI 自动注入 GetMapping(/chat) public String chat(RequestParam(defaultValue 你好介绍一下你自己) String message) { // 构建Prompt Prompt prompt new Prompt(new UserMessage(message)); // 调用模型并获取响应内容 String response chatClient.call(prompt).getResult().getOutput().getContent(); return response; } }启动与测试启动 Spring Boot 应用 (SmartAviationAssistantApplication)。打开浏览器或使用curl测试curl http://localhost:8080/chat?messageJava和Python在AI开发上各有什么优势预期结果返回一段由 AI 生成的、关于两种语言优势的文本。验证成功能收到非空的、连贯的文本响应。常见失败401 UnauthorizedAPI Key 配置错误或无效。Connection timed out网络无法访问模型端点检查代理或防火墙设置。空响应或报错检查application.yml中模型名称是否正确依赖是否冲突。5.2 测试2Spring AI Alibaba 调用如果你配置了阿里云可以创建一个专门的 Service 或 Controller 来测试。Spring AI 的抽象层使得切换模型供应商非常方便。理论上只需更改配置ChatClient就会自动指向阿里云。但为了清晰我们演示如何显式使用AlibabaChatClient。import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatClient; import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatOptions; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import lombok.RequiredArgsConstructor; RestController RequiredArgsConstructor public class AlibabaChatController { // 注入专用于阿里云的 ChatClient private final DashScopeChatClient dashScopeChatClient; GetMapping(/chat/alibaba) public String chatWithQwen(RequestParam String message) { // 可以设置模型特有参数 DashScopeChatOptions options DashScopeChatOptions.builder() .withModel(qwen-max) // 指定模型 .withTemperature(0.8f) .build(); Prompt prompt new Prompt(new UserMessage(message), options); return dashScopeChatClient.call(prompt).getResult().getOutput().getContent(); } }测试方式同上访问/chat/alibaba端点。这验证了多云模型调用的能力。5.3 测试3LangChain4j 构建简单链与工具调用LangChain4j 的核心价值在于编排。我们测试其AiServices接口和简单的工具调用。首先定义一个工具接口模拟查询航班信息的工具。import dev.langchain4j.agent.tool.Tool; import org.springframework.stereotype.Component; Component // 注册为Spring Bean public class FlightTools { Tool(根据航班号查询航班实时状态例如 CA1234) public String getFlightStatus(String flightNumber) { // 这里模拟返回真实场景应调用外部API或查询数据库 return String.format(航班 %s 的状态为预计起飞时间 14:30登机口 45状态 正在登机。, flightNumber.toUpperCase()); } Tool(根据出发城市和到达城市查询今日可选的航班列表) public String searchFlights(String departureCity, String arrivalCity) { return String.format(从 %s 飞往 %s 的今日航班有CA1234 (10:00-12:30), MU5678 (15:00-17:45)。, departureCity, arrivalCity); } }然后使用AiServices创建一个智能服务它能自动理解用户意图并调用工具。import dev.langchain4j.service.SystemMessage; import dev.langchain4j.service.UserMessage; import dev.langchain4j.service.V; import dev.langchain4j.service.spring.AiService; AiService // LangChain4j 注解自动代理 public interface AviationAssistant { SystemMessage(你是一个专业的航空客服助手可以查询航班信息和状态。请根据用户问题必要时调用工具获取信息然后给出友好、准确的回答。) String chat(String userMessage); }创建一个配置类将工具和模型绑定到AiService。import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.service.AiServices; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class LangChain4jConfig { Bean public AviationAssistant aviationAssistant(ChatLanguageModel chatLanguageModel, FlightTools flightTools) { // 使用 AiServices.builder() 将模型、工具和接口绑定 return AiServices.builder(AviationAssistant.class) .chatLanguageModel(chatLanguageModel) .tools(flightTools) // 注入工具 .build(); } }最后在 Controller 中调用。RestController RequiredArgsConstructor public class AgentController { private final AviationAssistant aviationAssistant; // 注入我们定义的智能体 GetMapping(/agent/chat) public String agentChat(RequestParam String question) { return aviationAssistant.chat(question); } }测试与验证启动应用。访问http://localhost:8080/agent/chat?question帮我查一下CA1234航班的状态。预期结果AI 会识别出需要调用getFlightStatus工具并整合工具返回的结果生成类似“好的已为您查询。航班CA1234的状态为预计起飞时间14:30登机口45状态正在登机。”的回答。验证成功回答中包含了工具返回的模拟数据且回答是连贯的。核心价值你无需手动解析用户意图和调用工具LangChain4j 的 Agent 机制自动完成了“思考-行动-观察”的循环。这是构建复杂 AI 应用的关键。6. RAG 知识库构建与检索增强接下来我们实现 RAG 的核心流程将航空公司的政策文档如行李规定、退改签规则存入向量数据库并让 AI 根据这些知识回答问题。6.1 文档加载与处理我们使用 LangChain4j 的文档加载器和分割器。import dev.langchain4j.data.document.Document; import dev.langchain4j.data.document.loader.FileSystemDocumentLoader; import dev.langchain4j.data.document.splitter.DocumentSplitters; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.store.embedding.EmbeddingStoreIngestor; import org.springframework.ai.embedding.EmbeddingModel; import org.springframework.core.io.Resource; import org.springframework.core.io.ResourceLoader; import org.springframework.stereotype.Service; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import java.nio.file.Paths; import java.util.List; Slf4j Service RequiredArgsConstructor public class KnowledgeBaseService { private final EmbeddingModel embeddingModel; // Spring AI 的嵌入模型 private final EmbeddingStoreTextSegment embeddingStore; // 向量存储需配置Bean private final ResourceLoader resourceLoader; /** * 从文件系统加载文档并存入向量库 */ public void ingestDocument(String filePath) { try { // 1. 加载文档 Document document FileSystemDocumentLoader.loadDocument(Paths.get(filePath)); // 2. 分割文档按段落或固定大小 ListTextSegment segments DocumentSplitters.recursive(300, 0).split(document); // 3. 创建摄取器并执行将文本转换为向量并存储 EmbeddingStoreIngestor ingestor EmbeddingStoreIngestor.builder() .embeddingModel(embeddingModel) .embeddingStore(embeddingStore) .build(); ingestor.ingest(segments); log.info(文档 {} 已成功摄入知识库分割为 {} 个片段。, filePath, segments.size()); } catch (Exception e) { log.error(摄入文档失败: {}, filePath, e); throw new RuntimeException(文档摄入失败, e); } } }6.2 配置向量存储以内存存储为例便于测试生产环境请换成 Redis、PgVector 等。import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; Configuration public class EmbeddingStoreConfig { Bean Profile(test) // 测试环境使用内存存储 public EmbeddingStoreTextSegment inMemoryEmbeddingStore() { return new InMemoryEmbeddingStore(); } // 生产环境配置 RedisEmbeddingStore // Bean // Profile(prod) // public EmbeddingStoreTextSegment redisEmbeddingStore(RedisConnectionFactory connectionFactory) { // return RedisEmbeddingStore.builder() // .connectionFactory(connectionFactory) // .keyPrefix(aviation:emb:) // .build(); // } }6.3 实现 RAG 问答链结合检索到的上下文进行回答。import dev.langchain4j.chain.ConversationalRetrievalChain; import dev.langchain4j.memory.ChatMemory; import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.retriever.EmbeddingStoreRetriever; import org.springframework.stereotype.Service; import lombok.RequiredArgsConstructor; Service RequiredArgsConstructor public class RagQaService { private final ChatLanguageModel chatLanguageModel; private final EmbeddingStoreRetriever retriever; // 需要基于 embeddingStore 创建 public String answerQuestion(String question) { // 创建对话记忆保留最近几轮对话 ChatMemory chatMemory MessageWindowChatMemory.withMaxMessages(10); // 构建检索增强的对话链 ConversationalRetrievalChain chain ConversationalRetrievalChain.builder() .chatLanguageModel(chatLanguageModel) .retriever(retriever) // 检索器从向量库找相关片段 .chatMemory(chatMemory) .build(); return chain.execute(question); } }6.4 测试 RAG 流程准备文档创建一个policy.txt文件内容如“本公司经济舱旅客可免费托运一件不超过23公斤的行李。手提行李尺寸不得超过204055厘米。”调用摄入接口编写一个初始化 Bean 或 API 端点调用knowledgeBaseService.ingestDocument(path/to/policy.txt)。提问测试调用ragQaService.answerQuestion(“经济舱托运行李限额是多少”)。预期结果AI 的回答应基于policy.txt中的内容而不是其通用知识。例如“根据规定经济舱旅客可免费托运一件不超过23公斤的行李。”验证成功回答准确引用了文档中的具体数字和条款。你可以尝试问文档中不存在的问题观察回答的区别。7. 整合构建智能航空客服 Agent现在我们将以上所有能力整合到一个更强大的 Agent 中。这个 Agent 能处理一般对话。查询实时航班信息通过工具。回答公司政策问题通过 RAG 检索知识库。根据上下文决定使用哪种能力。这可以通过 LangChain4j 更高级的Agent来实现但为了清晰我们设计一个简单的决策逻辑 Service。Service RequiredArgsConstructor public class SmartAviationAgentService { private final AviationAssistant aviationAssistant; // 带工具调用的助手 private final RagQaService ragQaService; // RAG 知识库助手 private final ChatClient chatClient; // 通用对话 public String processQuery(String userQuery, String sessionId) { // 1. 意图识别 (简化版实际可用小模型或规则) String intent classifyIntent(userQuery); // 2. 路由到不同处理器 return switch (intent) { case FLIGHT_STATUS, FLIGHT_SEARCH - { // 交给能调用航班查询工具的助手 yield aviationAssistant.chat(userQuery); } case COMPANY_POLICY - { // 交给 RAG 知识库助手 yield ragQaService.answerQuestion(userQuery); } default - { // 通用闲聊或无法识别的用基础对话 Prompt prompt new Prompt(new UserMessage(userQuery)); yield chatClient.call(prompt).getResult().getOutput().getContent(); } }; } private String classifyIntent(String query) { // 这里是一个简单的关键词匹配生产环境应使用更复杂的NLU模型 query query.toLowerCase(); if (query.contains(航班) (query.contains(状态) || query.contains(查询) || query.matches(.*[A-Z]{2}\\d{3,4}.*))) { return FLIGHT_STATUS; } else if (query.contains(航班) (query.contains(查) || query.contains(飞))) { return FLIGHT_SEARCH; } else if (query.contains(行李) || query.contains(退票) || query.contains(改签) || query.contains(规定)) { return COMPANY_POLICY; } else { return GENERAL; } } }最终验证 创建一个AgentController暴露/smart/ask端点。用户向这个端点提问后端会根据问题意图自动选择最合适的处理管道工具调用、RAG检索或普通对话来生成回答。这就构成了一个初级但功能完整的“智能航空客服”核心。8. 资源占用、性能观察与优化建议Java AI 应用的主要资源消耗不在框架本身而在于外部调用和向量计算。内存占用应用本身Spring Boot 应用通常占用 500MB - 2GB 堆内存取决于文档处理量。通过-Xmx参数控制。向量存储这是内存大头。使用内存向量库如InMemoryEmbeddingStore时存储百万级向量可能占用数 GB 内存。务必使用外部向量数据库如 Redis, PgVector用于生产环境。观察方法使用 JConsole, VisualVM 或jcmd pid GC.heap_info监控堆内存。CPU/GPU 占用本地嵌入模型如果使用本地运行的嵌入模型如sentence-transformers通过 ONNX Runtime推理时会占用 CPU/GPU。需监控相关进程。API 调用主要消耗在网络 I/O 和 JSON 序列化/反序列化CPU 占用不高。观察方法使用top(Linux/macOS) 或任务管理器 (Windows)。网络延迟调用云端模型 API 和向量数据库是主要延迟来源。建议模型 API 选择地理距离近的区域。向量数据库与应用服务器同机房或同 VPC 部署。对 RAG 检索结果实施缓存。使用异步非阻塞如 WebFlux处理并发请求。优化建议批量处理对于文档入库RAG 嵌入使用EmbeddingStoreIngestor的批量摄入减少 API 调用次数。缓存对频繁且结果不变的查询如“行李规定是什么”在应用层或 Redis 缓存最终答案。超时与重试为所有外部调用模型 API、向量库配置合理的超时和重试策略。连接池为数据库和 Redis 客户端配置连接池。监控与告警对 API 调用成功率、响应时间、向量检索耗时设置监控。9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动报错No qualifying bean of type ‘ChatClient’Spring AI 相关依赖未正确引入或版本冲突。1. 检查pom.xml依赖。2. 运行mvn dependency:tree查看冲突。3. 检查SpringBootApplication主类扫描路径。1. 确保引入了正确的 starter。2. 排除冲突的 transitive 依赖。3. 确认主类在根包下。调用/chat接口返回 401 错误。API Key 配置错误、过期或没有权限。1. 检查application.yml中api-key配置。2. 确认环境变量是否生效。3. 在命令行用curl直接测试模型 API。1. 使用echo $OPENAI_API_KEY验证环境变量。2. 在云平台控制台检查密钥状态和额度。3. 确保网络代理设置正确。LangChain4j 的 Agent 不调用工具。1. 工具类未被 Spring 管理。2. 模型不支持 Function Calling。3. Prompt 未引导模型使用工具。1. 检查工具类是否有Component或Service。2. 确认使用的模型如gpt-3.5-turbo是否支持函数调用。3. 查看SystemMessage中的指令是否清晰。1. 确保工具 Bean 被正确注入到AiServices。2. 升级到支持工具调用的模型如gpt-4o-mini。3. 在 System Prompt 中明确要求模型使用工具。RAG 回答与知识库内容不符。1. 文档未成功摄入向量库。2. 检索到的相关片段太少或无关。3. 嵌入模型不适合该类型文本。1. 检查ingestDocument方法日志确认片段数量。2. 检查向量库中是否有数据。3. 调整文本分割策略块大小、重叠。4. 尝试不同的嵌入模型。1. 验证文档加载路径和解析格式。2. 增加检索返回的片段数量maxResults。3. 优化文本分割参数或尝试语义分割。4. 在 Prompt 中加强指令要求“严格依据上下文”。应用响应缓慢。1. 模型 API 响应慢。2. 向量检索慢。3. 内存不足导致 GC 频繁。1. 在代码中打印各阶段耗时。2. 监控向量数据库性能。3. 观察 JVM GC 日志。1. 为外部调用设置超时考虑异步或缓存。2. 为向量库字段建立索引。3. 调整 JVM 堆大小优化代码避免内存泄漏。OutOfMemoryError: Java heap space1. 一次性加载超大文件进行嵌入。2. 内存向量库存储过多向量。3. JVM 堆内存设置过小。1. 分析堆转储文件。2. 检查文档处理逻辑。1. 流式处理大文件分批次嵌入。2.切勿在生产环境使用内存向量库。3. 增加 JVM 堆大小 (-Xmx4g)。10. 最佳实践与项目进阶建议从简单开始逐步迭代不要一开始就设计复杂的 Agent。先跑通 Spring AI 的基础对话再加入一个工具然后集成 RAG最后考虑路由和编排。配置外部化将所有敏感信息API Keys、数据库连接和可变参数模型名称、温度放在application.yml或配置中心并通过ConfigurationProperties管理。实现健康检查与监控为关键组件模型 API 连通性、向量数据库连接实现 Health Indicator。使用 Micrometer 暴露指标集成到 Prometheus 和 Grafana。设计可观测性在关键链路如工具调用、RAG 检索、模型调用添加详细日志和 Trace ID便于问题排查。处理速率限制与降级云模型 API 都有速率限制。实现令牌桶或漏桶算法进行限流并设计降级策略如切换到备用模型或返回缓存内容。安全第一输入输出过滤对用户输入和模型输出进行必要的敏感词过滤和内容安全审核。工具权限严格管控 Agent 可调用的工具权限例如数据库查询工具只能执行只读操作或经过参数化校验的操作。用户会话隔离确保不同用户的对话记忆ChatMemory和 RAG 检索上下文严格隔离防止信息泄露。持续学习与调优RAG 效果评估建立评估集定期测试 RAG 问答的准确率优化文档切分、检索和 Prompt 模板。Agent 路径分析记录用户问题被路由到哪个处理器分析意图识别的准确率持续优化分类逻辑。对于 Java 开发者而言Spring AI 和 LangChain4j 的组合提供了一条平稳的 AI 集成路径。它允许你利用现有的 Spring 工程化能力快速构建出具备对话、知识库和工具调用功能的智能应用。最先应该验证的是 Spring AI 的基础连接和 LangChain4j 的简单工具调用这是整个技术栈的基石。最容易踩的坑是依赖版本冲突和 API Key 等配置问题严格按照官方文档的版本搭配可以避开大部分问题。下一步你可以深入探索 Spring AI 的流式响应、函数调用Function Calling支持或者利用 LangChain4j 更复杂的 Agent 执行器如ReAct模式来构建能自主规划步骤的智能体。将向量数据库升级到生产级并引入缓存和异步处理你的智能航空客服就能从 Demo 走向真正可用的服务。