Spring AI+PGVector：从Demo到生产的企业知识库问答系统实战

这篇想和你聊一件我最近刚做完的事：把一个能跑通的RAG demo，一点点改造成真正能上生产的企业级知识库问答系统。核心组合就是标题里那套——Spring AI + PGVector。Spring AI负责跟大模型对话、做向量化、编排检索和生成流程；PGVector负责把文档切出来的块存成向量，并在查询时做相似度召回。这套组合做企业内部知识库、客服助手、研发文档问答、规章制度答疑这类场景非常顺手，也是目前Java后端团队落地RAG提到最多的方案。

业务方要的从来不是“能聊两句”的玩具，而是回答有依据、数据不泄露、出问题能定位、流量上来不崩。所以我几乎没留给自己试错的空间，每一步选型都得有明确理由。这篇文章会把从Demo到生产的完整过程展开给你看，包括为什么选这套技术栈、文档怎么切、检索怎么做混合、代码怎么落、生产要防哪些坑，以及我踩过的雷和最终的实测数据。如果你正在用Java技术栈做RAG，或者已经跑通demo但不知道怎么推到生产，这篇文章就是照着抄的作业。

1. 先聊清楚：这个项目到底要解决什么问题

1.1 大模型能写好答案，但管不住事实

原生的通用大模型有个天生的毛病：它会一本正经地编造答案。模型在训练时学到的是统计规律，不是实时的事实查询。你问它“咱们公司的年假制度是什么”，它会基于互联网上的泛化知识，给出一段看似合理但完全不属于你公司的回答。这就是所谓的幻觉问题。

RAG（检索增强生成）解决的就是这件事：在让大模型回答问题之前，先把问题拿去检索一遍咱们自己的知识库，把命中的文档片段和问题一起放进提示词，让大模型在给定材料的范围内做摘要和归纳。这样回答就有了“依据”，模型输出会被限定在你提供的上下文里，幻觉大幅下降，同时还能做到知识实时更新——你只需要更新数据库里的文档，不需要重新训练模型。

1.2 为什么不做微调，非要走RAG

做之前团队里确实有人提过：要不要用业务数据微调一个私有模型？我给当时的评估列了三条：

• 微调的投入产出比太低。企业文档数量多且更新频繁，规章制度每季度调整一次，产品手册随版本迭代，每改一次就微调一次，成本和时间都扛不住。
• 微调解决不了事实性问题。微调擅长改变模型的语气、风格、输出格式，但指望它记住每一条具体制度并准确引用，效果并不稳定。
• 合规压力大。把内部数据送到模型训练接口，很多公司连这一步都过不了合规审计，但RAG走推理接口，数据只在请求过程中使用，更容易解释和审计。

表格里可以直观对比一下：

结论很明确：企业内部知识库这个场景，RAG就是正解。

1.3 Demo暴露出来的三个问题

我最初用Python脚本加开源的向量库把链路跑通时，感觉一切都很美好。但把demo的代码给后端团队评审，问题立刻浮出来了：

• 没有工程化骨架。Python脚本划分了数据解析、切块、检索、调用模型各个阶段，但没有模块边界，没有错误处理，线上根本不敢跑。
• 运维体系不兼容。公司整个技术栈以Java为主，现有的监控、日志、权限、发布流程都是围绕Spring Boot搭的，塞一个Python服务进去，等于为这一个项目多维护一套体系。
• 检索质量没有量化。demo只知道“能搜出来”，但检索的准确率、召回率没有基准测试，模型换一个版本结果就漂移，根本没法验收。

所以后来我决定推倒重来，技术栈全面落到Java生态，检索存储直接用生产环境已有的PostgreSQL，引入PGVector扩展。这就是这个项目真正开始的地方。

2. 技术选型：为什么是Spring AI + PGVector

2.1 Spring AI解决了“大模型接入”的碎片化问题

在Spring AI之前，Java对接大模型基本靠手写HTTP调用，每家模型厂商的接口风格都不同，请求格式、鉴权方式、流式返回的处理逻辑都要自己实现一遍。这意味着每次换个模型，服务代码就要跟着改一遍，维护成本很高。

