这次我们来看一个完整的 AI 应用开发与部署实战。如果你对如何将 Prompt 工程、后端框架和 RAG 系统串联起来最终打包成一个可运行的 Docker 服务感兴趣这篇文章就是为你准备的。整个过程不绕弯子直接上手从零开始覆盖从核心概念到生产部署的全链路。我们将聚焦三个核心模块Prompt 工程是驱动 AI 的“指令集”决定了模型输出的质量Spring AI是 Java 生态中连接这些 AI 能力的桥梁让后端开发变得简单RAGFlow则是一个强大的开源 RAG 引擎负责知识库的构建与智能检索。最终我们会把所有组件通过 Docker 容器化实现一键部署和稳定运行。本文的重点不是空谈理论而是提供一套可执行、可验证的实操方案。你会看到如何设计有效的 Prompt如何用 Spring AI 快速集成大模型如何部署和配置 RAGFlow 服务以及如何将它们整合成一个完整的应用。无论你是想验证一个想法还是为现有系统添加 AI 能力这套流程都能提供清晰的路径。1. 核心能力速览在深入细节之前我们先快速了解这三个核心组件的定位、功能以及它们组合在一起能做什么。能力项说明项目类型全栈 AI 应用开发与部署实战核心组件Prompt 工程(设计)、Spring AI(集成)、RAGFlow(检索)主要功能1. 基于 Prompt 指令驱动 AI 模型完成特定任务。2. 使用 Spring AI 框架在 Java 应用中便捷调用多种大模型 API。3. 利用 RAGFlow 构建本地知识库实现基于文档的精准问答。4. 通过 Docker 将整个应用栈容器化实现环境隔离与一键部署。推荐硬件开发机8GB 内存。运行 RAGFlow 及大模型服务建议 16GB 内存。GPU 非必需但可加速 Embedding 和推理。显存占用取决于具体加载的模型。如果使用本地 Embedding 模型如bge-large-zh-v1.5和轻量级 LLM如 Qwen2.5-7B可能需要 4GB-8GB 显存。纯 CPU 模式内存占用较高。支持平台Windows (WSL2/Docker Desktop), Linux, macOS启动方式Spring Boot 应用可通过mvn spring-boot:run或打包的 Jar 启动。RAGFlow 提供 Docker Compose 一键启动。是否支持 API是。Spring AI 应用可暴露 REST API。RAGFlow 本身提供完整的 OpenAPI 接口。是否支持批量任务是。可通过 Spring AI 的BatchClient或自行编写循环逻辑处理批量 Prompt。RAGFlow 支持批量文档上传与解析。适合场景企业知识库问答、智能客服助手、文档分析与摘要、内部工具 AI 化、AI 应用原型快速验证。2. 适用场景与使用边界这个技术栈组合适合哪些人能解决什么问题又有哪些需要注意的边界适合谁Java 后端开发者希望在不切换技术栈的前提下为现有系统引入 AI 能力。全栈工程师/技术负责人需要快速搭建一个包含知识检索功能的 AI 应用原型或产品。对 RAG 感兴趣的学习者想了解从知识库构建、检索到应用集成的完整闭环。能解决什么问题信息过载与查找困难将公司内部文档、产品手册、会议纪要等上传至 RAGFlow构建专属知识库实现精准、快速的智能问答。模型调用复杂统一不同大模型供应商OpenAI, Anthropic, 智谱AI 月之暗面等的 API 调用方式通过 Spring AI 的抽象层简化开发。应用交付与部署通过 Docker 将 AI 应用及其依赖模型、向量数据库打包实现开发、测试、生产环境的一致性避免“在我机器上能跑”的问题。不适合什么场景超大规模、高并发的生产场景本文演示的是一套标准开发部署流程对于千万级文档、每秒数千次查询的场景需要在架构、缓存、负载均衡等方面进行深度优化。对延迟极其敏感的场景本地部署的 Embedding 和 LLM 模型推理速度受硬件限制可能无法满足毫秒级响应的需求。完全离线、无网络环境虽然 RAGFlow 和部分模型可以本地部署但 Spring AI 初始可能需要从 Maven 中央仓库下载依赖且某些模型仍需联网调用。版权、隐私与安全边界模型与数据版权确保使用的模型尤其是商业模型 API符合其服务条款。使用 RAGFlow 处理文档时确保你拥有文档的合法使用权。隐私数据如果知识库包含用户隐私、公司机密等敏感信息务必做好 Docker 容器的网络隔离、访问控制并考虑对存储卷进行加密。Prompt 安全注意防范 Prompt 注入攻击避免用户输入恶意指令导致模型泄露系统提示词或执行危险操作。对用户输入进行必要的清洗和校验。合规使用生成的内容需符合法律法规不得用于生成虚假信息、侵权内容或进行非法活动。3. 环境准备与前置条件开始动手之前请确保你的开发环境满足以下要求。这是后续所有步骤能顺利进行的基础。1. 操作系统推荐Linux (Ubuntu 20.04/22.04, CentOS 7) 或 macOS。也可行Windows 10/11但需通过WSL2 (Windows Subsystem for Linux)或Docker Desktop来获得最佳的 Docker 体验。本文命令以 Linux/macOS 环境为主WSL2 用户可在 Ubuntu 子系统中执行。2. 基础开发环境JavaJDK 17 或更高版本。这是 Spring Boot 3.x 和 Spring AI 的硬性要求。java -version # 应输出类似openjdk version “17.0.10” ...Maven3.6 版本用于管理 Spring Boot 项目依赖和打包。mvn -vGit用于克隆项目代码。3. Docker 环境这是部署 RAGFlow 和最终整合应用的关键。Docker Engine版本 20.10。Docker Compose版本 v2.20。通常 Docker Desktop 已包含Linux 需单独安装。验证安装docker --version docker compose version常见问题Windows/macOS 用户若遇到 “Docker Desktop failed to start because virtualization support wasn‘t detected”需在 BIOS/UEFI 中开启虚拟化技术Intel VT-x / AMD-V并确保 Hyper-V 或 Windows 沙盒功能已启用。4. 硬件与资源内存至少 8GB建议 16GB 或以上。运行 RAGFlow (内含 Milvus/PostgreSQL) 和 Java 应用需要较多内存。磁盘空间预留 10GB 以上空间用于 Docker 镜像、模型文件和项目代码。网络需要能顺畅访问 GitHub、Docker Hub 和 Maven 中央仓库以下载依赖和镜像。5. 可选GPU 支持如果你想在本地运行 Embedding 模型或轻量级 LLM 以获得更快速度需要NVIDIA GPU及对应的驱动。NVIDIA Container Toolkit使 Docker 容器能够使用 GPU。# Ubuntu 安装示例 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker安装后可以使用--gpus all参数运行容器。4. 安装部署与启动方式我们将分步进行先部署 RAGFlow再创建 Spring AI 应用最后整合。4.1 部署 RAGFlow (Docker Compose 方式)RAGFlow 提供了最便捷的 Docker Compose 部署方式。步骤 1获取部署文件访问 RAGFlow 的 GitHub 仓库 (https://github.com/infiniflow/ragflow) 或直接下载其docker-compose.yml文件。这里我们使用其最新稳定版。# 创建一个工作目录 mkdir -p ~/ai-app-demo cd ~/ai-app-demo # 下载 docker-compose 文件 (请以官方仓库最新版本为准) wget https://raw.githubusercontent.com/infiniflow/ragflow/main/docker/docker-compose.yml # 如果你网络受限也可以先克隆仓库较大 # git clone https://github.com/infiniflow/ragflow.git # cd ragflow/docker步骤 2启动 RAGFlow 服务在包含docker-compose.yml的目录下执行docker compose up -d这个命令会拉取多个镜像包括 RAGFlow 前端、后端、Milvus向量数据库、PostgreSQL等并以后台模式启动所有服务。步骤 3验证服务状态等待几分钟后检查容器是否正常运行docker compose ps你应该看到所有服务的状态都是Up。访问http://localhost:9380即可打开 RAGFlow 的 Web 界面。首次访问需要注册管理员账号。步骤 4基础配置可选模型配置登录后在“系统设置”-“模型设置”中可以配置 Embedding 模型和 LLM。你可以使用其自带的本地模型如bge-large-zh也可以配置 OpenAI、智谱AI等在线 API。知识库创建点击“知识库”-“新建”上传你的测试文档如 PDF、Word、TXTRAGFlow 会自动进行切片、向量化并存入 Milvus。至此一个功能完整的 RAG 后端服务就已经在本地 9380 端口运行起来了它提供了文档管理、向量检索和问答的完整 API。4.2 创建与配置 Spring AI 应用接下来我们构建一个简单的 Spring Boot 应用集成 Spring AI 来调用大模型。步骤 1初始化 Spring Boot 项目使用 Spring Initializr (https://start.spring.io) 或 IDE 创建新项目。Project: MavenLanguage: JavaSpring Boot: 3.2.x (确保是 3.x)Dependencies: 添加Spring Web,Spring AI(如果列表中有)。如果没有可以手动在pom.xml中添加。步骤 2添加 Spring AI 依赖编辑项目的pom.xml文件添加 Spring AI 的 BOM 和具体模块依赖。以使用 OpenAI API 为例dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version0.8.1/version !-- 请使用最新稳定版 -- typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies !-- ... 其他依赖如 Spring Web ... -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency /dependencies如果你想连接本地部署的模型如通过 Ollama可以添加spring-ai-ollama-spring-boot-starter。步骤 3配置应用属性在src/main/resources/application.yml中配置模型连接信息。spring: application: name: ai-demo-app # OpenAI 配置示例 spring.ai.openai: api-key: ${OPENAI_API_KEY:sk-your-key-here} # 建议使用环境变量 base-url: https://api.openai.com/v1 # 如果是 Azure OpenAI 或其他代理修改此处 chat: options: model: gpt-3.5-turbo temperature: 0.7 # 如果需要连接本地 RAGFlow API配置 RestTemplate 或 WebClient ragflow: base-url: http://localhost:9380 api-key: ${RAGFLOW_API_KEY:} # 在 RAGFlow 用户设置中创建 API Key步骤 4编写一个简单的 Prompt 测试接口创建一个 Controller 来测试 Spring AI 的基本功能。package com.example.aidemo.controller; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(“/ai/chat”) public String chat(RequestParam(defaultValue “你好请介绍一下你自己。”) String message) { return chatClient.prompt() .user(message) .call() .content(); } GetMapping(“/ai/prompt”) public String structuredPrompt() { // 一个更结构化的 Prompt 示例 String promptTemplate “”” 你是一位专业的翻译家。请将以下英文技术术语翻译成中文并给出一个简短的解释。 术语{term} 请严格按照以下格式回复 中文翻译[翻译结果] 解释[你的解释] “””; return chatClient.prompt() .user(u - u.text(promptTemplate).param(“term”, “Neural Network”)) .call() .content(); } }步骤 5启动并测试 Spring AI 应用# 在项目根目录下 mvn clean spring-boot:run应用启动后访问http://localhost:8080/ai/chat?messageHello和http://localhost:8080/ai/prompt应该能收到来自 AI 模型的回复。这验证了 Spring AI 集成成功。5. 功能测试与效果验证现在我们分别对 Prompt 工程、Spring AI 集成和 RAGFlow 功能进行测试确保每个环节都工作正常。5.1 Prompt 工程测试设计有效的指令Prompt 的质量直接决定输出效果。我们测试几种常见模式。测试 1基础指令清晰化目的验证模型是否能理解并执行明确的角色和格式指令。输入通过/ai/chat接口参数调整“请扮演一位经验丰富的软件架构师。我的问题是在微服务架构中如何设计一个高可用的配置中心请分点列出核心要点每点不超过两句话。”预期结果回复应体现“架构师”口吻内容结构化分点且紧扣“高可用配置中心”主题。判断成功回复有条理、专业且未偏离主题。测试 2少样本学习Few-Shot Prompting目的通过提供例子让模型模仿特定风格或格式完成任务。输入“请根据以下例子将输入的情感分类为‘积极’、‘消极’或‘中性’。 例子 输入‘这个产品太棒了解决了我所有问题’ - 情感积极 输入‘服务很差等了两个小时没人理。’ - 情感消极 输入‘明天下午三点开会。’ - 情感中性 现在请分类 输入‘代码运行效率出乎意料地高。’ - 情感[这里应该是模型输出]”预期结果模型输出“积极”。判断成功模型正确识别了隐含的积极情感。测试 3复杂任务链式思考Chain-of-Thought目的让模型展示推理过程提高复杂问题回答的准确性。输入“请一步步思考并解答一个篮子里有12个苹果。小明拿走了三分之一小红又拿走了剩下苹果的一半。请问篮子里还剩几个苹果请先写出思考步骤再给出最终答案。”预期结果回复应展示“12 * (1 - 1/3) 8; 8 / 2 4; 答案4个”这样的推理链。判断成功推理步骤清晰最终答案正确。5.2 Spring AI 集成测试多模型与流式响应测试 1切换不同模型提供商目的验证 Spring AI 的抽象层是否有效能否通过修改配置轻松切换模型。操作在application.yml中将spring.ai.openai配置注释启用spring.ai.anthropic或spring.ai.ollama的配置需先添加对应 starter 依赖。预期结果应用重启后调用/ai/chat接口请求应被路由到新的模型提供商并返回响应。常见问题API Key 或 Base URL 配置错误依赖未添加模型名称不支持。测试 2流式响应Server-Sent Events目的测试处理长文本时的用户体验实现打字机效果。代码示例GetMapping(value “/ai/chat/stream”, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }验证使用浏览器或curl访问该端点应该看到数据分块返回。curl -N http://localhost:8080/ai/chat/stream?message讲一个简短的故事。5.3 RAGFlow 功能测试知识库问答这是整个应用的核心价值所在。我们测试 RAGFlow 的文档处理和问答能力。测试 1文档上传与解析目的验证 RAGFlow 能否正确解析上传的文档并提取文本。操作登录 RAGFlow WebUI (http://localhost:9380)。创建知识库例如“测试产品手册”。上传一份 PDF 或 Word 格式的产品说明书或技术文档。在“文档”页面查看解析状态等待状态变为“已解析”。判断成功文档状态为“已解析”并且可以点击“预览”看到提取出的纯文本内容分块合理。测试 2基于知识库的问答目的验证 RAGFlow 能否根据上传的文档内容准确回答问题。操作在 RAGFlow 的“问答”页面选择刚才创建的知识库。输入一个明确基于文档内容的问题。例如如果上传了 Spring Boot 文档可以问“SpringBootApplication 注解的作用是什么”查看回复。预期结果回复应直接引用或总结文档中的相关内容而不是通用知识。判断成功答案准确且通常会在回复中附带引用来源文档片段证明检索增强生成生效。测试 3通过 API 调用问答目的验证如何通过编程方式与 RAGFlow 交互这是与 Spring AI 应用整合的关键。使用 curl 测试# 1. 获取认证 Token (假设账号密码为 admin/ragflow123) curl -X POST http://localhost:9380/api/v1/token \ -H “Content-Type: application/json” \ -d ‘{“username”: “admin”, “password”: “ragflow123”}’ # 响应中提取 access_token # 2. 使用 Token 进行问答 curl -X POST http://localhost:9380/api/v1/chat/completions \ -H “Content-Type: application/json” \ -H “Authorization: Bearer YOUR_ACCESS_TOKEN” \ -d ‘{ “model”: “your_llm_model_name”, “messages”: [{“role”: “user”, “content”: “SpringBootApplication 注解的作用是什么”}], “knowledge_base_id”: “YOUR_KB_ID” }’预期结果返回一个 JSON包含choices[0].message.content字段其中是答案。判断成功API 返回 HTTP 200且答案内容与 WebUI 问答结果一致。6. 接口 API 与批量任务现在我们将 Spring AI 应用与 RAGFlow 服务连接起来构建一个统一的 AI 应用后端并实现批量处理能力。6.1 集成 RAGFlow API 到 Spring AI 应用我们将创建一个服务将用户问题发送给 RAGFlow再将 RAGFlow 返回的“增强后的上下文”交给 Spring AI 的 ChatClient 生成最终答案。步骤 1创建 RAGFlow 服务客户端package com.example.aidemo.service; import lombok.Data; import org.springframework.beans.factory.annotation.Value; import org.springframework.http.*; import org.springframework.stereotype.Service; import org.springframework.web.client.RestTemplate; import java.util.List; import java.util.Map; Service public class RagFlowService { Value(“${ragflow.base-url}”) private String baseUrl; Value(“${ragflow.api-key}”) private String apiKey; private final RestTemplate restTemplate new RestTemplate(); public String chatWithKnowledgeBase(String question, String knowledgeBaseId) { String url baseUrl “/api/v1/chat/completions”; HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.setBearerAuth(apiKey); // 使用 API Key 认证 // 构建请求体 MapString, Object requestBody Map.of( “model”, “gpt-3.5-turbo”, // 这里使用 RAGFlow 配置的模型名 “messages”, List.of(Map.of(“role”, “user”, “content”, question)), “knowledge_base_id”, knowledgeBaseId, “stream”, false ); HttpEntityMapString, Object request new HttpEntity(requestBody, headers); ResponseEntityMap response restTemplate.postForEntity(url, request, Map.class); if (response.getStatusCode() HttpStatus.OK response.getBody() ! null) { // 解析嵌套的 JSON 结构获取回复内容 ListMap choices (ListMap) response.getBody().get(“choices”); if (choices ! null !choices.isEmpty()) { Map message (Map) choices.get(0).get(“message”); return (String) message.get(“content”); } } return “抱歉从知识库获取答案时出错。”; } }步骤 2创建整合接口package com.example.aidemo.controller; import com.example.aidemo.service.RagFlowService; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.*; import lombok.RequiredArgsConstructor; RestController RequestMapping(“/api/rag”) RequiredArgsConstructor public class RagController { private final RagFlowService ragFlowService; private final ChatClient chatClient; PostMapping(“/query”) public String queryKnowledgeBase(RequestBody QueryRequest request) { // 1. 从 RAGFlow 获取基于知识库的答案 String ragAnswer ragFlowService.chatWithKnowledgeBase(request.getQuestion(), request.getKbId()); // 2. 将 RAG 答案作为上下文让 Spring AI 进行润色或总结可选 // 这里也可以直接将 ragAnswer 返回给前端 String finalAnswer chatClient.prompt() .system(“你是一个助手请根据提供的参考信息用清晰、友好的语言回答用户问题。如果信息不足请如实说明。”) .user(u - u.text(“用户问题{question}\n\n参考信息{context}”) .param(“question”, request.getQuestion()) .param(“context”, ragAnswer)) .call() .content(); return finalAnswer; } Data public static class QueryRequest { private String question; private String kbId; // 知识库 ID } }这个接口实现了简单的“检索-生成”管道。你可以根据需求调整 Prompt例如让 AI 判断 RAG 返回的答案是否充分或进行格式转换。6.2 批量任务处理在实际应用中我们经常需要处理批量文档或批量问题。场景 1使用 Spring AI 的BatchClient批量处理 Prompt如果你的任务是向同一个模型发送大量独立的 Prompt例如为一批商品生成描述可以使用BatchClient提高效率。import org.springframework.ai.chat.client.BatchClient; // ... 注入 BatchClient public ListString batchGenerateDescriptions(ListString productNames) { ListPrompt prompts productNames.stream() .map(name - new Prompt(“为以下产品生成一段吸引人的电商描述” name)) .toList(); BatchResults batchResults batchClient.execute(prompts); // 处理批量结果 return batchResults.getResults().stream() .map(result - result.getOutput().getContent()) .toList(); }注意BatchClient的行为取决于底层模型提供商可能并行也可能串行。场景 2批量上传文档到 RAGFlowRAGFlow 的 API 支持文档上传。我们可以编写一个脚本或服务端点来遍历目录批量上传。// 伪代码展示思路 public void batchUploadToRagFlow(Path directoryPath, String kbId) throws IOException { try (StreamPath paths Files.walk(directoryPath)) { paths.filter(Files::isRegularFile) .filter(path - isSupportedFormat(path)) // 检查 pdf, docx, txt 等 .forEach(file - { // 构造 multipart/form-data 请求 // 调用 RAGFlow 的文档上传 API (/api/v1/knowledge_base/{kb_id}/document/upload) // 处理响应 }); } }场景 3批量问答与结果导出对于已知的问题列表可以循环调用上面实现的/api/rag/query接口并将结果保存到文件或数据库。Async // 可以使用异步提高吞吐 public void batchQaAndExport(ListQaPair questions, String kbId, Path outputPath) { ListString answers new ArrayList(); for (QaPair qa : questions) { String answer ragFlowService.chatWithKnowledgeBase(qa.getQuestion(), kbId); answers.add(“Q: ” qa.getQuestion() “\nA: ” answer “\n---\n”); // 可选添加延迟避免对 API 造成过大压力 Thread.sleep(200); } Files.write(outputPath, answers, StandardCharsets.UTF_8); }最佳实践批量任务务必加入错误处理、重试机制和日志记录并注意控制请求频率避免压垮服务。7. 资源占用与性能观察将多个服务部署在一起了解资源消耗至关重要。1. Docker 容器资源监控使用docker stats命令实时查看各容器的 CPU、内存、网络 I/O 使用情况。docker stats重点关注ragflow-server(后端服务)、milvus(向量数据库) 和你的spring-boot-app容器。2. 显存占用观察如果使用本地 GPU 模型如果 RAGFlow 配置了本地 Embedding 模型如bge-large-zh使用nvidia-smi命令查看 GPU 显存占用。watch -n 1 nvidia-smi在文档解析向量化阶段显存占用会显著上升。问答阶段如果使用本地 LLM显存占用也会持续较高。3. Spring Boot 应用性能启动时间观察应用启动时间如果引入 Spring AI 和大量依赖后启动变慢考虑使用 Spring Boot 的懒加载或分层打包。API 响应时间使用curl的-w参数或浏览器开发者工具测量/api/rag/query接口的端到端延迟。延迟主要来自RAGFlow 检索时间与知识库大小、切片策略相关。LLM API 调用或本地推理时间。JVM 内存使用jconsole、jvisualvm或arthas监控 Spring Boot 应用的堆内存使用情况。4. 优化建议RAGFlow 调优在 RAGFlow 设置中调整文本分块chunk大小和重叠overlap参数。较小的 chunk 可能检索更精准但会增大向量索引大小和检索开销。模型选择在效果和速度间权衡。对于 Embeddingbge-small-zh比bge-large-zh更快更省资源。对于 LLMAPI 调用通常比本地小模型快但依赖网络且有成本。缓存对于频繁出现的相同或相似问题可以在 Spring Boot 应用层引入缓存如 Caffeine直接返回缓存结果避免重复检索和生成。异步处理对于耗时的批量上传或生成任务使用Async或消息队列如 RabbitMQ异步处理避免阻塞 HTTP 请求线程。8. 常见问题与排查方法在部署和运行过程中你可能会遇到以下问题。这里提供排查思路。问题现象可能原因排查方式解决方案RAGFlow Docker 启动失败端口冲突、内存不足、镜像拉取失败、docker-compose版本不兼容。1.docker compose logs查看具体错误日志。2.netstat -tulnp | grep :9380检查端口占用。3.docker compose config检查配置文件。1. 修改docker-compose.yml中的端口映射。2. 增加 Docker 内存分配在 Docker Desktop 设置中。3. 使用docker compose down -v清理旧卷后重试。RAGFlow WebUI 无法访问 (502 Bad Gateway)后端服务 (ragflow-server) 未成功启动或依赖服务Milvus, PostgreSQL未就绪。1.docker compose ps查看所有服务状态。2.docker logs ragflow-server重点查看后端日志。1. 等待所有服务启动完成可能需要几分钟。2. 检查日志中的数据库连接错误确保 PostgreSQL 和 Milvus 健康。Spring Boot 应用启动报错提示IllegalArgumentExceptionSpring AI 版本与 Spring Boot 版本不兼容。检查pom.xml中spring-ai-bom和spring-boot-dependencies的版本。确保使用兼容的版本组合。参考 Spring AI 官方文档的版本说明。调用/ai/chat接口返回 500 错误模型 API 配置错误如错误的 API Key、Base URL、网络不通。1. 检查application.yml配置。2. 查看 Spring Boot 应用日志中的详细异常堆栈。3. 尝试用curl直接调用模型提供商 API 测试连通性。1. 确认 API Key 有效且有余额。2. 如果是国内环境调用 OpenAI可能需要配置代理或使用国内镜像站。RAGFlow API 调用返回 401 未授权API Key 错误或未设置Token 过期。1. 检查代码中Authorization头是否正确设置。2. 登录 RAGFlow WebUI在用户设置中确认 API Key。1. 使用正确的 API Key。2. 如果使用账号密码获取 Token注意 Token 有效期实现自动刷新逻辑。知识库问答答案质量差答非所问1. 文档解析失败文本提取不全。2. 分块策略不合理上下文断裂。3. 检索到的相关片段太少或不准。4. LLM 的 Prompt 指令不佳。1. 在 RAGFlow WebUI 预览文档解析结果。2. 调整知识库的分块大小和重叠参数。3. 测试不同的 Embedding 模型。4. 优化发送给 LLM 的 Prompt明确指令其“基于以下上下文回答”。1. 确保上传文档格式标准、清晰。2. 尝试不同的分块设置如 500 字符100 字符重叠。3. 在 RAGFlow 中尝试不同的检索器如混合搜索。4. 在 Prompt 中强化“仅根据上下文回答”的指令。批量处理时速度慢或进程卡住1. 同步调用导致线程阻塞。2. 模型 API 有速率限制。3. 本地资源CPU/内存/显存耗尽。1. 监控应用和 Docker 容器资源使用率。2. 查看日志中是否有超时或限流错误。1. 将批量任务改为异步执行。2. 在批量请求间添加间隔如 200-500ms。3. 考虑使用更轻量的模型或升级硬件。Docker 容器内应用无法访问宿主机服务网络配置问题。在容器内localhost指向容器自身。在容器内使用curl测试连通性。在 Spring Boot 配置中将ragflow.base-url从localhost:9380改为宿主机的 IP 地址或使用 Docker 的host.docker.internal(Mac/Windows) 或172.17.0.1(Linux) 作为主机名。9. 最佳实践与使用建议基于以上流程总结一些让项目更稳健、更高效的建议。1. 环境隔离与配置管理使用 Docker Compose将 RAGFlow 及其依赖数据库、向量库定义在docker-compose.yml中实现一键启停和环境复制。配置外部化Spring Boot 应用的敏感配置如 API Key务必通过环境变量或配置中心管理不要硬编码在application.yml中。可以使用Value(“${KEY:default}”)配合环境变量。版本锁定在pom.xml和docker-compose.yml中固定关键依赖的版本号避免自动升级导致的不兼容。2. 应用架构与代码组织分层清晰遵循 Controller - Service - Client/Repository 的分层模式。将调用 RAGFlow API 的代码封装在独立的Service或Client类中。异常处理对 RAGFlow API 调用、模型 API 调用做好统一的异常处理和降级策略如返回友好提示或切换备用模型。连接池与超时配置RestTemplate或WebClient的连接池、读超时和连接超时防止慢请求拖垮整个应用。3. Prompt 工程与 RAG 优化Prompt 模板化将常用的 Prompt 结构如角色设定、输出格式定义为模板存储在数据库或配置文件中便于管理和 A/B 测试。RAG 参数实验知识库的chunk_size和chunk_overlap对效果影响巨大。针对你的文档类型技术文档、长文章、QA对进行多组参数测试选择最佳组合。检索结果后处理在将检索到的文本片段交给 LLM 前可以进行去重、排序、长度裁剪等后处理提升上下文质量。4. 安全与合规API 访问控制为 Spring Boot 应用和 RAGFlow 的 API 设置访问权限。Spring Boot 可以使用 Spring Security。RAGFlow 务必使用强密码和 API Key。输入输出审查对用户输入进行必要的过滤和审查防止 Prompt 注入攻击。对 AI 生成的内容在涉及事实、数据、建议时应添加免责声明并建议用户复核。数据生命周期管理定期清理 RAGFlow 中测试用的、临时的知识库和文档。制定线上知识库的更新和归档策略。5. 监控与日志关键指标监控监控 API 的响应时间、成功率、RAGFlow 容器的资源使用率。结构化日志在 Spring Boot 应用中使用 SLF4J 记录结构化的日志如 JSON 格式方便通过 ELK 等工具进行分析。记录每次问答的请求参数、检索到的文档 ID、生成耗时等便于效果分析和问题追踪。10. 总结与下一步通过这次从零到一的实践我们串联起了现代 AI 应用开发的几个关键环节用Prompt 工程精准控制模型行为用Spring AI简化模型集成用RAGFlow构建知识大脑最后用Docker完成标准化部署。这套组合拳的优势在于它基于成熟的、活跃的开源项目降低了从想法到可运行原型的技术门槛。最值得尝试的点快速验证想法你可以在几个小时内就为一个垂直领域如法律、医疗、客服搭建一个具备私有知识问答能力的 Demo。技术栈友好对于 Java 开发者Spring AI 提供了极其平滑的接入体验无需深入 Python 生态。部署标准化Docker Compose 让整个复杂系统的部署和迁移变得异常简单。最先应该验证的功能 建议你首先复现5.3 节“RAGFlow 功能测试”。找一份你熟悉领域的技术文档比如公司内部 Wiki 或产品手册上传到 RAGFlow然后问几个具体、细节的问题。当你看到 AI 能准确引用文档内容回答时你会立刻感受到 RAG 技术的价值。最容易踩的坑环境问题Docker 启动失败、端口冲突、内存不足。务必先确保 Docker 环境本身健康。配置错误Spring AI 或 RAGFlow 的 API Key、Base URL 配置错误。养成通过日志和简单curl命令逐层调试的习惯。效果调优直接使用默认参数效果不佳。需要花时间调整文档分块策略和 Prompt 指令这是获得好效果的必要步骤。后续可以继续扩展的方向前端界面为这个 Spring Boot 后端开发一个简单的前端如 Vue/React打造一个完整的问答应用。多路召回与重排序在 RAGFlow 或自己实现的服务中尝试结合关键词检索和向量检索并对召回结果进行重排序进一步提升准确率。Agent 能力利用 Spring AI 的 Function Calling 或新推出的 Agent 模块让 AI 不仅能问答还能执行工具调用如查询数据库、发送邮件实现更复杂的自动化流程。生产化部署考虑将 Spring Boot 应用也容器化使用 Docker Compose 或 Kubernetes 统一管理所有服务并配置 Nginx 反向代理、SSL 证书等。这套流程是一个强大的起点。它提供的不是黑盒产品而是一套可完全掌控、可深度定制、可集成到现有系统的技术方案。建议收藏本文在搭建过程中遇到具体问题时再回来查阅对应的排查章节。