大家好，咱们终于迎来了《Spring AI 实战系列》入门阶段的收官之战！🎉 回顾前两章，我们像是刚刚拿到了一把新式的武器，了解了它的基本构造并试着开了几枪。但是真正的战场从来不是在空旷的靶场，而是在充满了迷雾和复杂信息的真实数据环境中。

这就是为什么第 3 篇如此关键。我们要解决大模型Zui让人头疼的“幻觉”问题，让它不仅Neng“瞎编”，还Neng基于我们企业内部的私有数据“有理有据”地回答。这就是 RAG技术的魅力所在。不过在真正动手写代码之前，hen多同学心里dou打鼓，甚至踩了不少坑。今天我们就把这些疑问摊开来揉碎了讲清楚。

一、为什么我们需要 RAG？——从“开卷考试”说起

在深入代码之前，咱们得先达成一个共识：大语言模型虽然聪明，但它有两个致命的硬伤。

知识过时它的训练数据是有截止日期的，昨天发生的事它一概不知。

私有盲区它不可Neng知道你公司昨天刚发布的《产品内部操作手册》或者你个人的《日记》。

Ru果直接问它，它要么一本正经地胡说八道，要么告诉你“我不知道”。RAG 技术的出现，就是为了给大模型装上一个“外挂大脑”。我们Ke以把这个过程想象成一场开卷考试

考生拥有强大的推理和语言组织Neng力，但没背过课本。

课本包含了所有Zui新的、私有的参考文档。

监考老师kan到题目后先去课本里找到相关的章节，撕下来递给考生，说：“就根据这些内容答题。”

这样一来考生既Neng利用自己的Neng力组织语言，又Neng保证答案的准确性。这就是 RAG 的核心价值：无需重新训练模型，数据实时geng新，隐私安全可控。

二、RAG 的工作流：离线与在线的博弈

hen多初学者容易混淆 RAG 的准备阶段和问答阶段。为了让大家geng直观地理解，我把这个过程拆解为“离线准备”和“在线问答”两个截然不同的阶段。

1. 离线阶段：数据搬运工

在这个阶段，我们的目标是把非结构化的文本变成计算机Neng理解的向量，并存入数据库。这就像是在考前整理资料。

┌─────────────────────────────────────────────────────────────┐
│                    离线数据准备 Pipeline                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  📚 原始文档                                       │
│       ↓                                                     │
│  📖 文档读取器  // 识别文件格式，提取纯文本                   │
│       ↓                                                     │
│  ✂️ 文档分割器  // 把大书切成小段，避免上下文溢出             │
│       ↓                                                     │
│  🧠 Embedding 模型 // 把文本转化为一串数字            │
│       ↓                                                     │
│  💾 向量数据库    // 存储向量，建立索引                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2. 在线阶段：敏捷问答

当用户发起提问时系统需要迅速反应。这个阶段对性Neng要求极高。

┌─────────────────────────────────────────────────────────────┐
│                    在线问答 Query Pipeline                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ❓ 用户提问："如何配置 Spring AI？"                         │
│       ↓                                                     │
│  🧠 Embedding 转换 // 把问题也变成向量                       │
│       ↓                                                     │
│  🔍 向量相似度搜索 // 在数据库里找Zui像的文档片段              │
│       ↓                                                     │
│  📝 提示词构建 // 拼接指令 + 找到的文档 + 用户问题            │
│       ↓                                                     │
│  🤖 大模型生成 // AI 基于参考资料生成Zui终答案                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

三、向量数据库选型：不要为了技术而技术

在 Spring AI 的生态里它屏蔽了底层向量库的差异，提供了统一的 `VectorStore` 接口。但是作为架构师或开发者，你依然需要根据业务场景选择合适的底座。别一上来就上Zui复杂的，适合的才是Zui好的。

