这次我们来看一个面向 Java 开发者的 AI 应用开发教程。这个教程的核心不是教你训练模型而是教你如何利用 Spring AI、SpringAIAlibaba、RAG、MCP 和 FastAPI 这些框架和工具快速构建企业级的 AI 应用。对于习惯了 Spring 生态的 Java 开发者来说这是一个从传统后端开发平滑过渡到 AI 应用开发的绝佳路径。教程的重点在于“能用”和“怎么用”。它不要求你精通复杂的机器学习算法而是关注如何将大模型能力像调用普通服务一样集成到你的 Java 项目中。你会学到如何搭建一个具备知识库问答RAG能力的智能客服如何通过 MCP 协议让 AI 调用外部工具以及如何用 FastAPI 构建一个轻量、高性能的 AI 服务网关。整个过程强调工程化、可部署和可维护。本文会带你从零开始梳理这套技术栈的核心概念、环境搭建、项目构建、功能实现到最终部署上线的完整流程。无论你是想为现有系统增加智能问答功能还是想从零开发一个 AI 应用这篇文章都能提供一套清晰的行动指南。适合有一定 Spring Boot 和 Java 基础的开发者目标是让你看完就能动手跑通第一个 AI 集成 demo。1. 核心能力速览在深入细节之前我们先快速了解这套“Spring AI SpringAIAlibaba RAG MCP FastAPI”组合拳能做什么以及它的技术门槛。能力项说明技术栈定位面向 Java 开发者的 AI 应用全栈开发方案强调工程化集成而非模型研发。核心框架Spring AISpring 官方 AI 项目提供统一的 AI 模型调用抽象。SpringAIAlibaba阿里云对 Spring AI 的增强实现深度集成阿里云百炼平台等服务。核心功能RAG检索增强生成为 AI 模型注入私有知识实现基于文档的精准问答。MCPModel Context Protocol让 AI 模型能够安全、可控地调用外部工具和 API。FastAPI作为高性能 API 网关或独立 AI 服务提供灵活的接口层。开发语言主要使用Java (Spring Boot)部分组件如 FastAPI、向量数据库客户端可能涉及 Python。硬件门槛无特殊 GPU 要求。本方案主要调用云端大模型 API如 OpenAI、通义千问、DeepSeek或本地部署的模型服务开发机普通 CPU 即可。若需本地部署嵌入模型或轻量级模型进行测试则对内存有一定要求。启动方式标准的 Spring Boot 应用启动方式mvn spring-boot:run或运行Application类以及 Python 的 FastAPI 服务启动uvicorn。接口能力提供完整的 RESTful API支持同步/异步调用易于被前端或其他服务集成。批量任务支持通过任务队列如 Spring Batch、RabbitMQ处理批量文档的向量化入库、批量问答等。适合场景企业知识库问答、智能客服、AI 辅助编程工具、数据分析报告生成、自动化流程 Agent 等。2. 适用场景与使用边界这套技术组合并非万能明确其适用边界能帮助你更好地决策。它非常适合以下场景已有 Java/Spring 技术栈的团队希望快速引入 AI 能力而不想完全转向 Python 技术栈。构建企业级 AI 应用需要稳定的服务、清晰的架构、完善的监控和日志而不仅仅是跑通一个 Demo。私有知识库问答RAG公司内部有大量文档产品手册、技术规范、客服话术需要构建一个能准确回答内部问题的智能助手。需要 AI 调用外部能力MCP例如让 AI 根据对话内容查询数据库、发送邮件、调用内部审批系统等。需要高性能 API 网关FastAPI 以其异步高性能著称适合作为面对高并发请求的 AI 服务入口或聚合层。它可能不适合AI 模型研究与训练本方案核心是应用和集成而非从头训练或微调大模型。对延迟极其敏感的实时场景调用云端大模型 API 通常有几百毫秒到几秒的延迟需结合缓存、流式输出等技术优化体验。完全离线的纯本地部署虽然 RAG 的向量检索可以本地进行但核心的大模型生成能力通常依赖云端 API。若需完全离线需自行部署本地大模型复杂度会显著增加。预算极其有限的项目调用商用大模型 API 会产生费用需根据 token 使用量进行成本评估。合规与安全边界数据安全向云端大模型发送数据时需确认服务商的隐私政策敏感数据应做脱敏处理或使用私有化部署的模型。知识版权构建 RAG 系统时确保使用的文档材料拥有合法授权。工具调用MCP需严格定义和限制 AI 可调用的工具范围防止越权操作。3. 环境准备与前置条件开始编码前需要准备好以下环境。这是保证后续步骤顺利的基础。1. 基础开发环境JDK 17 或更高版本Spring AI 推荐使用 JDK 17。Maven 3.6 或 Gradle用于项目管理。Python 3.8用于运行 FastAPI 服务或一些 Python 工具链如用于文本分词的库。IDEIntelliJ IDEA推荐、VS Code 或 Eclipse。2. 模型服务准备三选一或组合云端大模型 API准备一个可用的 API Key。OpenAIGPT-3.5/4 系列。阿里云百炼通义千问系列。DeepSeek、智谱 AI等国内可用服务。可选本地嵌入模型用于将文本转换为向量。可使用sentence-transformers等库本地运行或直接使用云服务。可选本地大模型如通过Ollama、LM Studio等在本地部署轻量模型用于测试或特定场景。3. 向量数据库用于 RAG选择一款并准备好连接信息。常见的有Chroma轻量易于上手适合开发和测试。Milvus功能强大适合生产环境。PGVector基于 PostgreSQL 的扩展适合已有 PG 生态的团队。阿里云向量检索服务云服务免运维。4. 其他工具Docker可选方便一键启动向量数据库等服务。Postman 或 curl用于测试 API。Git代码版本管理。4. 安装部署与启动方式我们将以一个典型的项目结构为例演示如何搭建一个融合了 RAG 和 MCP 的 Spring Boot AI 应用并用 FastAPI 包装一层。4.1 创建 Spring Boot 项目使用 Spring Initializr 或 IDE 创建新项目依赖选择Spring WebSpring AI(需要添加 Spring 的 milestone 或 snapshot 仓库)Lombok(简化代码)Spring Data JPA(如果使用关系型数据库存储会话等)4.2 添加关键依赖在pom.xml中需要显式添加 Spring AI 及相关连接器的依赖。以使用 OpenAI 和 Chroma 为例!-- Spring AI OpenAI 连接器 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version0.8.1/version !-- 请使用最新稳定版 -- /dependency !-- Spring AI Chroma 向量存储连接器 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-chroma-store-spring-boot-starter/artifactId version0.8.1/version /dependency !-- SpringAIAlibaba (如果需要) -- !-- 请根据阿里云官方文档添加对应的 starter -- !-- FastAPI 是独立的 Python 服务此处无需 Java 依赖 --4.3 配置应用属性在application.yml中配置关键信息spring: ai: openai: api-key: ${OPENAI_API_KEY:your-openai-key-here} # 建议使用环境变量 chat: options: model: gpt-3.5-turbo # 或 gpt-4 vectorstore: chroma: host: localhost port: 8000 collection-name: my_knowledge_base # 配置 Chroma 向量数据库连接如果本地运行 # 通常通过 Docker 运行: docker run -p 8000:8000 chromadb/chroma4.4 启动 Spring Boot 应用配置完成后直接启动主类# 在项目根目录下 mvn clean spring-boot:run或直接在 IDE 中运行Application类的main方法。看到 Tomcat 启动在 8080 端口默认即表示成功。4.5 启动 FastAPI 服务可选假设我们有一个独立的 Python 服务用于处理文件上传、解析等任务并通过 HTTP 与 Spring Boot 服务通信。创建fastapi_app.pyfrom fastapi import FastAPI, File, UploadFile from pydantic import BaseModel import requests import logging app FastAPI(titleAI Gateway) SPRING_AI_SERVICE_URL http://localhost:8080 class QueryRequest(BaseModel): question: str app.post(/v1/chat) async def chat_with_ai(request: QueryRequest): 将请求转发给后端的 Spring AI 服务 try: response requests.post(f{SPRING_AI_SERVICE_URL}/api/chat, json{message: request.question}, timeout30) response.raise_for_status() return response.json() except Exception as e: logging.error(f调用后端服务失败: {e}) return {error: Service temporarily unavailable} app.post(/v1/upload) async def upload_document(file: UploadFile File(...)): 上传文档到知识库这里简化处理实际应调用 Spring 服务的文档处理接口 contents await file.read() # 这里可以添加文件解析、分块等逻辑然后调用 Spring 服务的向量化接口 # 例如requests.post(f{SPRING_AI_SERVICE_URL}/api/ingest, datachunks) return {filename: file.filename, status: received} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)启动 FastAPI 服务pip install fastapi uvicorn requests python fastapi_app.py现在你有两个服务在运行Spring Boot (8080) 和 FastAPI (8000)。前端可以直接调用 FastAPI 的接口。5. 功能测试与效果验证下面我们分模块验证核心功能是否正常工作。5.1 基础 AI 对话测试首先测试 Spring AI 直接调用大模型的能力。测试目的验证 Spring AI 配置是否正确能否正常与 OpenAI或其他模型通信。操作步骤在 Spring Boot 项目中创建一个简单的 Controller。RestController RequestMapping(/api) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } PostMapping(/chat) public MapString, String chat(RequestBody MapString, String request) { String message request.get(message); String response chatClient.call(message); return Map.of(response, response); } }启动应用。使用 Postman 或 curl 发送请求。curl -X POST http://localhost:8080/api/chat \ -H Content-Type: application/json \ -d {message: 请用Java写一个Hello World程序}预期结果收到一个包含 JavaHello World代码的 JSON 响应。判断成功HTTP 状态码为 200且响应中包含合理的代码文本。常见失败原因API Key 错误、网络不通、模型服务不可用、依赖版本冲突。5.2 RAG 知识库构建与问答测试这是核心功能验证能否将私有知识注入 AI。测试目的将一篇技术文档如 Markdown 文件存入向量数据库然后针对文档内容提问看 AI 能否基于文档正确回答。操作步骤文档处理服务创建一个 Service用于将文档分块、向量化并存储到 Chroma。Service public class RAGService { private final VectorStore vectorStore; private final EmbeddingClient embeddingClient; public RAGService(VectorStore vectorStore, EmbeddingClient embeddingClient) { this.vectorStore vectorStore; this.embeddingClient embeddingClient; } public void ingestDocument(String documentText, String docId) { // 1. 文本分块 (这里简化实际可用更复杂的分块策略) ListString chunks splitTextIntoChunks(documentText); // 2. 为每个块创建包含内容和元数据的 Document 对象 ListDocument documents chunks.stream() .map(chunk - new Document(chunk, Map.of(source, docId))) .toList(); // 3. 存储到向量数据库 vectorStore.add(documents); } public String query(String question) { // 1. 将问题转换为向量 // 2. 在向量数据库中做相似度搜索获取最相关的几个文本块 ListDocument relevantDocs vectorStore.similaritySearch(question); // 3. 将相关文本块作为上下文与问题一起构造 Prompt 发送给大模型 String context relevantDocs.stream().map(Document::getContent).collect(Collectors.joining(\n\n)); String prompt String.format( 请基于以下上下文回答问题。如果上下文不包含答案请说“根据已知信息无法回答”。 上下文 %s 问题%s 答案 , context, question); // 4. 调用 ChatClient 获取答案 return chatClient.call(prompt); } private ListString splitTextIntoChunks(String text) { // 简单实现 // 按段落或固定长度分块 return Arrays.asList(text.split(\n\n)); } }构建知识库通过一个 API 端点或初始化 Bean 来加载你的文档。RestController RequestMapping(/api/rag) public class RAGController { private final RAGService ragService; // ... 构造函数 PostMapping(/ingest) public String ingest(RequestBody DocumentIngestRequest request) { ragService.ingestDocument(request.getContent(), request.getDocId()); return Ingestion successful; } PostMapping(/query) public MapString, String query(RequestBody MapString, String request) { String answer ragService.query(request.get(question)); return Map.of(answer, answer); } }测试首先调用/api/rag/ingest接口上传一篇关于“Spring AI 配置”的文档内容。然后调用/api/rag/query接口提问“如何在 Spring Boot 中配置 OpenAI 的 API Key”预期结果AI 返回的答案应基于你上传的文档内容而不是其通用知识。判断成功答案准确引用了文档中的配置步骤或关键代码片段。常见失败原因文本分块不合理、向量化模型不匹配、相似度搜索返回结果不相关、Prompt 构造不佳。5.3 MCP 工具调用测试测试 AI 能否根据指令调用外部工具。测试目的让 AI 理解用户意图并调用我们预先注册好的工具例如查询天气、计算器。操作步骤定义工具创建一个“计算器”工具。Component public class CalculatorTool implements FunctionCalculatorTool.Request, CalculatorTool.Response { public record Request(double a, double b, String operator) {} public record Response(double result) {} Override public Response apply(Request request) { return switch (request.operator) { case - new Response(request.a request.b); case - - new Response(request.a - request.b); case * - new Response(request.a * request.b); case / - new Response(request.a / request.b); default - throw new IllegalArgumentException(Unsupported operator); }; } }注册工具并调用Spring AI 提供了AiService和Tool注解来简化工具调用。我们需要配置一个AiService将工具暴露给模型。Service public class ToolService { private final AiService aiService; public ToolService(CalculatorTool calculatorTool) { // 构建 AiService注册工具 var toolRegistry new SimpleToolRegistry(calculatorTool); var chatModel new OpenAiChatModel(...); // 注入配置好的 ChatModel this.aiService AiService.builder() .chatModel(chatModel) .toolRegistry(toolRegistry) .build(); } public String executeWithTools(String userMessage) { // AiService 会自动解析用户消息决定是否以及如何调用工具 return aiService.call(userMessage); } }测试调用ToolService传入消息“请计算 123 乘以 456 等于多少”预期结果AI 会识别出计算意图调用CalculatorTool并返回计算结果。判断成功返回正确的计算结果56088并且日志中能看到工具被调用的记录。常见失败原因工具描述不清晰、模型不支持工具调用、请求格式不符合模型要求。5.4 FastAPI 网关集成测试测试通过 FastAPI 统一入口访问后端服务是否正常。测试目的验证 FastAPI 服务能否正确代理请求到 Spring Boot AI 服务。操作步骤确保 Spring Boot 服务端口 8080和 FastAPI 服务端口 8000都已启动。使用 curl 直接调用 FastAPI 的聊天接口。curl -X POST http://localhost:8000/v1/chat \ -H Content-Type: application/json \ -d {question: FastAPI 是什么}预期结果收到来自后端 Spring AI 服务的回答。判断成功FastAPI 返回了 JSON 响应且内容与直接调用 Spring Boot 服务一致。常见失败原因FastAPI 服务配置的后端地址错误、网络端口不通、跨域问题如果从浏览器调用。6. 接口 API 与批量任务6.1 接口 API 设计要点一个健壮的 AI 应用 API 应考虑以下几点统一响应格式使用固定的 JSON 结构包装成功和错误响应。{ code: 200, msg: success, data: { /* 实际数据 */ } }异步处理对于耗时的任务如文档向量化、长文本生成提供异步接口立即返回一个任务 ID客户端可轮询结果。PostMapping(/async-task) public ResponseEntityMapString, String createAsyncTask(RequestBody TaskRequest request) { String taskId taskService.submit(request); return ResponseEntity.accepted().body(Map.of(taskId, taskId, statusUrl, /api/tasks/ taskId)); } GetMapping(/tasks/{taskId}) public TaskResult getTaskResult(PathVariable String taskId) { ... }流式输出SSE对于 AI 对话支持 Server-Sent Events (SSE) 流式返回 tokens提升用户体验。GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam String message) { return chatClient.stream(message).map(ChatResponse::getOutput); }6.2 批量任务处理RAG 系统中批量导入文档是常见需求。场景有 1000 个 PDF 文件需要构建进知识库。方案使用 Spring Batch定义ItemReader(读取文件)ItemProcessor(解析文本、分块、向量化)ItemWriter(写入向量数据库)。使用消息队列将每个文件处理任务作为消息发送到 RabbitMQ 或 Kafka由多个消费者并发处理提高吞吐量。实现要点断点续传记录已处理文件任务中断后可从断点继续。错误处理单个文件处理失败不应影响整体任务记录失败日志供后续重试或人工处理。资源控制控制并发度避免对向量数据库或模型 API 造成过大压力。简易批量处理 Service 示例Service Slf4j public class BatchIngestionService { private final RAGService ragService; private final ExecutorService executorService Executors.newFixedThreadPool(5); // 控制并发数 public void batchIngestFiles(ListFile files) { ListCompletableFutureVoid futures files.stream() .map(file - CompletableFuture.runAsync(() - { try { String content parseFile(file); // 解析文件内容 ragService.ingestDocument(content, file.getName()); log.info(文件 {} 处理完成, file.getName()); } catch (Exception e) { log.error(处理文件 {} 失败, file.getName(), e); // 可以记录到失败列表后续重试 } }, executorService)) .toList(); // 等待所有任务完成 CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join(); executorService.shutdown(); } }7. 资源占用与性能观察由于本方案主要调用远程 API本地资源占用主要集中在应用本身和向量数据库。Spring Boot 应用常规的 Java 应用内存占用堆内存 512MB-2GB 起步取决于负载和缓存。CPU 消耗主要在处理请求、序列化和网络 IO。向量数据库如本地 Chroma内存占用与存储的向量数量和维度成正比。对于百万级向量的知识库可能需要数 GB 内存。CPU 用于相似度计算。FastAPI 服务Python 进程内存占用相对较小几百 MB在高并发下会创建多个工作进程。性能观察与调优点API 调用延迟这是主要瓶颈。监控调用大模型 API 的耗时考虑使用连接池、设置合理的超时时间、启用重试机制。向量检索速度确保向量数据库的索引类型适合你的查询模式如 HNSW。监控检索耗时如果过慢需考虑优化索引参数或升级硬件。JVM 监控使用 VisualVM、JConsole 或 Arthas 监控 Spring Boot 应用的 GC 情况、线程状态和堆内存。数据库连接池监控向量数据库和关系型数据库如果使用的连接池使用情况避免连接泄露。异步化将耗时的 I/O 操作如调用模型 API、向量检索异步化避免阻塞 Web 容器线程提升整体吞吐量。8. 常见问题与排查方法在开发和部署过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案启动 Spring Boot 应用失败提示spring-ai依赖找不到。Maven 仓库未配置 Spring 的 milestone/snapshot 仓库。检查pom.xml或settings.xml中的仓库配置。在pom.xml的repositories中添加 Spring 的 milestone 仓库。调用/api/chat返回 401 或 403 错误。API Key 配置错误、过期或没有权限。检查application.yml中的spring.ai.openai.api-key或查看服务商控制台。使用正确的 API Key确保其在请求的服务商处有效。RAG 问答效果差答案与文档无关。1. 文本分块不合理过大或过小。2. 向量化模型与检索模型不匹配。3. 相似度搜索返回的 top-k 值太小。4. Prompt 构造不佳。1. 检查分块后的文本内容。2. 检查向量数据库存储和查询使用的模型是否一致。3. 打印出相似度搜索返回的文本块看是否相关。1. 调整分块策略按段落、按句子、重叠分块。2. 确保使用相同的嵌入模型。3. 增加top-k参数值。4. 优化 Prompt明确指令。向量数据库连接失败如 Chroma。Chroma 服务未启动或主机端口配置错误。使用docker ps或netstat检查 Chroma 服务状态和端口监听。确保 Chroma 服务正常运行并检查 Spring 配置中的host和port。MCP 工具调用不生效AI 不调用工具。1. 工具函数签名或描述不符合模型要求。2. 当前使用的模型不支持工具调用功能。3. 用户提问方式未能触发工具调用。1. 检查工具类的Tool注解描述是否清晰。2. 确认使用的模型如gpt-3.5-turbo是否支持 function calling。3. 查看模型返回的原始响应看是否包含了工具调用请求。1. 遵循 Spring AI 或模型提供商对工具定义的要求。2. 升级到支持工具调用的模型如gpt-3.5-turbo-1106或更高版本。3. 在用户提问中更明确地指示需要计算或查询。FastAPI 服务调用 Spring Boot 服务超时。网络问题或 Spring Boot 服务处理时间过长。检查两台服务器之间的网络连通性并查看 Spring Boot 服务的日志是否有慢查询或错误。1. 确保网络通畅防火墙规则允许。2. 在 FastAPI 中增加请求超时时间。3. 优化 Spring Boot 服务的性能。批量导入文档时内存溢出OOM。一次性加载所有文件内容到内存或向量化过程占用内存过大。使用 JVM 内存分析工具如 Eclipse MAT查看堆转储。1. 采用流式或分页方式读取和处理文件。2. 控制批量处理的并发度。3. 增加 JVM 堆内存 (-Xmx)。9. 最佳实践与使用建议基于项目经验给出以下建议帮助你构建更稳健的系统环境隔离为开发、测试、生产环境配置不同的application-{profile}.yml文件区分 API Key、数据库地址等敏感信息。配置外部化API Key、数据库密码等敏感信息务必通过环境变量或配置中心如 Nacos、Apollo注入不要硬编码在代码中。优雅降级当大模型 API 不可用时应有降级策略如返回缓存答案、提示服务繁忙。限流与熔断使用 Resilience4j 或 Sentinel 对模型 API 调用进行限流和熔断防止因下游服务不稳定导致系统雪崩。可观测性集成 Micrometer 和 Prometheus暴露应用指标请求量、延迟、错误率。对关键的 RAG 检索和 AI 生成步骤打点记录耗时。Prompt 管理不要将 Prompt 硬编码在代码中。可以将其存储在数据库或配置文件中便于迭代优化和 A/B 测试。向量数据库维护定期清理过时或无效的向量数据。对于大规模知识库考虑建立向量索引的更新策略。版权与合规用于构建 RAG 的文档必须确保有合法使用权。在 AI 生成的答案中可考虑添加“本回答基于内部资料生成仅供参考”等免责声明。如果涉及用户数据需严格遵守隐私政策必要时对数据进行脱敏。测试策略单元测试测试工具函数、文本分块逻辑等。集成测试测试与向量数据库、模型 API 的集成。端到端测试模拟用户完整流程从提问到获取答案。效果评估构建一个测试集定期评估 RAG 问答的准确率、相关性。10. 总结与下一步这套“Spring AI SpringAIAlibaba RAG MCP FastAPI”的组合为 Java 开发者打开了一扇高效构建 AI 应用的大门。它的最大价值在于将前沿的 AI 能力无缝集成到成熟的 Java 企业级开发体系中让你能用熟悉的 Spring 模式去开发智能应用。最先应该验证的功能是基础 AI 对话和RAG 知识库问答。这两个功能跑通整个技术栈的核心链路就打通了。最容易踩的坑通常是环境配置仓库、API Key和文本分块策略按照本文的步骤和排查方法大部分问题都能解决。完成基础功能后可以继续深入以下几个方向性能优化引入缓存如 Redis 缓存常见问答结果、实现流式输出、优化向量检索的索引参数。架构扩展将 AI 服务拆分为独立的微服务通过服务网关统一管理。引入消息队列处理异步任务。能力增强接入多模态模型处理图片、音频实现更复杂的 Agent 工作流让 AI 自动规划并调用多个工具完成任务。前端集成开发一个友好的 Web 聊天界面或与现有业务系统如 OA、CRM集成。建议将本文作为动手实践的路线图从创建一个最简单的 Spring Boot AI 项目开始逐步添加 RAG、MCP 等功能模块。过程中多查看 Spring AI 官方文档和对应模型服务商的文档它们提供了最权威的 API 说明和最佳实践。