Spring AI做的事情是把这些统一抽象出来：ChatClient负责对话，EmbeddingModel负责向量化，VectorStore负责向量存储和检索。底层接OpenAI、通义千问、Ollama还是其他兼容接口，对上层代码来说只是换了一个配置项。我身边不少团队从自研封装切到Spring AI，最大的体感就是“模型厂商不再跟业务代码耦合了”。加上Spring AI 1.0正式发布后，兼容Spring Boot 3.4和3.5，对生产项目来说稳定性已经有保障。

Java团队选它的理由其实很简单：它让AI能力像MyBatis、Redis那些Spring生态组件一样，可以声明式接入Java后端，不用改变团队的开发习惯，也不破坏现有的工程规范。这一点在强工程化的企业环境里，比技术本身的新颖程度重要得多。

2.2 PGVector：不引入新数据库，先省掉一半运维

你可能会问，向量存储为什么不用Milvus、Weaviate、Chroma这些专门的向量数据库？它们功能更丰富。我的回答是：降级使用，要看场景。企业内部知识库的初期量级，大多是几万到几十万个文档块，这个规模用PGVector完全足够，而且能省下一整套独立数据库的部署和运维成本。

PGVector是PostgreSQL的扩展，它让你能在熟悉的SQL里直接做向量相似度检索，还支持HNSW和IVFFlat两种索引。最大的优势在于：它不是一个“额外的数据系统”，而是你现有PostgreSQL的一个延伸。这意味着你能享受PostgreSQL的事务、备份、权限管理、监控生态，文档块和业务数据可以存储在同一个库中，保证系统的一致性。RAG需要的数据和业务数据分开存放？在PGVector里可以不分开，文档维护起来还更简单。

什么时候该换独立向量库？我用一个简单的量级标准来判断：单表向量数据超过千万级，或者并发查询需要低延迟高吞吐的专用存储，又或者需要复杂的混合检索能力（比如按元数据过滤、多路召回融合）时，再考虑迁移。绝大多数企业内部问答场景，离这个天花板还很远。

2.3 整体架构与技术全景

整个系统的数据流可以拆成五个环节：

1. 文档接入：读取PDF、Word、Markdown等各类内部文档源。
2. 文档解析与切块：把长文档变成有语义边界的文本块。
3. 向量化入库：调用Embedding模型把文本块变成向量，写入PGVector。
4. 检索召回：根据用户问题，从向量库中召回最相关的文档片段。
5. 应答生成：把检索结果和问题组装进提示词，交给大模型生成最终答案。

架构上没有引入消息队列、刻意拆微服务，而是以Spring Boot单体应用起步，模块之间用接口隔离。我给团队的解释是：初期单体比微服务可靠得多。RAG链路里真正的性能瓶颈是模型调用和检索耗时，不是应用内部的模块拆分。等流量确实涨上来了，详细的模块划分也能让你平稳拆出去。

3. 数据管道：从原始文档到可检索的向量

3.1 文档解析：比想象中麻烦的环节

很多RAG教程会把文档解析一笔带过，默认你已经有干净整洁的纯文本。但真实的企业文档完全不是这样：PDF里是扫描件或复杂表格，Word里带页眉页脚，Markdown里嵌着代码块和图片链接。解析不清，切块质量就崩，后面检索再优化也救不回来。

Spring AI提供了TikaDocumentReader，底层用Apache Tika做格式解析。它支持PDF、DOCX、XLSX、PPT、HTML等几十种格式，解析效果对大多数场景够用。我实际使用中遇到最多的问题是PDF里的多栏排版，Tika在复杂版式下会读乱顺序。解决办法是：内部重要文档尽量用Word或Markdown作为解析源；PDF源文档，扫描件先过OCR再进管道，这个坑在下面踩坑清单里还会细说。

