先说个背景：这段时间我用 Spring AI 落地了一个 RAG 知识库项目，从最开始连“向量”这个词都只是听说过，到最终把检索链路、向量库选型、评测体系全部跑通，前后折腾了大概三周。这篇就把整个复盘过程写出来，围绕 RAG 拆成 13 张图来讲，每张图对应一个必须搞懂的核心点。适合正在学 RAG 或准备用 Spring AI（包括 Spring AI Alibaba）做知识库后端的同学，不需要你有向量数据库基础，会 Spring Boot 就能跟上思路。
我不打算上来就堆概念，而是按一条实际做项目的路径走：先从向量开始把地基打牢，再拆 RAG 的完整链路，接着给 Spring AI 的实战代码和选型理由，然后是评测体系怎么搭，最后聊 RAG 的瓶颈和进阶方向。文中所有代码、参数、坑，都是我在真实项目里验证过或踩过的。
1. 向量到底是什么：RAG 的第一块地基
1.1 文本变成数字：Embedding 模型的工作原理
第一张图，也是最关键的一张：想象你有一堆文本，把它们全部丢进一个 Embedding 模型，出来的是高维空间里的一堆点。例如“今天天气不错”和“今天天气很好”这两个句子，变成坐标后距离非常近；而“今天天气不错”和“股价涨停了”这两个句子，距离就非常远。RAG 能工作的根本原因就是这个几何性质：语义相似性被映射成了空间距离。
那 Embedding 模型到底做了什么？本质上它是一类神经网络编码器，把输入文本先拆成 token，再通过多层注意力网络把整个句子的语义压缩成一个固定维度的浮点数组。常见模型有 bge-m3、text-embedding-3、qwen-embedding 等，输出维度通常是 1024 或 1536。这组浮点数没有“可读性”，你没法说第 37 个数字代表什么，但它整体上编码了句子的语义信息。
第二张图我画的是 Embedding 的处理流程：原始文本 → 清洗 → 切 token → 模型编码 → 归一化 → 得到向量。其中归一化这步很多人忽略，实际很重要，归一化之后向量长度变成 1，后续用点积和余弦相似度结果就完全一致了，很多向量库默认存的就是归一化后的向量。
1.2 相似度计算：点积、余弦、欧氏距离怎么选
第三张图是三种距离/相似度的几何示意。先给结论：RAG 场景里默认用余弦相似度，或者用归一化后的点积，极少用欧氏距离。
- 余弦相似度：只关心两个向量的方向是否一致，公式是 A·B 除以两者模长的乘积，结果范围 [-1, 1]。它对向量的绝对长度不敏感，适合文本这种长度天然有差异的场景。
- 点积：A·B 直接相乘求和，结果会受向量长度影响。如果向量已经归一化，点积和余弦完全等价；如果没归一化，长向量容易占便宜，检索结果会被文档长度干扰。
- 欧氏距离：几何上最直观，就是两点间的直线距离。但维度一高，所有距离都会趋向接近，这就是常说的“维度灾难”，在文本向量上表现明显不如余弦稳定。
Spring AI 里可以通过embeddingModel.distance()或向量库配置来指定相似度类型，我项目里统一用的余弦，实测效果最稳定。也顺便提一句：很多论文会用点积，但那是建立在向量已归一化的前提下，别盲目抄。
2. RAG 全链路拆解：索引、检索、增强、生成
2.1 建知识库的前两步：切分与向量化
第四张图是整个 RAG 的架构总览，四个阶段：加载解析 → 切分 → 向量化入库 → 检索增强生成。前两步看着简单，实际最影响效果。
文档加载解析这里有个很容易踩的坑：PDF 直接按文本提取，表格、多栏排版、图片注释会全部乱掉。我处理公司产品文档时，PDF 里只要出现双栏布局，按顺序读出来的文本就是错乱的，检索时召回的内容牛头不对马嘴。这一步建议优先用 Markdown 或 HTML 源文件，其次才考虑解析 PDF，必要时对复杂 PDF 做 OCR 预处理。
切分（Chunking）是第五张图的内容。为什么要切？因为 Embedding 模型有最大输入长度限制，而且过长的文本切成一个向量，语义会被稀释，检索时定位不到具体段落。我用的参数是：chunk_size 800 字符，overlap 100 字符。overlap 的目的是避免句子恰好被拦腰切断，导致语义断裂。切分方式有三类：
- 固定窗口切分：简单粗暴，按字符数硬切，适合日志、代码等结构弱的内容。
- 递归字符切分：按“段落 → 句子 → 子句”的优先级递归切，能保留语义完整性，这是我最常用的方式。
- 语义切分：用模型判断语义边界再切，效果好但成本高，适合对精度要求极致的场景。
切分后的每个 chunk 就是一个 Document，会配一个唯一 ID，连同原始文本一起交给 Embedding 模型向量化，再写入向量数据库。
2.2 向量索引与召回：Top-K 里藏着最大变量
第六张图是 HNSW 索引结构。向量数据库的索引不是为了算得快，是为了“少算”。暴力检索要拿 query 向量跟库里所有向量逐一比对，百万级数据根本扛不住。HNSW 的思路是多层跳表：上层稀疏、底层稠密，从顶层快速定位到大致区域，再往下一层层细化，查询复杂度能降到对数级别。选向量库时，HNSW 基本是默认选项，MILVUS、PGVector、Elasticsearch 全支持。
第八张图是 Top-K 召回流程：query 向量化之后，在索引里找到最相似的 K 个向量，把对应 chunk 文本取出来。这里有两个关键参数：
- Top-K：我项目里设为 5。太小召回不全，太大会把不相关的内容塞进上下文，既浪费窗口又干扰生成。
- 相似度阈值：Spring AI 的
VectorStoreDocumentRetriever里可以配similarityThreshold，低于阈值的检索结果直接丢弃。我实测阈值 0.5 左右比较合理，低于 0.4 召回质量明显下降。
这里引出一个容易忽略的问题：Top-K 召回的是“向量相似”的内容，不是“语义正确”的内容。Embedding 模型如果没调好，语义鸿沟会直接变成召回噪声，后面重排序环节就是来补救这个问题的。
2.3 重排序与 Prompt 拼接：最后一步的精细活
第九张图是 Reranker 重排序。Top-K 召回拿到 5 条候选，其中可能只有 1-2 条真正有用。重排序模型（如 bge-reranker）会把 query 和每个候选拼接起来，用 cross-encoder 方式逐对打分，再重新排序。Bi-encoder（普通 Embedding）把 query 和文档分别编码再算相似度，速度快但交互少；cross-encoder 让两者在模型内部充分交互，精度明显更高。
我项目里召回 5 条，重排序后只取前 3 条进 Prompt，生成质量比直接取前 5 条提升了不止一个档次。代价是多一次模型推理，耗时增加几十毫秒到两百毫秒不等，看模型大小，这个成本值得花。
第十张图是 Prompt 拼接的结果示意。实际上发给大模型的 prompt 结构大致是：
你是一个知识库问答助手，请基于以下参考资料回答用户问题。 如果参考资料中没有答案，请直接说明不知道，不要编造。 参考资料： [1] 文档标题A，第3段：...... [2] 文档标题B，第1段：...... 用户问题：......这个模板里两个细节很关键：一是强制要求“没有答案就直说不知道”，能明显抑制 LLM 幻觉；二是保留来源编号，一方面方便溯源，另一方面让模型知道内容来自哪份文档，生成时会更“克制”。
3. Spring AI 实战：从零搭一个本地 RAG 知识库
3.1 技术选型：Spring AI、LangChain4j、Dify 怎么选
十一张图（这张放在实操对比里更合适）：社区生态对比。这个环节其实我犹豫过，LangChain4j 在 Java 圈也很成熟，Dify 则是低代码平台思路，最后选了 Spring AI，核心原因有三个：
- 官方适配和标准 API：Spring AI 是 Spring 官方项目，会统一
EmbeddingModel、VectorStore、ChatClient等抽象，版本迭代有保障，不像第三方框架存在停更风险。 - 对 Java 后端最友好：团队本就是 Spring Boot 技术栈，接入成本极低，不用额外维护一套 Python 服务。
- 模型供应商抽象做得干净：Ollama、OpenAI、百炼、通义千问等，切换时只改配置，业务代码不用动。
如果你是个人快速验证，Dify 确实更快，拖拽界面就能搭出一套知识库；但一旦要深度集成到现有业务系统，比如权限、音视频处理、数据看板，低代码平台就会变成瓶颈。Dify 的工作流最终还是要转成代码来实现定制逻辑，这也就是为什么“Dify 工作流转 Spring AI Java 代码”会被反复搜索。
3.2 Spring AI 核心代码：Embedding、VectorStore、ChatClient 一次打通
这是整篇文章的实操核心。我用 Ollama 跑本地模型：Embedding 用 bge-m3，生成用 qwen2.5 7B，数据库用 PostgreSQL + PGVector。整套配置代码基于 Spring AI 1.x：
@Configuration public class RagConfiguration { @Bean public EmbeddingModel embeddingModel() { return OllamaEmbeddingModel.builder() .baseUrl("http://localhost:11434") .modelName("bge-m3") .build(); } @Bean public VectorStore vectorStore(EmbeddingModel embeddingModel, DataSource dataSource) { return PgVectorStore.builder(dataSource, embeddingModel) .dimensions(1024) .schemaName("public") .tableName("rag_docs") .build(); } @Bean public RetrievalAugmentationAdvisor advisor(VectorStore vectorStore) { return RetrievalAugmentationAdvisor.builder() .queryAugmentor(QueryAugmentor.query()) .documentRetriever(VectorStoreDocumentRetriever.builder() .vectorStore(vectorStore) .topK(5) .similarityThreshold(0.5) .build()) .build(); } @Bean public ChatClient chatClient(ChatModel chatModel, RetrievalAugmentationAdvisor advisor) { return ChatClient.builder(chatModel) .defaultAdvisor(advisor) .build(); } }配置好之后，业务侧就是最普通的调用：
@Service public class RagService { private final ChatClient chatClient; public RagService(ChatClient chatClient) { this.chatClient = chatClient; } public String ask(String question) { return chatClient.prompt() .user(question) .call() .content(); } }关键点在于defaultAdvisor(advisor)，这里的RetrievalAugmentationAdvisor会把“向量检索 + 重排序 + Prompt 增强 + 生成”这条链路全部串起来，业务代码不用关心 RAG 细节。这就是 Spring AI 抽象比直接调向量库 SDK 更舒服的地方。
文档入库的代码也很简单：
@Service public class DocumentIngestService { private final VectorStore vectorStore; public void ingest(String rawText) { TextSplitter textSplitter = TextSplitter.builder() .chunkSize(800) .overlap(100) .build(); List<Document> docs = textSplitter.apply(rawText); // 可选：对每个 doc 设置 metadata，比如来源文件名、章节号 docs.forEach(doc -> doc.getMetadata().put("source", "manual")); vectorStore.add(docs); } }这套流程跑通后，一个最小的本地 RAG 知识库就成型了。再提醒一下：Ollama 的 baseUrl 要确保能访问，Embedding 模型维度 1024 必须和 PGVector 建表时的维度保持一致，不一致会直接报错。
3.3 向量数据库集成与优化
第七张图是 Spring AI 各组件的关系图：ChatClient → RetrievalAugmentationAdvisor → VectorStore → EmbeddingModel，以及DocumentIngestService → VectorStore → EmbeddingModel。两个入口最终都汇聚到VectorStore，所以选型和优化都围绕它展开。
向量数据库我最终选了 PGVector，理由是团队不想额外引入一套 Milvus，PG 身兼业务库和向量库，运维成本最低。如果你数据量超过 500 万条，或者对毫秒级延迟有硬性要求，还是上独立的 Milvus 或 Qdrant 更稳。
PGVector 建表时要显式指定维度：
CREATE TABLE rag_docs ( id SERIAL PRIMARY KEY, content TEXT, metadata JSONB, embedding vector(1024) ); CREATE INDEX ON rag_docs USING hnsw (embedding vector_cosine_ops);索引类型选了 HNSW +vector_cosine_ops，因为前面定了用余弦相似度，这个索引直接对应余弦距离算法。这里容易出错的地方是：如果建表维度是 1024，但是用了 1536 维的 Embedding 模型，写入时就报错；反过来也一样。升级模型时记得重建表和索引。
再分享一个优化细节：HNSW 索引的m（每个节点的最大连接数）和ef_construction（建索引时的动态候选集大小）两个参数。默认 m=16、ef_construction=64 足够，追求极致召回可以把 m 调到 32，但索引体积和构建时间会明显上升。我实际项目中保持默认，查询 10 万条向量耗时在 20 毫秒以内，完全够用。
4. 评测体系：用数字证明 RAG 效果
4.1 核心指标拆解：hit rate、MRR、忠实度、答案相关性
第十一张图是评测指标概览。很多人做完 RAG 只靠“感觉回答得挺准”，这不行。必须把效果量化，才能知道改动有没有用。我用的四个指标：
- Hit Rate@K（召回命中率）：前 K 条检索结果里，是否包含标准答案对应的文档。衡量的是“检索有没有把关键内容捞出来”。
- MRR（平均倒数排名）：第一个正确答案排在结果列表第几位，排得越靠前越好。公式是 1/rank 的平均值，比如正确答案排在第一位得 1 分，第二位得 0.5 分。
- 忠实度（Faithfulness）：生成的每个句子，是否都能在检索到的 context 里找到依据。这一步本质是检测幻觉，答案如果编造了材料中没有的内容，忠实度就会扣分。
- 答案相关性（Answer Relevance）：生成内容对用户问题是否切题，有没有答非所问。它和忠实度互补，一个保证“没编造”，一个保证“没跑题”。
Hit Rate 和 MRR 是检索质量指标，忠实度和答案相关性是生成质量指标。四者合起来才能真正反映 RAG 系统水平。
4.2 评测数据集构建与测试流程
评测集是评测体系的灵魂，没有高质量评测集，一切都白塔。我的做法是：从项目真实文档里挑 60 个典型问题，每个问题手工标注对应的正确答案片段（chunk ID）。这 60 个问题不能都是简单的“事实型问题”，要覆盖三类：
- 简单事实型：答案在某一个 chunk 里明确存在，比如“XX 服务的超时时间默认是多少”。
- 推理型：答案分散在多个 chunk，需要模型拼接，比如“A 服务和 B 服务之间是如何传递鉴权信息的”。
- 跨文档型：答案涉及两份甚至更多不同文档，比如“某功能的最新版本相对于旧版本改了哪些配置”。
标注完就产出测试集，然后写测试代码批量跑。Hit Rate 和 MRR 可以在 Java 里直接算：
public static double hitRate(List<List<String>> retrievedDocs, List<String> relevantDocs, int k) { int hits = 0; for (int i = 0; i < retrievedDocs.size(); i++) { List<String> topK = retrievedDocs.get(i).subList(0, Math.min(k, retrievedDocs.get(i).size())); if (topK.contains(relevantDocs.get(i))) { hits++; } } return (double) hits / retrievedDocs.size(); } public static double mrr(List<List<String>> retrievedDocs, List<String> relevantDocs) { double total = 0.0; for (int i = 0; i < retrievedDocs.size(); i++) { for (int j = 0; j < retrievedDocs.get(i).size(); j++) { if (retrievedDocs.get(i).get(j).equals(relevantDocs.get(i))) { total += 1.0 / (j + 1); break; } } } return total / retrievedDocs.size(); }忠实度和答案相关性这类生成指标，靠人评分太累，我自己偏好用开源的 RAGAS 框架，或者让一个更强的 LLM 当裁判来打分。虽然自动评测跟人工标注还有差距，但作为回归测试手段，价值非常大：每次调参后跑一遍评测集，数字摆在那儿，改动好不好一目了然。
4.3 从评测结果反推调优路径
评测不是跑完就完事，关键是看数字定位问题。分享我的调优路径：
- Hit Rate 低于 70%：问题大概率出在切分和 Embedding 模型上。先优化切分（加 overlap、换语义切分），再考虑换更强 Embedding，然后才能动其他环节。
- Hit Rate 高但 MRR 低：说明正确答案被召回了但排得靠后，多半是 Top-K 位置安排不合理，或者向量召回时相似度排序不够准。优先加重排序。
- 忠实度低：模型在编造，说明 Prompt 里的“禁止编造”约束不强，或者检索内容本身有噪声干扰。我在 Prompt 里强制要求“没有依据就回答不知道”，效果立竿见影。
- 答案相关性低：可能是 query 本身太模糊，或者增强环节没有把用户问题改写清楚。Spring AI 的
QueryAugmentor可以配 query 改写，这一步能解决不少实际问题。
总之一个原则：检索质量没达标之前，不要浪费时间调 Prompt 和生成参数。地基不牢，上层再怎么优化都白搭。
5. 进阶方向：Agentic RAG、GraphRAG、本体 RAG
5.1 RAG 的瓶颈在哪
第十二张图画的是 RAG 瓶颈归因。传统 RAG（一次检索、一次生成）在下面三个场景明显力不从心：
- 多跳问题：比如“上海和杭州之间的高铁经过哪些城市”，答案分散在多篇文档，一次 Top-K 检索很难同时捞到。
- 知识割裂：文档之间本身有复杂的实体关系，比如“某功能上线后影响了某模块的配置”，但 RAG 只是按向量相似度找文本块，实体关系完全没建模。
- 动态多步需求：各种条件判断，比如“如果用户是会员就推荐这几个商品，否则推荐另一批”，传统 RAG 一次生成根本没法处理这种分支逻辑。
向量检索本质是在找“相似的文本碎片”，它不擅长做“多步推理”。这就引出了下面这些进阶方向。
5.2 Agentic RAG：让模型自己决定怎么查
第十三张图是 Agentic RAG 与传统 RAG 的对比。核心思路：把“检索”从一个固定动作变成一个决策过程。模型先理解用户问题，然后决定要查哪个向量库、查几次、要不要改写 query、检索完够不够用、不够就再查一轮。
Spring AI 里实现这个思路有几个现成路径：一是用ChatClient配合工具函数（Tool Calling），把VectorStore检索封装成一个工具，让模型自主决定何时调用；二是引入 Spring AI Agent 相关组件做更复杂的 ReAct 循环。我项目里先做了一个最小版本：定义一个vectorSearch(String query)工具，模型在推理过程中按需调用，遇到多跳问题时效果比传统 RAG 好很多。
5.3 GraphRAG 和本体 RAG：从“文档”到“知识结构”
从“文档”到“知识结构”这个转变，是 GraphRAG 和本体 RAG（Ontology RAG）共同的底层逻辑。GraphRAG 的思路是用 LLM 把文档里的实体和关系抽取出来，构建成知识图谱，查询时先从图里找到相关子图，再结合原始文本去生成。它的优势是把实体关系显式建模，弥补了向量检索不懂关系的短板。本体 RAG 则更进一步，在抽取实体关系之上，给知识定义统一的概念体系和约束，适合企业级复杂领域，代价是构建成本高、维护活重。
听起来很美好，但如果你只是单机小项目，我建议先别上头。GraphRAG 的抽取过程对算力消耗极大，我拿 200 页文档试过一次，跑了快半小时用掉 160GB 内存。等真遇到多跳、跨文档关系问题再上，否则性价比偏低。
5.4 从 Dify 工作流迁移到 Spring AI Java 代码
这是近半年大量团队在做的迁移：低代码平台原型验证跑通后，把工作流固化到正式后端。Dify 工作流里最常见的是“知识检索 → 模型生成 → 条件分支”这套节点组合。迁移到 Spring AI 的对应关系很直接：
- 知识检索节点 →
VectorStoreDocumentRetriever+similarityThreshold阈值配置 - 模型生成节点 →
ChatClient.prompt().call() - 条件分支节点 → Spring 的
ConditionalEvaluator或者工具调用路径里自己写分支策略 - 迭代循环节点 → Agentic RAG 的工具调用方式
迁移过程注意，Dify 里的知识库切分参数、检索阈值如果你当时调过，迁移时要同步到 Spring AI 代码里，不然效果直接回退。我见过不少团队迁完代码之后抱怨“没 Dify 效果好”，一查全是参数没对齐。
6. 常见问题与避坑实录
6.1 图片到底能不能存进 RAG 知识库
这是被问得最多的一个问题。我的答案是：看你用什么方式处理图片，不同路线结论不一样。
如果走传统 RAG 链路，也就是文本 Embedding + 文本向量检索，那图片确实没法直接入库，因为 Embedding 模型吃的是文本，不是像素。你丢一张扫描件进去，它什么都检索不到。正确做法是先 OCR 把图片里的文字提取出来，再走正常入库流程；如果是图表，配一句人工写的文字说明，把图的要点描述清楚一并入库，检索效果反而更好。
如果你希望模型直接理解图片内容，那就是多模态路线：用支持视觉的多模态模型（比如通义千问 VL 系列）把图片编码或理解后参与生成。但要注意，这条路线和“RAG 知识库”是两个维度，你需要的是多模态检索+多模态生成，Spring AI 目前对 OpenAI 风格的 image content 已经有支持，Java 侧也能做，但复杂度明显高。绝大多数业务场景，OCR + 文本描述入库这条路最稳。
6.2 本地部署踩过的坑
本地跑模型看着简单，坑是真不少。第一个是 Ollama 拉模型慢，bge-m3 有几个 G，公司网络不给力时能等一个小时，提前做好预下载。第二个坑是内存：Embedding 模型 bge-m3 大概 1.2G 内存，qwen2.5 7B 量化后要 6-8G，我开发机 16G 内存跑这两个刚好，再叠加 PG 和 Java 虚拟机就容易卡。建议模型尽量用量化版，开发阶段用小型模型。
还有一个很容易翻车的地方：OllamaEmbeddingModel的 baseUrl 写http://localhost:11434时，如果你跑了 Docker 或远程开发环境，localhost 指向的根本不是宿主机，需要改成宿主 IP 或服务名。这种问题不看日志根本发现不了，报错往往还是“Connection refused”。
6.3 几个容易忽略的性能与效果细节
最后送几个实测总结——先说说切分和相似度阈值，这两个参数存在联动关系。切分越小，召回粒度越细，但每块包含的上下文越少，对后续生成反而有反效果；我项目里从 800 调到 1500，hit rate 提升约 5 个点，生成答案的连贯性也更好。同时similarityThreshold这块，不要把 Top-K 和阈值同时设得很高，比如 Top-K=10 加阈值 0.8，极大概率经常召回不到内容，两者之间要留出余量。
再一个容易被忽视的成本项：一次 RAG 调用可能包含向量检索、重排序、LLM 生成三段耗时，而且每次都要重新 Embedding 当前 query。query 向量化这步本身就几十毫秒，如果你在网关层做简单缓存（同等问题原文重复问直接走缓存），长尾问题能省掉一大半计算成本，实测下来挺值的。最后记住，评测集务必随文档更新而更新，没有持续维护的评测集，你的优化就是在打黑枪。
