最近不少做 Java 的同行都在问同一件事零基础想用 Spring AI 在 Java 项目里做检索增强生成RAG到底怎么起步很多人第一反应是去抄 Python 那套 LangChain 配合专用向量数据库的方案其实用 Spring AI 直接对接自己熟悉的 PostgreSQL加一个 pgvector 扩展就能把文档检索、向量化、问答生成整条链路跑通而且不引入额外的独立中间件。这篇文章按我实际搭过的一个模拟问答系统的流程来写适合完全没接触过向量数据库、也没写过 AI 接口的 Java 开发者。你能得到的不是一堆概念名词而是能直接抄的依赖、配置、表结构和代码骨架以及我在调试过程中踩过的坑和最终留下的调参经验。所有核心关键词都会落在 Spring AI、Java、向量数据库、PostgreSQL、检索增强生成RAG这几条线上。1. RAG解决的是大模型的临时记忆力问题1.1 为什么直接问大模型不靠谱先打个比方。大模型像一个知识面很广但不带资料库的专家他的知识在训练完成那一刻就冻结了。你问他常识问题、通用问题他能答得很好但你让他回答你们公司内部的产品手册、某个系统的接口规范、某份合同里的条款他大概率会一本正经地编造答案。这不是模型笨而是这些私有内容根本不在他的训练数据里。RAGRetrieval Augmented Generation检索增强生成的思路很直白不强迫模型记住所有资料而是在你提问的时候先去一个外部资料库里把相关片段检索出来再把这些片段连同问题一起交给模型让模型基于片段作答。这样模型既不需要重新训练也不需要记住你的文档回答质量却可以贴近私有知识。对企业应用来说这是目前成本最低、落地最快的方案。1.2 一次RAG请求的内部旅程我在刚接触这一套时最大的困惑是到底有哪些环节。后来自己动手拆出来其实就五步把文档PDF、Markdown、纯文本加载进来把长篇大论切成小块因为模型上下文有限而且整篇塞进去既贵又容易跑题为每一块文本生成一个向量也叫嵌入 embedding把语义变成一串数字用户提问时把问题也变成向量去数据库里做相似度搜索找出最相关的几块文本把检索到的文本块 用户问题 系统提示词一起交给大模型生成最终回答。前四步属于检索第五步属于生成合起来就是检索增强生成。你只要理解了这条链路后面所有代码其实都是在往上套。1.3 Spring AI在整条链路里的位置很多 Java 开发者对 AI 有一种误解觉得必须会 Python、必须懂机器学习才能碰。实际上你现在做的是应用集成不是训练模型。Spring AI 就是帮你做集成的那层封装它把上面五步里的切分、向量化、存取、检索、调用模型都封装成了 Java API。你要做的只是准备数据、写配置、调接口。模型从哪里来、向量怎么算、存到哪里都有对应的 starter 可以插拔。换句话说你不需要成为 AI 专家只需要成为一个会用 Spring AI 的 Java 开发者。这也是标题里零基础三个字的底气所在——你真正需要的新知识只有向量数据库的少量概念剩下的全是你熟悉的 Spring 风格。2. 选型思考为什么是 Spring AI PostgreSQL 这套组合2.1 Spring AI给Java生态补上了什么在 Spring AI 出现之前Java 接大模型基本都是自己拿 HTTP 客户端去调 REST API文档字符串拼接、鉴权管理、重试逻辑全靠手写还要另找一套方案做向量存储。Spring AI 的做法很符合 Java 社区的脾气提供统一的 ChatClient 和 VectorStore 抽象底层对接不同模型和不同向量库你换供应商只需要改配置。举个例子同样的代码聊天模型从一家换成另一家通常只要改 application.yml 里的模型名称和 Key向量库从 PostgreSQL 换成别的存储业务代码也不需要大改。这种面向接口编程的习惯对 Java 开发者来说属于肌肉记忆上手自然快。而且 Spring AI 完全沿用 Spring Boot 的自动配置机制你加一个依赖它就帮你装配好对应的客户端 Bean。2.2 为什么向量存储选pgvector而不是专用向量数据库市面上的专用向量数据库宣传了很多性能指标确实漂亮但落到很多中小项目里有个现实问题你的业务数据本来就在 PostgreSQL 里为什么非要再部署一套独立服务多一个中间件就多一套运维、多一份监控、多一个备份策略。pgvector 是 PostgreSQL 的一个扩展直接让普通数据库获得向量存储和相似度检索能力数据能跟业务数据放在一个事务里管理对于先跑通再说的场景非常合适。顺便说一句选型边界如果未来向量数据量达到千万级、查询并发很高再考虑迁到专用向量数据库也不迟。前期的表结构、检索逻辑都差不多迁移成本没有想象中高。对零基础入门来说pgvector 能让你把注意力集中在 RAG 本身的链路上而不是被分布式基础设施分走精力。3. 零基础环境搭建版本组合要先对上这一节最容易劝退新人因为网上资料版本很杂照着旧教程敲完代码编译报错一片红。我直接把当前能用、验证过的组合写出来。3.1 版本矩阵与BOM管理Spring AI 的版本号迭代快早期 0.8.x 到 1.0.0 GA 之间 API 变化不小。我用的是基于 Spring Boot 3.4.x 的 Spring AI 1.0.0 这一代ChatClient、VectorStore、SearchRequest 这些核心 API 都趋于稳定。你如果拿 0.8.x 的教程硬套 1.0是会踩不少坑的。管理依赖时有两个关键动作。第一个是用 Spring AI 的 BOMBill of Materials统一版本避免各个 artifact 版本不一致。第二个是确认 Spring Boot 版本与 Spring AI BOM 声明兼容Spring AI 的发布说明里会写明对应 Spring Boot 的版本范围严格按它来。在 pom.xml 里这样引入 BOMdependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement然后再引入两个 starter。一个是模型接入我用的是 OpenAI 兼容接口的 starter因为这是最通用、Key 最好申请的方案另一个是 pgvector 向量存储的 starterdependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-vector-store-pgvector/artifactId /dependency /dependencies提示如果你用的不是 OpenAI 官方服务而是某个兼容 OpenAI 协议的网关或自建服务只需在配置里把 base-url 指过去模型名改成该服务支持的名称即可。Spring AI 的模型 starter 基本都兼容这一套路。3.2 application.yml里必须写对的配置有了依赖接下来的重点就是配置文件。我刚开始漏了向量维度配置结果插入数据时报维度不匹配折腾了一个多小时。Spring AI 的 pgvector 自动配置会用以下几个关键属性spring: datasource: url: jdbc:postgresql://localhost:5432/ragdb username: postgres password: postgres ai: openai: api-key: ${OPENAI_API_KEY} chat: options: model: gpt-4o-mini embedding: options: model: text-embedding-3-small vectorstore: pgvector: initialize-schema: true dimensions: 1536 distance-type: COSINE_DISTANCE index-type: HNSW说明几个我后来才弄明白的点dimensions必须和你用的 embedding 模型输出维度一致。text-embedding-3-small是 1536 维text-embedding-3-large是 3072 维换模型就得改这里否则插入向量时 PostgreSQL 会直接报错。initialize-schema: true表示让 Spring AI 自动建表。生产环境我建议关掉手动管理表结构但初次实验开着省事。distance-type和index-type决定相似度计算方式与索引结构我会在第 4 节细讲。datasource用的是普通 PostgreSQL 数据源不需要额外引入 JPASpring AI 的 JdbcVectorStore 会自动复用这个数据源。到这里一个能启动的 Spring Boot 项目就准备好了。你不需要写任何代码直接运行如果控制台没有报错说明自动配置已经生效。4. 数据库侧准备pgvector扩展与Spring AI表结构4.1 启用扩展与手动建表Spring AI 虽然能自动建表但它不会替你执行CREATE EXTENSION。因为启用扩展需要 PostgreSQL 实例层面的权限应用层的自动配置无法决定。所以你要先手动把扩展装好CREATE EXTENSION IF NOT EXISTS vector;这条语句执行成功后PostgreSQL 才拥有vector(n)这种类型。如果跳过这一步后面建表会报type vector does not exist这是新手最常见的第一个数据库报错。我实际开发时不喜欢完全依赖自动建表因为自动建的表结构往往是能用但不够用。比如我想给文档块加来源文件、分类标签这些业务元数据自动建表虽然支持 metadata 字段但索引和约束不一定符合我的要求。所以我通常会把自动建表关掉自己执行建表语句。Spring AI 1.0 默认表名是vector_store核心结构如下CREATE TABLE IF NOT EXISTS vector_store ( id UUID PRIMARY KEY, content TEXT, metadata JSONB, embedding vector(1536) );如果你用的是initialize-schema: trueSpring AI 会自动创建一个几乎一样的表你不需要手写。但理解这张表的结构很重要它能帮你排查很多问题。4.2 距离算法与索引类型怎么选pgvector 支持三种距离算法Spring AI 里通过distance-type配置。我整理了一个对照表配置值计算方式适用场景说明COSINE_DISTANCE余弦距离文本语义检索首选关注方向上的相似度对文本长度不敏感EUCLIDEAN_DISTANCE欧氏距离向量数值本身更有意义时对向量长度敏感文本使用较少NEGATIVE_INNER_PRODUCT负内积追求极速匹配时数学上最省计算量但需要向量归一化配合零基础阶段直接用 COSINE_DISTANCE 就好它和语义相似度的直觉最匹配。索引类型主流是 HNSW 和 IVFFlat。HNSW 是近似的图索引构建慢但查询快、召回率高适合中小规模数据IVFFlat 需要先有数据做训练聚类调参多一些。我推荐默认 HNSW特别是你还在学习阶段少一个变量就少一份坑。注意索引只有在数据量大时才有意义。几千条以内全表扫描也很快但既然 Spring AI 配置里提供了选项从第一天就按正确姿势搭避免以后数据量上来再回头折腾。4.3 Spring AI的自动建表策略我见过不少同学把initialize-schema一直开着部署到生产还让应用自动改表结构这是隐性风险。因为 Spring AI 升级后自动建表脚本可能变化线上如果已经存在同名表不同版本的建表脚本之间可能出现字段差异。我的建议是本地学习阶段开着方便进入联调阶段就改成false把表结构纳入你的数据库迁移脚本里管理比如 Flyway/Liquibase。另外有个细节Spring AI 的 metadata 字段是 JSONB 格式可以存任意键值对。但你存进去的每个键后面做过滤检索时都会被解析成条件。所以设计 metadata 时要有意识地控制键数量比如只放source来源、category分类、version版本号这类常用维度别把一堆无关字段塞进去。5. 核心三步实战文档入库、相似度检索、增强问答现在进入正题。我用一个最小可运行的模拟项目来演示有一批产品说明文档我希望用户在页面上提问后系统能根据文档内容回答。全程只用一个 Service 类和一个 Controller刻意不铺太多工程化结构先把逻辑讲透。5.1 第一步加载文档并按语义切分文档加载比较简单你自己用 Java 读文件、读字符串、甚至从一个 HTTP 接口拿文本都行。Spring AI 提供了一个Document类型一个 Document 就是一篇文本附带 metadata。比如我把模拟项目里的产品手册读进来Document doc new Document( 智能门锁X2支持指纹、密码、NFC三种开锁方式……, Map.of(source, product-manual.md, category, user_manual) );难点在切分。一个新手的常见做法是把整篇文档丢给模型结果要么超出上下文长度要么回答时什么都想引用、泛泛而谈。切分的核心思想是把长文档切成有独立语义的小块同时让相邻块之间保留一点重叠避免语义在切缝处被截断。var splitter TokenTextSplitter.builder() .withChunkSize(400) .withChunkOverlap(80) .build(); ListDocument chunks splitter.apply(List.of(doc));这里chunkSize指每块大约多少个 tokenchunkOverlap是相邻块重叠的部分。为什么要重叠因为一段话被切成两块后可能在分界处丢掉关键上下文。比如密码支持临时密码这句话如果临时在上一块末尾、密码在下一块开头两块单独看都会语义残缺。重叠相当于给检索留了缓冲带。切分尺寸没有绝对标准。我的经验是中文场景下400 到 600 token 比较均衡太大则检索颗粒度粗太小则每个块携带的上下文太少。你可以先按这个配置跑观察检索效果再调。5.2 第二步向量化入库切好的 chunks 要转成向量存进 PostgreSQL。Spring AI 的VectorStore接口把这步封装得极其简单Autowired private VectorStore vectorStore; public void storeDocuments(ListDocument chunks) { vectorStore.add(chunks); }add方法内部会调用自动配置好的EmbeddingModel给每个 Document 生成向量然后批量写入数据库。你不需要自己拼接 SQL、不需要管理事务这些 Spring AI 都处理了。写入后去数据库查一下vector_store表能看到每条记录都有 id、content、metadata 和一个很长的向量数组字段。这里有个值得注意的演进Spring AI 1.0 里VectorStore是顶层接口pgvector 实现类会自动从数据源 配置参数构建。你要做的只是在某个配置类里确认这个 Bean 存在或者干脆什么都不做直接注入使用。如果你在启动时发现VectorStore注入失败最可能的原因是 pgvector starter 没引入或者 datasource 配置没生效。5.3 第三步相似度检索检索是 RAG 的核心。这步做得好不好直接决定最终回答的质量。检索输入是用户的问题输出是最相关的 N 个文档块。Spring AI 用SearchRequest来表达检索条件public ListDocument search(String question) { SearchRequest request SearchRequest.builder() .query(question) .withTopK(5) .withSimilarityThreshold(0.7) .build(); return vectorStore.similaritySearch(request); }解释两个参数topK返回最相似的几块。5 是常见起步值资料丰富或问题复杂时可以调到 8-10但别贪多塞太多不相关内容给模型反而容易让它跑偏。similarityThreshold相似度阈值。Spring AI 里 similarity 范围一般是 0 到 1越接近 1 越相关。设成 0.7 表示低于这个相似度的结果不要能过滤明显无关的块。我习惯把这两个参数做成可配置因为不同文档集的表现差异很大。有的文档术语统一、写得好0.8 阈值都很准有的文档口语化严重0.6 都捞不到东西。调参方法后面单独讲。5.4 用ChatClient组装增强问答检索到的文档块只是原材料最终回答要靠 ChatClient 生成。我推荐零基础先走手动拼接上下文的路线因为能把整条数据流看得清清楚楚而不建议一上来就用那些全自动 Advisor 封装。手动方案的核心就两步把检索结果拼进系统提示词再把用户问题传进去。Autowired private ChatClient chatClient; public String answer(String question) { ListDocument docs search(question); String context docs.stream() .map(Document::getText) .collect(Collectors.joining(\n\n---\n\n)); return chatClient.prompt() .system(你是一个严谨的客服助手。只能依据下方资料回答资料中没有的信息请明确回答资料中未找到。\n\n资料\n context) .user(question) .call() .content(); }这段代码里最关键的是 system 提示词。只能依据下方资料回答是约束力最强的句子少了它模型就会放飞自我拿自己训练时的知识乱编。我实际测试过一个对照加了这句回答基本贴着资料走不加这句模型开始自由发挥甚至编出完全不存在的信息。这个约束不是万无一失但却是成本最低的一道护栏。如果你想要更官方的做法Spring AI 也提供了QuestionAnswerAdvisor可以在查询阶段自动注入相似文档ChatClient chatClient ChatClient.builder(chatModel) .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore)) .build();但我建议先把手动方案跑通理解 data flow 之后再换封装这样出问题时你才知道问题出在检索环节还是生成环节。6. 实测效果、调参路径与避坑记录到这里一个能跑的 RAG 闭环已经完成。但能跑和好用之间隔着一堆调参和排错经验。这一节把我实测过程中遇到的高频问题按排查思路写出来方便你复现。6.1 检索效果不准时按这个顺序排查我第一版跑出来的效果非常糟糕问门锁怎么设置临时密码返回的文档块却是介绍 NFC 开锁的。当时我以为模型不行后来逐步排查才发现罪魁祸首是切分不合理。现在我的排查顺序是固定的先看检索结果本身对不对。我把search()返回的文档块直接打印出来看发现返回的块确实和问题不相关问题在检索而不是生成。再确认是切分问题还是向量问题。手动把问题门锁怎么设置临时密码和一个正确文档块、一个错误文档块的向量相似度打出来对比发现正确块和错误块的相似度差距很小说明向量本身没能拉开距离。回头看切分逻辑发现chunkSize设得过大一块里混杂了开锁、密码、电池更换三段内容语义被冲淡了。把切分调小并保留重叠后检索结果立刻变干净。这个排查链路的价值在于先分清楚是检索的锅还是生成的锅再往深处定位。如果你跳过第一步直接去改提示词很可能白忙一场。6.2 中文场景的切分和元数据过滤中文文档和英文文档的切分差异是我在实际中体会最深的一点。英文天然按空格分词TokenTextSplitter的表现很稳定中文没有空格边界虽然 tokenizer 本身能处理但切出来的块语义完整性还是需要人工验证。我的经验是让块尽量按自然段落边界切而不是机械地按长度切。如果文档本身有标题结构可以按标题把文档先分成大节再对大节内部做切分这样每个块天然围绕一个主题检索命中率会明显提升。另外一个实用的技巧是元数据过滤。当知识库里有多种类型的文档时产品手册、FAQ、技术公告靠纯向量相似度会互相干扰。我在 search 方法里加上分类过滤SearchRequest request SearchRequest.builder() .query(question) .withTopK(5) .withFilterExpression(category user_manual) .withSimilarityThreshold(0.7) .build();这样检索只在指定分类内部进行效果比让向量自己辨认分类稳定得多。Spring AI 的过滤表达式支持、!、、||这些常见操作符和写 if 条件差不多。6.3 必须绕开的几个坑我把整个搭建过程中遇到的最典型的坑汇总成一个表按出现概率排序报错或异常现象原因解决办法type vector does not exist没有 CREATE EXTENSION vector先在数据库执行扩展语句different vector dimensionsembedding 模型维度与表结构/配置不一致统一 dimensions 配置与建表语句401 鉴权失败api-key 没配或配错base-url 不对检查环境变量与 application.yml启动时 VectorStore Bean 注入失败少了 pgvector starter 或 datasource 未生效核对依赖与数据源配置检索结果全是不相关内容chunkSize 太大、重叠太少、阈值太松重新调切分参数看检索输出空文档块导致写入报错切分结果可能过滤出空字符串写入前过滤 content 为空的块还有一个隐蔽坑metadata 里如果存了null值或非标准 JSON 类型过滤表达式解析时容易报错。我在模拟项目里曾经把某个字段存成数字结果过滤表达式里写字符串比较就出问题。建议 metadata 的值统一成字符串或布尔型减少解析歧义。6.4 让问答再稳一点的小技巧最后一个阶段性的优化点是让模型知道哪些不能说。在 system 提示词里加上资料中没有的信息请明确回答资料中未找到看起来简单实际效果非常明显。没有这句约束时模型倾向于把检索到的一点相关内容扩写成完整的、煞有介事的答案这在客服场景是不可接受的。加了这句之后模型会更保守宁可不答也不乱编。更进一步的思路是在前端或者后置校验里做引用溯源让模型在回答末尾标注依据的文档块编号人工抽查时能随时反查原始文档。这个需求不用改架构只需在提示词里要求它输出引用标记并在返回结果里透传来源 metadata 就行。它不提升模型能力却能让整个系统的可信度上一个台阶。最后分享两个我在实际操作中的体会。第一别急着换向量数据库或者换模型RAG 效果的大头在数据质量切分是否合理、文档是否整洁、metadata 是否规范。这些做好之后再考虑模型和索引调优。第二建议你从第一天就给topK、similarityThreshold、chunkSize做配置文件化。我最初直接写死在代码里后来调参时改一次代码重启一次效率极低抽成配置项后调参变成改配置、重启、看结果的三步循环。这套 Spring AI PostgreSQL 的组合最大的优点就是把复杂链路收敛在一个应用、一个数据库里让你把有限的注意力放在真正影响效果的地方——数据切分和检索质量。