解析阶段还要做一件重要的事：保留元数据。文档来源、章节标题、更新时间、权限级别这些信息，都要跟着文本块一起存进PGVector。元数据不仅是后续做权限过滤的依据，也是提高检索精度的关键——比如只检索某个产品线的文档，一个metadata过滤就搞定了。

3.2 切块策略：RAG效果好坏的第一道分水岭

切块是RAG链路里最容易被低估的一步。块太大，单块信息太杂，向量化后语义被稀释，检索时命中噪声大；块太小，单个块语义不完整，大模型拿到的上下文碎片化，回答信息不足。我经过多轮对比测试，最终确定了内部的标准切法，你可以直接参考：

切块时还需要设置重叠窗口（overlap），相邻块之间保留一些重复内容。这个参数很多人会忽略，但它在检索时非常关键：一个完整知识点如果正好被切在边界上，没有重叠就彻底丢了。我的经验是chunk_size设为800个Token，overlap设为150到200个Token，相当于前后保留约20%的上下文重叠。

Spring AI提供了TokenTextSplitter，可以直接按Token数切，比按字符切更符合大模型的文本理解方式。如果你需要按标题结构切，可以自己实现一个TextSplitter，按Markdown的#、##、###层级做递归切分，确保每块内部是语义闭环的。

3.3 Embedding模型选型：算好成本和质量这笔账

向量化的质量直接决定检索准不准。Embedding模型选型时，我重点看三个指标：维度、最大输入Token、单条价格。

• 维度决定向量存储和计算成本。OpenAI的text-embedding-3-small是1536维，通义千问的text-embedding-v3也是1024或1536维可选。维度越高表达力越强，但存储和相似度计算开销也越大。
• 最大输入Token决定单次能向量化的文本长度。很多模型限制是512或1024个Token，如果切块太大，文本会被截断，向量完全没有意义。这也是为什么切块时Token数要卡在800以内。
• 单条价格决定批量处理成本。内部知识库一次性处理的文档量级通常不大，几万块也就几块钱到几十块钱，但企业要考虑长期增量更新，成本还是得算清楚。

生产环境我建议Embedding模型和对话模型分开配置，这样哪天想换更好的Embedding，不影响现有对话链路。Spring AI里这两个模型本来就是独立配置的，可以各用各的厂商，灵活性很好。

3.4 向量入库与索引初始化

数据写进PGVector前，要做两件事：创建扩展、建表。Spring AI的PgVectorStore会在初始化时自动建表，但你最好还是手动创建扩展，避免应用自动建表时权限不足：

sql复制CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS vector_store (
    id uuid PRIMARY KEY,
    content text,
    metadata jsonb,
    embedding vector(1536)
);

我是用Spring AI的PgVectorStore完成的入库，配置好EmbeddingModel后，直接把切好的文档列表传进去会自动完成向量化并写入数据库：

java复制@Autowired
private VectorStore vectorStore;

public void ingest(List<Document> documents) {
    // vectorStore内部会自动调用EmbeddingModel，并对文档进行向量化
    vectorStore.add(documents);
    log.info("successfully ingested {} documents", documents.size());
}

这里有一个重要细节：如果文档量大，一次性批量向量化很容易打爆模型接口的限流。我做了分批处理，每50个块一批，批次间隔500毫秒。实测下来，既不触发限流，吞吐也基本能吃满Embedding接口的QPS上限。

4. 检索链路：混合检索、重排序与提示词模板

4.1 为什么纯向量检索不够用

纯向量检索的问题在于：向量相似度擅长捕捉语义相近，但经常忽略关键词的精确匹配。举个真实的例子，用户问“服务器的保修期是多久”，如果知识库里只有“售后保修政策”这个标题，没有出现“服务器”这个词，向量检索可能会把“服务器”相关产品介绍排在前面，而漏掉保修政策原文。

解决这个问题的办法是混合检索（Hybrid Search）：向量检索负责找“语义相近”，全文检索负责找“关键词命中”，然后把两路结果融合排序。PostgreSQL自带全文检索能力，配合PGVector完全不需要额外组件。两路召回合并后，相关性明显提升，尤其是那些包含专有名词、产品编号、型号的查询，效果提升是肉眼可见的。

