这次我们来看一个完整的 AI 应用开发实战项目。它不是一个单一的模型而是一个从提示词工程、后端开发到知识库部署的端到端流程。核心是结合Prompt 工程、Spring AI框架和RAGFlow知识库通过Docker完成本地化部署。如果你正在寻找一个能跑在本地、能处理私有文档、并且能通过 API 调用的 AI 应用构建方案这篇文章可以直接收藏。简单来说这个流程能帮你解决几个关键问题如何用 Spring AI 快速接入大模型能力如何用 RAGFlow 构建一个基于私有文档的智能知识库以及如何将这两者通过 Docker 组合成一个可复用的服务。整个过程不依赖特定的云服务可以在你自己的开发机或服务器上完成适合需要数据隐私和定制化开发的场景。本文会带你走通三个核心环节首先是Prompt 工程的基础与调优这是所有 AI 应用效果的起点然后是使用Spring AI框架搭建一个能调用大模型如 OpenAI、Ollama 本地模型的后端服务最后通过Docker部署RAGFlow将其作为私有知识库引擎并与 Spring AI 服务集成实现基于文档的问答RAG。我们会重点关注每一步的环境准备、关键配置、接口调用和常见问题排查。1. 核心能力速览能力项说明项目类型端到端 AI 应用开发与部署流程技术栈Prompt 工程 Spring AI (Java) RAGFlow (Python/Docker)核心功能1. 基于 Spring AI 的模型调用与 Prompt 管理2. 基于 RAGFlow 的私有知识库构建与检索3. 通过 Docker 实现服务化、可移植部署硬件门槛开发环境普通 PC/Mac 即可内存建议 8GB。RAGFlow 部署依赖 Docker运行需要一定内存和磁盘空间用于向量数据库和模型。CPU 推理可行GPU 可加速。启动方式Spring AI 应用通过 IDE 或mvn spring-boot:run启动。RAGFlow通过 Docker Compose 一键启动。接口能力Spring AI 提供 RESTful API 用于对话和复杂 Prompt 调用。RAGFlow 提供 API 用于文档上传、知识库管理和问答检索。批量任务Spring AI 支持异步处理批量 Prompt 任务。RAGFlow 支持批量文档上传与解析。适合场景企业内部知识库问答、私有数据智能助手、AI 应用原型快速开发、需要本地化部署的 RAG 场景。2. 适用场景与使用边界这个组合方案非常适合以下几类开发者或团队企业级应用开发者需要在 Java 技术栈Spring Boot中快速集成 AI 能力同时要求数据完全私有不出内网。全栈工程师/个人开发者希望从零构建一个功能完整的 AI 应用涵盖从后端逻辑、Prompt 设计到知识库检索的全链路。有私有文档处理需求的团队拥有大量内部文档如产品手册、技术规范、会议纪要需要构建一个能准确回答相关问题的智能助手。学习 AI 应用落地的学生或研究者通过一个具体的项目理解 Prompt Engineering、RAG 架构和微服务部署的实践结合。使用边界与注意事项数据安全与隐私虽然部署在本地但需确保上传至 RAGFlow 的文档已获得合法授权不包含敏感个人信息或商业秘密除非在安全环境内。RAGFlow 的向量化模型和 Embedding 服务也应部署在可控环境中。模型依赖Spring AI 本身是框架需要后端连接具体的大模型服务如 OpenAI API、Azure OpenAI、Ollama 本地模型。使用云端 API 会产生费用并涉及网络调用使用本地模型如通过 Ollama则对计算资源有要求。知识库效果RAGFlow 的问答效果严重依赖于文档解析质量、分块策略和检索相关性。对于格式复杂或专业性极强的文档需要调整解析参数和 Prompt 才能达到理想效果。性能与扩展本地 Docker 部署的 RAGFlow在处理海量文档或高并发查询时可能遇到性能瓶颈。生产环境需要考虑分布式部署、负载均衡和缓存策略。版权合规确保使用的基座模型如通过 Spring AI 调用和 Embedding 模型符合其许可协议。用于商业用途时需仔细核对。3. 环境准备与前置条件在开始编码和部署之前请确保你的开发环境满足以下要求。我们将环境分为Spring AI 开发环境和RAGFlow 部署环境两部分。3.1 Spring AI 开发环境这是构建 AI 应用后端的部分。操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04)。Java 开发套件 (JDK)版本17 或 21Spring Boot 3.x 的要求。推荐使用 OpenJDK 发行版如 Temurin。# 检查 Java 版本 java -version构建工具Apache Maven 3.6或Gradle。本文以 Maven 为例。# 检查 Maven 版本 mvn -v集成开发环境 (IDE)推荐 IntelliJ IDEA (社区版或旗舰版)、VS Code 或 Eclipse。确保安装了 Spring Boot 和 Maven 相关插件。模型访问凭证二选一方案A使用云端 API准备一个可用的OpenAI API Key或Azure OpenAI端点及密钥。方案B使用本地模型安装Ollama并拉取一个本地模型如llama3.2、qwen2.5:7b或deepseek-coder。# 安装 Ollama (Linux/macOS) curl -fsSL https://ollama.com/install.sh | sh # 拉取模型 ollama pull llama3.23.2 RAGFlow 部署环境这是构建知识库服务的部分通过 Docker 运行。操作系统支持 Docker 的 Linux、macOS 或 Windows。Docker 与 Docker Compose这是必须的。确保 Docker 守护进程正在运行。Docker Desktop适用于 Windows 和 macOS 用户它包含了 Docker Engine 和 Docker Compose。Linux需要分别安装 Docker Engine 和 Docker Compose 插件。# 检查 Docker 和 Docker Compose 版本 docker --version docker compose version硬件资源内存建议至少8GB可用内存。RAGFlow 的 Docker 容器会运行多个服务包括向量数据库如 Milvus和 Embedding 模型。磁盘空间预留10GB以上空间用于存储 Docker 镜像、向量数据和上传的文档。网络需要从 Docker Hub 拉取镜像确保网络通畅。如果需要 GPU 加速 Embedding 或 Rerank 模型需安装 NVIDIA Container Toolkit。端口占用检查RAGFlow 默认会占用多个端口如 80, 443, 3000等。确保这些端口在宿主机上未被其他应用占用或准备好修改 Docker Compose 配置。4. 安装部署与启动方式我们将按照先部署 RAGFlow 知识库再开发 Spring AI 应用的顺序进行因为 Spring AI 应用需要调用 RAGFlow 的 API。4.1 RAGFlow 的 Docker 部署与启动RAGFlow 提供了官方的 Docker Compose 文件可以一键启动所有依赖服务。获取部署文件 访问 RAGFlow 的 GitHub 仓库或官方文档找到最新的docker-compose.yml文件。通常可以通过以下命令获取# 创建一个项目目录 mkdir ragflow-deploy cd ragflow-deploy # 下载 docker-compose.yml 文件 (请以官方最新地址为准) curl -o docker-compose.yml https://raw.githubusercontent.com/infiniflow/ragflow/main/docker/docker-compose.yml注意上述 URL 仅为示例请务必从 RAGFlow 官方渠道获取正确的文件。可选配置环境变量查看docker-compose.yml同目录下是否有.env文件或类似配置。你可能需要配置RAGFLOW_SERVER_PORT服务端口。数据库密码、向量数据库配置等。如果需要使用特定的 Embedding 模型如bge-large-zh也可能需要在此配置。启动 RAGFlow 服务 在包含docker-compose.yml的目录下执行docker compose up -d这个命令会拉取所有必要的镜像包括 RAGFlow 前端、后端、Milvus 向量数据库、MySQL 等并在后台启动它们。首次运行需要下载镜像时间取决于网络速度。验证服务状态# 查看容器运行状态 docker compose ps # 查看日志确认服务启动无误 docker compose logs -f ragflow-server当看到日志中出现服务启动成功的提示如Started Application in XX seconds后即可进行下一步。访问 Web UI 并初始化 打开浏览器访问http://localhost:80默认端口。首次访问需要注册一个管理员账号并登录。登录后你可以看到 RAGFlow 的管理界面在这里可以创建知识库、上传文档、配置解析器等。4.2 Spring AI 应用创建与启动我们将创建一个全新的 Spring Boot 项目来集成 Spring AI。创建 Spring Boot 项目 使用 Spring Initializr 或 IDE 的创建向导。Project: MavenLanguage: JavaSpring Boot: 3.2.x 或更高Group Artifact: 自定义如com.example和ai-demoDependencies: 添加Spring Web和Spring AI在 Initializr 上可以直接搜索并添加 “Spring AI” 依赖。如果找不到需要手动在pom.xml中添加。配置pom.xml 确保pom.xml中包含 Spring AI 的 BOM物料清单和对应模型的 Starter。以下是一个连接 OpenAI 的示例配置?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 modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version !-- 使用最新稳定版 -- relativePath/ /parent groupIdcom.example/groupId artifactIdai-demo/artifactId version0.0.1-SNAPSHOT/version nameai-demo/name descriptionDemo project for Spring AI/description properties java.version17/java.version spring-ai.version0.8.1/spring-ai.version !-- 使用最新版本 -- /properties dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI OpenAI Starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency !-- 用于测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project如果使用 Ollama 本地模型则需要添加spring-ai-ollama-spring-boot-starter依赖。配置应用属性 在src/main/resources/application.properties或application.yml中配置模型连接。连接 OpenAI:# application.properties spring.ai.openai.api-key${OPENAI_API_KEY} spring.ai.openai.chat.options.modelgpt-3.5-turbo # 可选设置代理如果需要 # spring.ai.openai.base-urlhttps://api.openai.com/v1连接 Ollama:# application.properties spring.ai.ollama.base-urlhttp://localhost:11434 spring.ai.ollama.chat.options.modelllama3.2配置 RAGFlow API 地址后续集成用:ragflow.api.base-urlhttp://localhost:80/api/v1 ragflow.api.tokenYOUR_RAGFLOW_API_TOKEN # 需要在 RAGFlow 后台创建启动 Spring Boot 应用# 在项目根目录下 mvn spring-boot:run或者直接在 IDE 中运行主类AiDemoApplication。看到Started AiDemoApplication in X.XXX seconds日志即表示启动成功。5. 功能测试与效果验证现在我们分别对 Spring AI 的基础对话、Prompt 工程以及 RAGFlow 的知识库功能进行测试。5.1 Spring AI 基础对话测试首先验证 Spring AI 是否能成功调用大模型。创建测试 Controller 在项目中创建一个DemoController.java。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 DemoController { private final ChatClient chatClient; // 通过构造器注入 ChatClient public DemoController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/chat) public String chat(RequestParam(value message, defaultValue Hello) String message) { return chatClient.prompt() .user(message) .call() .content(); } }发起测试请求 启动应用后使用浏览器或curl命令测试。curl http://localhost:8080/chat?message用Java写一个Hello World程序预期结果返回一个格式良好的 JavaHelloWorld代码片段。成功判断收到非空的、与问题相关的文本响应且没有抛出异常如连接超时、认证失败。常见失败原因401 UnauthorizedAPI Key 配置错误或无效。Connection refusedOllama 服务未启动localhost:11434。响应慢或超时网络问题或模型首次加载。5.2 Prompt 工程实践与测试Prompt 工程是提升模型输出质量的关键。Spring AI 提供了强大的 Prompt 模板功能。创建复杂 Prompt 模板 假设我们需要一个代码审查助手。在resources目录下创建prompts/code-review.st文件。### 角色 你是一位资深的{language}开发专家擅长代码审查。 ### 任务 请审查以下{language}代码并提供改进建议。 ### 代码 {code} ### 审查要求 1. 指出潜在的性能问题。 2. 检查代码风格是否符合{styleGuide}规范。 3. 提出重构建议如果有。 4. 输出格式请使用Markdown。 ### 输出创建使用 Prompt 模板的 Servicepackage com.example.aidemo.service; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.prompt.PromptTemplate; import org.springframework.core.io.Resource; import org.springframework.core.io.ResourceLoader; import org.springframework.stereotype.Service; import java.util.Map; Service public class CodeReviewService { private final ChatClient chatClient; private final ResourceLoader resourceLoader; public CodeReviewService(ChatClient.Builder builder, ResourceLoader resourceLoader) { this.chatClient builder.build(); this.resourceLoader resourceLoader; } public String reviewCode(String language, String code, String styleGuide) { // 加载 Prompt 模板文件 Resource resource resourceLoader.getResource(classpath:prompts/code-review.st); PromptTemplate promptTemplate new PromptTemplate(resource); // 渲染模板填充变量 Prompt prompt promptTemplate.create(Map.of( language, language, code, code, styleGuide, styleGuide )); // 调用模型 ChatResponse response chatClient.prompt(prompt).call().chatResponse(); return response.getResult().getOutput().getContent(); } }测试 Prompt 模板 创建一个对应的 Controller 端点进行测试。PostMapping(/review) public String review(RequestBody CodeReviewRequest request) { return codeReviewService.reviewCode(request.language(), request.code(), request.styleGuide()); } // 请求体记录 record CodeReviewRequest(String language, String code, String styleGuide) {}使用 Postman 或curl发送一个包含 Java 代码的 POST 请求。预期结果返回一份结构化的 Markdown 格式代码审查报告。成功判断报告内容针对输入的代码并涵盖了性能、风格和重构建议。调优方向如果结果不理想可以修改 Prompt 模板例如更清晰地定义“性能问题”或提供更具体的代码风格示例。5.3 RAGFlow 知识库功能测试在 Spring AI 应用调用 RAGFlow 之前先在 RAGFlow 的 Web UI 中完成知识库的创建和测试。创建知识库登录 RAGFlow Web UI (http://localhost:80)。点击“知识库” - “新建知识库”。输入知识库名称如MyTechDocs选择适当的 Embedding 模型如bge-large-zh-v1.5和向量数据库默认 Milvus。配置解析器根据文档类型PDF、Word、PPT、TXT选择合适的解析器并调整分块Chunk大小和重叠Overlap参数。例如对于技术文档分块大小 512 字重叠 50 字可能是个不错的起点。上传文档并解析在创建好的知识库中点击“上传文档”。选择本地文件如一份产品说明书 PDF进行上传。上传后RAGFlow 会自动进行文本提取、分块、向量化并存入向量数据库。在“文档”列表中可以查看解析状态和结果预览。在 Web UI 中进行问答测试进入知识库的“对话”或“测试”页面。输入一个基于上传文档内容的问题例如“这款产品的主要特性是什么”预期结果RAGFlow 会返回一个答案并且答案旁边会显示引用的文档片段来源。成功判断答案准确、相关并且引用的来源确实包含了答案信息。效果不佳排查答案不相关调整检索的“相似度阈值”或“Top K”返回数量。答案不完整检查文档解析是否成功分块是否过于细碎考虑调整分块大小或使用“语义分块”模式。答案未引用来源检查向量检索是否正常确认 Embedding 模型是否适合该语种文档。6. 接口 API 与批量任务完成基础功能验证后我们需要让 Spring AI 应用能够通过 API 与 RAGFlow 交互并处理批量任务。6.1 Spring AI 调用 RAGFlow APIRAGFlow 提供了完整的 REST API 供外部系统调用。我们需要在 Spring AI 应用中集成这个客户端。获取 RAGFlow API Token 在 RAGFlow Web UI 中进入“设置”或“API 管理”页面创建一个新的 API Token并妥善保存。创建 RAGFlow 客户端 Servicepackage com.example.aidemo.service; 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.HashMap; import java.util.Map; Service public class RagFlowService { Value(${ragflow.api.base-url}) private String baseUrl; Value(${ragflow.api.token}) private String apiToken; private final RestTemplate restTemplate new RestTemplate(); public String chatWithKnowledge(String kbName, String question) { String url baseUrl /chat/completions; // RAGFlow 的聊天接口路径请查阅官方API文档确认 HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.setBearerAuth(apiToken); // 或 headers.set(Authorization, Bearer apiToken); MapString, Object requestBody new HashMap(); requestBody.put(kb_name, kbName); requestBody.put(query, question); // 可能还有其他参数如 stream, history 等 requestBody.put(stream, false); HttpEntityMapString, Object request new HttpEntity(requestBody, headers); ResponseEntityMap response restTemplate.exchange(url, HttpMethod.POST, request, Map.class); // 解析响应提取答案。实际结构需参考 RAGFlow API 文档。 MapString, Object body response.getBody(); if (body ! null body.containsKey(answer)) { return (String) body.get(answer); } else { throw new RuntimeException(Failed to get answer from RAGFlow: body); } } }重要上述代码中的 API 路径和请求/响应结构仅为示例务必查阅你所用版本的 RAGFlow 官方 API 文档进行修正。创建融合 Prompt 的增强接口 现在我们可以创建一个 Controller它先调用 RAGFlow 获取知识库答案再将答案作为上下文通过 Spring AI 的 Prompt 工程生成更友好或更专业的最终回复。GetMapping(/ask) public String askKb(RequestParam String question) { // 1. 从 RAGFlow 获取基于知识的答案 String knowledgeAnswer ragFlowService.chatWithKnowledge(MyTechDocs, question); // 2. 构建增强 Prompt将知识答案作为上下文 String enhancedPrompt String.format( 基于以下已知信息请以专业、清晰的方式回答用户的问题。 如果已知信息不足以回答问题请直接说明“根据已知信息无法回答该问题”。 ### 已知信息 %s ### 用户问题 %s ### 回答 , knowledgeAnswer, question); // 3. 调用大模型生成最终回答 return chatClient.prompt() .user(enhancedPrompt) .call() .content(); }6.2 批量任务处理在实际应用中我们经常需要处理批量文档或批量问题。RAGFlow 批量文档上传 RAGFlow 的 API 通常支持批量上传文档。你可以编写一个脚本遍历本地目录调用 RAGFlow 的文件上传接口。注意处理上传状态和失败重试。// 伪代码示例 public void batchUploadDocuments(Path directoryPath, String kbName) { try (StreamPath paths Files.walk(directoryPath)) { paths.filter(Files::isRegularFile) .filter(path - isSupportedFormat(path)) // 检查文件格式 .forEach(file - { try { uploadSingleFileToRagFlow(file, kbName); // 添加延迟避免请求过快 Thread.sleep(500); } catch (Exception e) { log.error(Failed to upload file: file, e); // 记录失败文件后续重试 } }); } catch (IOException e) { log.error(Error walking through directory, e); } }Spring AI 异步批量问答 对于大量用户问题可以使用 Spring 的Async注解实现异步处理提升吞吐量。Service public class BatchQAService { Async // 需要配置线程池 public CompletableFutureString processQuestionAsync(String question) { String answer askKb(question); // 调用上面定义的 /ask 逻辑 return CompletableFuture.completedFuture(answer); } } // 在 Controller 中批量调用 PostMapping(/batch-ask) public ListString batchAsk(RequestBody ListString questions) { ListCompletableFutureString futures questions.stream() .map(batchQAService::processQuestionAsync) .collect(Collectors.toList()); // 等待所有任务完成 CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join(); return futures.stream() .map(CompletableFuture::join) .collect(Collectors.toList()); }注意生产环境需要合理配置线程池大小避免资源耗尽。7. 资源占用与性能观察部署和运行这套组合服务需要关注以下几个方面的资源使用情况。RAGFlow Docker 容器资源内存使用docker stats命令观察。刚启动时多个容器server, milvus, mysql等总内存占用可能在 2-4GB。随着文档上传和向量数据增长内存占用会上升尤其是 Milvus 向量数据库。CPU文档解析OCR、文本提取和向量化Embedding是 CPU 密集型操作。批量上传时 CPU 使用率会显著升高。磁盘向量数据和文档原文会持久化在 Docker 卷中。使用docker system df查看磁盘占用。定期清理测试数据或无用知识库。网络如果 Embedding 模型是从远程拉取非本地部署的模型首次使用时会下载模型文件占用网络带宽。Spring AI 应用资源内存Spring Boot 应用本身内存占用不大几百MB。但如果处理大量并发请求或大篇幅的 PromptJVM 堆内存需要适当调高通过-Xmx参数。CPU/GPUSpring AI 只是一个客户端计算压力在它调用的大模型服务端。如果调用本地 Ollama则需要观察 Ollama 进程的资源占用CPU/GPU显存。性能优化观察点RAGFlow 检索速度首次检索可能较慢因为要加载模型。后续检索速度取决于向量数据库的索引性能和硬件。可以观察 RAGFlow 日志中的检索耗时。Spring AI 调用延迟调用云端 API 受网络延迟影响调用本地 Ollama 受模型加载和计算速度影响。可以使用Timed注解或 Micrometer 监控接口响应时间。批量处理瓶颈文档上传受限于 RAGFlow 的解析能力和网络 I/O。建议控制并发上传数。批量问答受限于大模型服务的并发限制如 OpenAI 的 RPM/TPM或本地 Ollama 的计算能力。需要实现限流和队列机制。8. 常见问题与排查方法在部署和集成过程中你可能会遇到以下问题。问题现象可能原因排查方式解决方案RAGFlow Docker 启动失败1. 端口被占用。2. 内存不足。3. Docker 镜像拉取失败。4..env配置错误。1.docker compose logs查看具体错误日志。2.netstat -tulnp | grep :80检查端口。3.docker compose config检查配置。1. 修改docker-compose.yml中的端口映射。2. 增加系统内存或 Docker 资源限制。3. 检查网络手动docker pull镜像。4. 核对.env文件。RAGFlow Web UI 无法访问1. 服务未成功启动。2. 防火墙/安全组阻止。3. 容器内部错误。1.docker compose ps确认所有容器状态为Up。2. 检查宿主机防火墙规则。3.docker exec -it container_name sh进入容器查看。1. 根据日志修复启动错误后重启。2. 开放对应端口。3. 检查容器内应用日志。文档上传后解析失败1. 文档格式不支持。2. 解析器配置不当。3. 缺少 OCR 依赖对于扫描件。1. 在 RAGFlow UI 查看文档解析状态和错误信息。2. 尝试上传简单的.txt文件测试。1. 确认文档格式在支持列表中。2. 调整解析器参数如分块大小。3. 确保 RAGFlow 部署包含了 OCR 组件。知识库问答返回无关答案1. 检索相似度阈值太低。2. 分块策略不合理。3. Embedding 模型不匹配。1. 在 RAGFlow 测试界面调整“相似度阈值”和“Top K”。2. 查看返回的“来源”片段看是否相关。1. 提高相似度阈值减少返回片段数。2. 重新调整分块大小和重叠或尝试“语义分块”。3. 为中文文档选择中文优化的 Embedding 模型。Spring AI 连接模型失败1. API Key 或 Base URL 错误。2. 网络代理问题。3. Ollama 服务未运行。1. 检查application.properties配置。2. 使用curl直接测试模型 API 端点。3. 检查 Ollama 服务状态ollama list。1. 修正配置信息。2. 为 Spring Boot 应用配置网络代理。3. 启动 Ollama 服务ollama serve。调用 RAGFlow API 返回 401/4031. API Token 错误或过期。2. 请求头未正确设置。1. 在 RAGFlow 后台重新生成 Token。2. 使用 Postman 等工具模拟请求对比请求头。1. 使用正确的 Token。2. 确保在 HTTP 头中正确设置Authorization: Bearer token。批量上传或问答时服务崩溃1. 内存溢出OOM。2. 数据库连接池耗尽。3. 超出模型服务速率限制。1. 查看应用和 Docker 容器日志中的 OOM 错误。2. 监控数据库连接数。3. 查看模型服务返回的错误信息如 429。1. 增加 JVM 堆内存和 Docker 容器内存限制。2. 优化代码及时关闭资源配置连接池。3. 实现请求限流、队列和重试机制。9. 最佳实践与使用建议基于以上流程这里总结一些让项目更稳定、更高效运行的建议。环境隔离与配置管理为开发、测试、生产环境使用不同的配置文件application-dev.properties,application-prod.properties。敏感信息如 API Key、数据库密码务必通过环境变量或配置中心注入不要硬编码在文件中。使用 Docker Compose 的profiles功能来区分不同环境的服务组合。Prompt 工程管理将 Prompt 模板文件化如.st文件便于版本控制和复用。建立 Prompt 测试用例当模型或需求变更时快速验证 Prompt 的有效性。对于复杂的系统 Prompt可以将其拆分为多个可组合的部分。RAGFlow 知识库优化文档预处理上传前尽量对文档进行清理如去除页眉页脚、水印格式统一为 PDF 或 Markdown。分块策略不要迷信默认值。对于技术文档尝试按章节或子标题分块对于问答对确保问题和答案在同一分块内。测试驱动上传一批文档后用一组标准问题测试检索效果根据结果迭代调整分块参数和检索参数。定期维护清理测试知识库、过期文档对重要知识库进行备份。应用层设计与监控异步与降级对于耗时操作如文档解析、复杂推理采用异步处理并提供服务降级策略如超时后返回缓存或默认答案。链路追踪在 Spring Boot 应用中集成 Sleuth/Zipkin追踪一个用户请求从进入 Spring AI、调用 RAGFlow 到返回的完整链路便于定位性能瓶颈。健康检查为 Spring Boot 应用和 RAGFlow 服务添加健康检查端点并集成到 Kubernetes 或监控系统中。输入输出校验对用户输入的问题进行长度、内容安全校验对模型输出进行必要的后处理如过滤敏感信息、格式化。安全与合规API 网关与鉴权在生产环境不要将 Spring Boot 或 RAGFlow 的管理接口直接暴露到公网。使用 API 网关如 Spring Cloud Gateway, Nginx进行反向代理并添加身份认证和授权。审计日志记录所有的用户问答请求和答案用于效果分析和合规审计。数据生命周期制定明确的用户数据、对话记录、上传文档的保留和删除策略。这套从 Prompt 工程、Spring AI 开发到 RAGFlow Docker 部署的流程打通了 AI 应用从构思到落地的关键路径。最值得尝试的点在于它提供了一套完全本地化、可掌控的技术方案特别适合对数据隐私有要求或需要深度定制的场景。最先应该验证的功能是 RAGFlow 对私有文档的检索准确性这是整个应用价值的基石。最容易踩的坑集中在环境配置和组件联调上尤其是 Docker 网络、端口以及各服务间的 API 认证。当你成功跑通这个流程后下一步可以探索更复杂的架构例如将 Spring AI 服务容器化、用 Kubernetes 编排整个应用栈、或者集成更多的 AI 能力如语音、图像处理从而构建出更强大的企业级智能应用。