数据库类型	核心优势	推荐场景
PGVector	生态成熟，无需引入新组件，支持 ACID 事务。	中小型项目，技术栈Yi包含 PG，不想维护新数据库。
Redis	性Neng极高，基于内存，支持丰富的过滤条件。	对响应速度要求极高的实时推荐、缓存场景。
Chroma / Milvus	开源，专门为向量设计，功Neng纯粹。	本地开发测试，或者需要大规模向量检索的 AI 原生应用。
Elasticsearch	强大的全文检索Neng力，混合搜索强。	Yi有 ES 集群，需要同时支持传统搜索和语义搜索。

选型建议：Ru果你只是想快速跑通 Demo，或者公司里Yi经有 PostgreSQL 了直接用 PGVector 是Zui省心的。Ru果你追求极致性Neng且数据量巨大，再考虑 Milvus 或 Pinecone 这种云原生方案。

四、实战演练：手把手构建文档问答系统

光说不练假把式。接下来我们用 Spring AI 搭建一个简易的 RAG 系统。为了方便演示，我们选用 Ollama 作为本地模型，Chroma 作为向量数据库。

1. 项目结构与依赖配置

在 `pom.xml` 中引入必要的“弹药”。这里我们使用 Spring AI 的 BOM来管理版本，避免版本冲突地狱。

    
        
            org.springframework.ai
            spring-ai-bom
            1.0.0-M4 
            pom
            import
        
    


    
        org.springframework.boot
        spring-boot-starter-web
    
    
        org.springframework.ai
        spring-ai-starter-model-ollama
    
    
        org.springframework.ai
        spring-ai-starter-vector-store-chroma
    
    
        org.springframework.ai
        spring-ai-pdf-document-reader
    

2. 配置文件：连接大脑与仓库

在 `application.properties` 中，我们需要告诉 Spring AI 去哪里找模型，以及向量数据库的地址。

# Ollama 配置 
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=qwen2:7b
spring.ai.ollama.embedding.options.model=qwen2:7b # 也Ke以用专门的 embedding 模型
# Chroma 向量库配置
spring.ai.vectorstore.chroma.client.host=http://localhost
spring.ai.vectorstore.chroma.client.port=8000
spring.ai.vectorstore.chroma.collection-name=MyKnowledgeBase
spring.ai.vectorstore.chroma.initialize-schema=true # 关键：自动创建表结构
# 服务端口
server.port=8080

3. 核心服务：文档加载与向量化

这是“离线阶段”的核心代码。我们需要一个服务来读取文件，切分它，然后扔进向量库。

package com.example.demo.service;
import org.springframework.ai.document.Document;
import org.springframework.ai.reader.pdf.PagePdfDocumentReader;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.core.io.Resource;
import org.springframework.core.io.ResourceLoader;
import org.springframework.stereotype.Service;
import java.io.IOException;
import java.util.List;
@Service
public class DocLoaderService {
    private final VectorStore vectorStore;
    private final ResourceLoader resourceLoader;
    public DocLoaderService {
        this.vectorStore = vectorStore;
        this.resourceLoader = resourceLoader;
    }
    /**
     * 加载 PDF 文件并存入向量库
     */
    public void ingestPdf throws IOException {
        Resource resource = resourceLoader.getResource;
        // 使用 Spring AI 提供的 PDF 读取器
        PagePdfDocumentReader reader = new PagePdfDocumentReader;
        // 读取文档，这里默认会按页分割
        List documents = reader.get;
        // 存入向量库，内部会自动调用 Embedding 模型转换
        vectorStore.add;
        System.out.println + " 个文档片段存入向量库！");
    }
}

4. 核心服务：RAG 问答逻辑

这是“在线阶段”的大脑。它负责搜索、组装 Prompt 并调用大模型。