4.2 混合检索的SQL实现

Spring AI的PgVectorStore默认只做向量检索，如果要混合检索，有两种方式：一是自己写Repository，用原生SQL做两路召回；二是调起两路查询后，在自己的Java代码里做融合。我实际用的是原生SQL方式，效果更可控：

sql复制SELECT id,
       content,
       metadata,
       (1 - (embedding <=> :queryEmbedding))                               AS vector_score,
       ts_rank(to_tsvector('simple', content),
               plainto_tsquery('simple', :queryText))                      AS fts_score,
       (0.6 * (1 - (embedding <=> :queryEmbedding)) +
        0.4 * ts_rank(to_tsvector('simple', content),
               plainto_tsquery('simple', :queryText)))                     AS hybrid_score
FROM vector_store
WHERE (1 - (embedding <=> :queryEmbedding)) > 0.55
   OR to_tsvector('simple', content) @@ plainto_tsquery('simple', :queryText)
ORDER BY hybrid_score DESC
LIMIT :topK;

<=>是PGVector里的余弦距离运算符，1减去距离就得到相似度。ts_rank是PostgreSQL全文检索的相关性评分。融合权重我用了0.6:0.4，这个比例不是拍脑袋定的，是我在测试集上调参得出的结果——向量分数和关键词分数都有贡献，但向量语义的主导地位不能丢。

需要注意的是，to_tsvector($doc$) @@ to_tsquery($query$)用的是默认的英文分词，处理中文效果差。要么用simple配置，要么装zhparser或pg_jieba做中文分词。我生产环境用了pg_jieba，中文关键词匹配准确率明显提升。

4.3 召回后重排序：把排名修正一版

向量检索和全文检索融合后的TopN结果，仍然可能混入不相关的内容。重排序（Rerank）就是在这个阶段用更精确的模型，对TopN做个精细化的排序。这就像是先海选一批候选人，再用更严格的面试官做终面。

重排序有两种做法：

• 用专门的Rerank模型。比如Cohere Rerank，或开源的bge-reranker，对候选文档和问题做交叉编码，算出一个精确的相关性分数。效果好，但需要额外调用一次模型，增加延迟。
• 用大模型自己排序。把TopN结果和问题放在一起，让大模型选出最相关的3~5个。实现简单，但token开销大，线上延迟高。

我生产环境最终用的是bge-reranker-base模型，部署在GPU服务器上，单次重排50个候选大约耗时50毫秒，性价比很高。没有独立GPU的话，可以先从规则过滤做起，比如根据元数据业务线过滤、根据关键词覆盖率过滤，也能过滤掉明显不相关的结果。

4.4 提示词模板：把“依据”喂给模型

提示词模板是整个链路里最容易出效果、也最容易埋雷的地方。一个合格的企业内部问答提示词，至少要包含四部分：

• 系统角色设定：明确告诉模型你是企业知识库助手，只能根据提供的资料回答。
• 检索上下文：把TopN文档内容按顺序拼接进来，附上出处ID，这是模型回答的唯一依据。
• 约束规则：资料中找不到时，如实回答“知识库中没有相关信息”，绝不编造。
• 输出格式：要求包含引用来源，方便后续做溯源链接。

Spring AI的ChatClient配合PromptTemplate可以做得非常干净：

java复制String systemPrompt = """
    你是一名企业知识库助手。请严格根据给定的资料回答问题。
    资料中没有的信息，明确回答“知识库中暂无相关内容”，不要自行编造。
    回答末尾需列出引用的资料编号。
    """;

String answer = chatClient.prompt()
        .system(systemPrompt)
        .user(u -> u.text("请根据以下资料回答问题:\n\n{context}\n\n问题:{question}")
                     .param("context", contextText)
                     .param("question", question))
        .call()
        .content();

这样一个上下文结构，大模型可以稳定产出有依据的回答。我之前在某个版本的提示词里漏了“禁止编造”约束，实测模型会在资料不全时自行补充常识性内容，所以提示词每一个约束词都值得认真打磨，千万别嫌麻烦。

5. 代码落地：关键实现与核心配置逐段讲

5.1 用Spring Initializr搭建项目骨架

我使用Spring Boot 3.4.x加Java 21作为基础。Spring AI 1.0.0正式版目前对Spring Boot 3.4的兼容性最好。创建项目时直接引入以下依赖：

xml复制<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tika-document-reader</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

需要注意Spring AI的依赖仓库默认不在Maven Central，官方发布在https://repo.spring.io/milestone或https://repo.spring.io/release。如果你直接拉取失败，优先检查仓库配置，这个问题在官方文档首页就有明确说明，但还是有不少人踩到。

5.2 关键配置：application.yml逐行拆解

配置是整个系统灵活性的核心，我把关键配置项都放在了yml里，方便运维在不同环境直接切换，不用改代码：

yaml复制spring:
  ai:
    openai:
      base-url: ${AI_BASE_URL:https://api.openai.com}
      api-key: ${AI_API_KEY:}
      chat:
        options:
          model: ${CHAT_MODEL:gpt-4o-mini}
          temperature: 0.2
      embedding:
        options:
          model: ${EMBEDDING_MODEL:text-embedding-3-small}
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1536
  datasource:
    url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:rag_kb}
    username: ${DB_USER}
    password: ${DB_PASSWORD}

temperature: 0.2是我测试下来比较适合知识问答的值，温度太高模型自由发挥空间大，容易偏离给定资料；太低又显得机械。distance-type选用余弦距离，适合文本语义相似度场景。索引类型用HNSW，后面会详细讲它和IVFFlat的取舍。

5.3 文档入库：从Tika解析到落库的完整流程

入库这个环节我用了一个独立的Service来编排，流程保持线性，便于排查问题：

java复制@Service
public class IngestionService {

    private final VectorStore vectorStore;
    private final TokenTextSplitter splitter = new TokenTextSplitter.Builder()
            .withChunkSize(800)
            .withOverlap(180)
            .build();

    public IngestionService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    public void ingestFile(String filePath) {
        TikaDocumentReader reader = new TikaDocumentReader(new FileSystemResource(filePath));
        List<Document> docs = reader.get();

        docs.forEach(doc -> enrichMetadata(doc, filePath));

        List<Document> chunks = splitter.apply(docs);
        processInBatches(chunks, 50);
        log.info("ingested {} chunks from {}", chunks.size(), filePath);
    }

    private void processInBatches(List<Document> docs, int batchSize) {
        for (int i = 0; i < docs.size(); i += batchSize) {
            List<Document> batch = docs.subList(i, Math.min(i + batchSize, docs.size()));
            vectorStore.add(batch);
            try {
                Thread.sleep(500);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new RuntimeException("batch processing interrupted", e);
            }
        }
    }
}

这里enrichMetadata是给每个文档块加上来源文件名、解析时间、权限级别等元数据。这个设计后面帮了大忙——业务侧要求只能检索用户有权限看的文档，直接基于metadata筛选，不需要改动检索逻辑。

5.4 问答接口：流式输出与超时控制

生产接口对外暴露时，有一个细节非常影响用户体验：阻塞式等待大模型回复，用户体验差且容易超时；流式输出则能让用户看到文字一个个蹦出来，体感快得多。Spring AI的ChatClient天然支持流式调用：

java复制@PostMapping("/api/rag/ask")
public Flux<String> ask(@RequestBody AskRequest request) {
    SearchRequest searchRequest = SearchRequest.builder()
            .query(request.question())
            .topK(10)
            .similarityThreshold(0.55)
            .build();
    List<Document> docs = vectorStore.similaritySearch(searchRequest);
    String context = buildContext(docs);
    
    return chatClient.prompt()
            .system(systemPrompt)
            .user(u -> u.text("请根据以下资料回答问题:\n\n{context}\n\n问题:{question}")
                         .param("context", context)
                         .param("question", request.question()))
            .stream()
            .content();
}