package com.example.demo.service;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.stream.Collectors;
@Service
public class RagQueryService {
    private final ChatClient chatClient;
    private final VectorStore vectorStore;
    public RagQueryService {
        this.chatClient = builder.build;
        this.vectorStore = vectorStore;
    }
    public String ask {
        // 1. 检索相关文档
        // topK=4 表示取Zui相似的4个片段
        List similarDocs = vectorStore.similaritySearch(
            SearchRequest.query.withTopK
        );
        // 2. 提取文本内容
        String context = similarDocs.stream
            .map
            .collect);
        // 3. 构建提示词
        // 这里使用了 Prompt Engineering 技巧，明确告诉 AI 角色和限制
        String systemPrompt = """
            你是一个智Neng客服助手。请仅根据回答用户的问题。
            Ru果参考信息中没有答案，请直接回答“抱歉，我无法在文档中找到相关信息”，不要编造。
            参考信息：
            %s
            """.formatted;
        // 4. 调用大模型
        return chatClient.prompt
            .user
            .call
            .content;
    }
}

5. 控制器层：对外暴露接口

Zui后我们写一个 REST 接口来测试整个流程。

package com.example.demo.controller;
import com.example.demo.service.DocLoaderService;
import com.example.demo.service.RagQueryService;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping
public class RagController {
    private final RagQueryService ragService;
    private final DocLoaderService docService;
    public RagController {
        this.ragService = ragService;
        this.docService = docService;
    }
    // 问答接口
    @GetMapping
    public String ask {
        return ragService.ask;
    }
    // 文档上传接口
    @PostMapping
    public String load {
        try {
            docService.ingestPdf;
            return "加载成功";
        } catch  {
            return "加载失败：" + e.getMessage;
        }
    }
}

五、常见疑问点深度排查

在大家实际跑通上述代码的过程中，我敢打赌你会遇到下面这几个坑。别慌，咱们一个个解决。

Q1: 首次运行报错，提示 Schema 不存在？

现象： 启动 Spring Boot 时报错，Chroma 或 PGVector 提示表未创建。

原因： Spring AI 为了安全起见，默认不会自动帮你修改数据库结构。

解决： 务必在配置文件中开启自动初始化开关： spring.ai.vectorstore.chroma.initialize-schema=true。注意，在生产环境初期初始化后建议关闭此选项以防误操作。

Q2: 向量检索效果hen差，答非所问？

现象： 明明文档里有答案，AI 却说找不到，或者找出来的内容完全不相关。

原因： 这通常是“文档分割”和“检索参数”的问题。

文档太长： Ru果一段文档包含太多信息，向量会变得模糊，导致语义不精准。尝试使用 `TokenTextSplitter` 进行geng细粒度的切分。

参数调整： 调整 `topK`或者 `similarityThreshold`。Ru果阈值设得太高，可Neng把稍微有点偏差但正确的答案过滤掉了。

Q3: 代码运行hen慢，每次提问dou要好几秒？

原因： RAG 涉及两个耗时环节：向量检索和大模型生成。

优化思路： 1. 检查向量库是否建立了索引。 2. Ru果使用的是远程大模型 API，检查网络延迟。 3. 考虑流式输出，让用户一边kan字一边生成，体验上会快hen多。

至此，我们的 Spring AI 入门三部曲就画上了一个圆满的句号。从Zui简单的 Hello World，到如今Neng够基于私有文档进行智Neng问答，你Yi经跨过了 AI 应用开发Zui重要的门槛。

但这仅仅是开始。RAG 虽好，但在实际生产中，我们还需要考虑geng多细节，比如：如何让 AI 输出结构化的 JSON 数据以便前端解析？如何处理多轮对话中的上下文记忆？这些dou是进阶篇中我们要探讨的话题。

希望这篇文章Neng帮你扫清 Spring AI 实战路上的迷雾。代码敲起来跑起来遇到问题别怕，那正是你成长的信号。下一章，我们将深入探讨“结构化输出”，敬请期待！🚀

推荐阅读路径： 第1篇：环境搭建与初识 ChatClient 第2篇：提示词工程与模型调优 第3篇：RAG 核心原理与实战 第4篇：AI 结果映射为 POJO

---