接口返回Flux<String>，前端通过SSE接收流式内容。这里要特别留意超时设置：大模型接口本身可能耗时15秒以上，但网关和服务间的feign调用超时不能卡死在默认的几秒上。我的做法是应用层超时设置为60秒，网关层设置为90秒，留足余量。

6. 生产防护：连接、索引、并发与安全

6.1 HNSW索引与IVFFlat：参数权衡

PGVector支持两种索引：IVFFlat和HNSW。IVFFlat先把向量聚类成多个list，查询时只搜索相近的几个聚类，快但精度一般。HNSW基于图结构检索，查询更快更准，代价是构建索引时内存占用高、建索引时间长。

我的实际选型很明确：数据量几十万以内，无脑用HNSW。它的查询延迟稳定在10毫秒级别。建索引时遇到过一个问题，几十万条数据一次性建索引会把实例内存打满，解决方法是分批次构建，或者先建IVFFlat过渡，低峰期再重建HNSW。索引创建语句如下：

sql复制CREATE INDEX ON vector_store USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

m和ef_construction是HNSW的两个核心参数：m控制每个节点的最大连接数，越大越精确但内存越高；ef_construction控制建索引时的动态列表大小，越大索引质量越高。16和64是社区公认的均衡推荐值。查询时的ef_search可以在SQL里动态指定，比如SET hnsw.ef_search = 100;，值越大召回越准但越慢。

6.2 连接池和并发控制：别让模型API成为压垮系统的最后一根稻草

生产环境最大的风险不在数据库，而在外部模型API。模型API限流、超时、返回异常，任何一个都会直接拖垮业务系统。我在接入层做了三层防护：

• 数据库连接池限制。HikariCP的maximum-pool-size设置为核心数加一，防止慢查询堆积打爆连接池。
• 模型API调用限流。内部用Semaphore控制了并发调用大模型的线程数，默认限制20个并发，超出的请求排队等待，避免瞬间流量把API额度耗尽。
• 熔断降级。依赖Resilience4j对模型调用做熔断，连续失败率超过阈值后，直接返回提示“AI服务暂时不可用”，而不是让用户一直转圈。

这层防护让我在一次模型上游故障时保住了系统可用性，虽然AI问答不可用，但整个Spring Boot应用没有宕机，健康检查也一直是绿的。

6.3 权限过滤与数据安全

企业内部知识库，最怕的是越权访问。A部门的薪资制度，绝不能被B部门的人通过AI问答问出来。我的做法是权限数据与文档元数据绑定，所有查询请求进来时，先从登录态拿到用户的权限标签，再拼进检索SQL做强制过滤：

sql复制WHERE metadata ->> 'permission' IN (:permissions)
   OR metadata ->> 'permission' = 'public'

这个过滤条件打在SQL层，任何业务代码都无法绕过去。此外，外部传输全程走HTTPS，敏感文档在入库前做脱敏处理，日志里禁止打印问题和答案原文。这些安全措施结合后，过内部安全评审基本没有问题。

6.4 监控、日志与可观测性

RAG链路涉及的中间环节太多了，没有监控等于盲飞。我上了三套基础监控：

• 链路追踪。用Micrometer Tracing把“问题接收→向量检索→重排序→模型调用→答案返回”整条链路的耗时记录成span，哪个环节慢了在一张图上就能看出来。
• 业务指标。记录每天的问题量、检索命中率、平均响应时长、token消耗量，这些指标能直观反映系统的使用情况和成本。
• 质量日志。把每个问题的答案、引用的文档块ID、相似度分数都记录下来，后期评估和问题复盘全靠这份日志。

其中“引用的文档块ID + 相似度分数”这两个字段的价值非常容易被低估，没有它们，你根本没法回答业务方那句灵魂拷问：“这个答案为什么这么答？”有了日志，就能回溯，能判断是检索没召回正确文档，还是模型没用好上下文。

7. 评估与踩坑：用数据说话，替你把雷排了

7.1 建一个评估集，让RAG效果可量化

RAG系统上线前一定要有一个离线测试集，否则你根本不知道这次改动是变好了还是变差了。我花了一个周末，从知识库里抽了80个真实业务问题，给每个问题标注了正确答案和对应的文档块。评估时计算三个指标：

• 检索命中率：召回的Top5里是否包含正确答案对应的文档块，查全率。
• 答案准确率：人工判断模型回答是否与标准答案一致或高度相关。
• 引用准确率：模型引用的文档是否真实支持它的回答，防止“引用没错但答非所问”。

我用这三个指标，对比了纯向量检索和混合检索的差异。测试结果显示：纯向量Top5命中率在72%左右，混合检索提升到了88%。原因是业务问题里含大量产品型号、政策名称等专有名词，全文检索的精确匹配帮了很大的忙。重排序又把这88%的命中率推到了94%。数据一出来，团队的信心就有了。

7.2 踩坑实录：这些坑我替你踩过了

每个坑都对应一行代码或一个配置的调整。这里挑两个最有代表性的展开说说。

第一个是Nginx的SSE缓冲问题。我把流式接口联调好，本地测试完美，部署到生产后，前端页面十几秒不出一个字，最后一次性吐了整段回答。排查了很久才发现是Nginx默认开启了缓冲，把流式内容攒到一起才转发。需要在location里加一行proxy_buffering off;，问题立刻消失。这类问题在本地环境根本复现不出来，只有部署到真实代理环境才会暴露。

第二个是相似度阈值的作用。我把similarityThreshold设成0后，发现模型偶尔会从无关文档里“硬找”答案。后来把阈值调高到0.52，效果立刻改善。但要注意阈值也不能太高，调太高会把大量相关文档过滤掉，让模型无据可依。这个阈值需要在测试集上反复调，没有一个万能值。

7.3 线上稳定性：版本、模型、数据的三角管理

还有一类问题不是一次性的bug，而是长期运维中会反复咬你的。我整理成三个原则写进了运维手册：

• 模型版本要锁定。生产环境的对话模型和Embedding模型一定要锁定版本号，每次升级要回归测试集。模型厂商不定期更新版本，语义表现会漂移，不锁版本，今天能用明天可能就废了。
• 索引变更要有演练。改向量维度、换Embedding模型、重建索引都是高风险操作，必须在预发环境完整跑一遍入库和查询流程，确认无误后再上生产。
• 定期抽检答案质量。我每周会随机抽20条问答记录，人工看一遍答案质量，同时把周报里的“引用准确率”“检索命中率”一起过一遍。这个习惯帮我提前发现了一次Embedding模型升级带来的质量回退。

8. 后续扩展：从单轮问答走向更复杂的应用

系统平稳运行之后，我开始琢磨怎么把这条链路的能力放大。目前已经验证可行的方向有三个。

第一个是Agentic层面的扩展。Spring AI的多智能体编排可以做多轮工具调用，把RAG变成智能体的一种工具。我在一个实验项目里验证了：让智能体先判断用户意图，再决定走RAG知识库、查订单系统还是调工单API，效果比单纯的固定流程灵活很多。

第二个是Spring AI Alibaba的Skill机制。Skill把数据分析、定时任务、API调用等进行抽象，可以和RAG自由组合。比如在知识库问答基础上，叠加一个“排班汇总”Skill，模型就能从文档里找出班次规则，再结合当前人员表做推算，跨越纯文本检索的边界。

第三个是GraphRAG方向。普通RAG把文档切成互不相干的块，GraphRAG则会在实体层面建立关系图，回答“哪些模块之间有什么依赖”“某个方案影响了哪些环节”这类跨文档问题时会明显强于普通RAG。我目前还在用Spring AI Graph做技术验证，后面跑通后再单独写一篇。

这次改造给我最大的体会是：RAG系统90%的复杂度根本不在模型，而在文本处理、检索质量、运维稳定性这些不显眼的地方。Spring AI把基础组件标准化得很好，但真正能不能跑到生产，还是得靠工程上一个个细节去抠。如果你正在从demo往生产走，希望这篇文章能帮你把路看清楚，少踩几个我已经替你踩过的坑。