1. Java 开发者切入 AI 的真实路径拆解1.1 为什么 Java 开发者不需要从零学 Python我做了十多年 Java 后端这两年身边问得最多的一句话就是“搞 AI 是不是必须转 Python”每次我都直接说不用。原因很简单AI 应用落地分两层一层是模型训练和微调那确实是 Python 的主场另一层是把大模型能力集成进业务系统也就是常说的 AI 应用工程化这一层 Java 不但不弱反而在稳定性、并发、事务、可观测性上有天然优势。你想想一个企业级系统要接入大模型它需要什么需要鉴权、限流、熔断、日志、监控、事务一致性、多租户隔离这些全是 Java 后端玩了二十年的东西。Python 写个 demo 很快但真上生产高并发下的连接池管理、流式响应的背压处理、向量库的读写一致性这些坑 Java 生态反而更成熟。所以 Java 开发者入门 AI 的正确姿势不是去啃 Transformer 论文而是把 AI 当成一个新的下游依赖来集成用你已有的工程能力去驾驭它。这条路线图我给它分成四步第一步跑通一次大模型 API 调用理解 token、temperature、流式返回这些基本概念第二步引入 Spring AI 或 LangChain4j 做框架封装把裸调用变成可维护的代码第三步接入 RAG 知识库让模型能回答你私有数据的问题第四步做 Agent 编排让模型能调用工具、多步推理。这四步走完你就是一个合格的 AI 应用工程师了跟会不会 Python 没关系。提示别一上来就买 GPU 服务器或者研究本地部署大模型。先用云端 API 把整条链路跑通成本几块钱理解成本最低。本地部署是后面优化成本和数据隐私时才考虑的事。1.2 路线图四阶段的能力对照我把这四个阶段对应的技术点、产出物和常见误区整理成一张表你可以对照自己的进度看卡在哪一层。阶段核心技术点产出物常见误区阶段一裸调用HTTP 客户端、JSON 解析、SSE 流式一个能对话的接口把 API Key 硬编码进代码阶段二框架封装Spring AI、LangChain4j、Prompt 模板可复用的 Service 层过度封装把简单调用搞复杂阶段三RAG向量库、Embedding、切片、召回私有知识问答切片策略一刀切召回率低阶段四Agent工具调用、多步编排、记忆能自主完成任务的智能体无脑上 Agent简单问题复杂化这张表是我踩过坑之后总结的。阶段一最容易犯的错是密钥管理我见过有人把 Key 提交到 Git 仓库第二天账单跑了几千块。阶段二最容易犯的错是为了用框架而用框架一个简单的问答接口套了五层抽象改个 Prompt 要翻三个文件。阶段三的坑最多后面我会专门用一章讲。阶段四则是很多人还没到那一步就急着上结果做出来的东西还不如一个写死的 if-else 靠谱。1.3 工具链选型的核心逻辑工具链这块Java 生态目前主流就两条线Spring AI和LangChain4j。经常有人问我到底选哪个我的回答是看你的项目底座。如果你的项目本来就是 Spring Boot 体系团队熟悉 Spring 那套注解和自动装配那 Spring AI 上手几乎零成本它跟 Spring Boot 的集成度非常高配置写在 application.yml 里注入一个 ChatClient 就能用。如果你的项目不是 Spring 体系或者你需要更灵活的链式编排、更丰富的模型适配那 LangChain4j 更合适它的 API 设计更贴近 LangChain 的思路模块化程度高。还有一个维度是模型供应商的适配广度。Spring AI 对 OpenAI、Azure OpenAI、Ollama 这些支持得很好国内的通义千问、智谱也都有对应的 starter。LangChain4j 的适配层做得更细很多小众模型和向量库它都有现成实现。我的建议是新项目且是 Spring 体系直接 Spring AI需要复杂编排或非 Spring 体系选 LangChain4j。两者不是互斥的我甚至见过一个项目里 RAG 部分用 LangChain4j业务集成用 Spring AI各取所长。至于向量库入门阶段我强烈建议先用内存向量库或者 Ollama 自带的简易方案别一上来就上 Milvus、Weaviate 这些分布式向量库。原因很简单你连召回率都没调明白上分布式库只是增加运维负担。等数据量到百万级、需要持久化和高可用的时候再迁移迁移成本并不高因为主流框架都做了向量库的抽象层。2. Spring AI 与 LangChain4j 核心细节解析2.1 Spring AI 的自动装配机制与实操要点Spring AI 最舒服的地方就是它把大模型调用做成了 Spring 风格的 Bean。你在 pom 里引入spring-ai-openai-spring-boot-starter然后在 application.yml 里配好 api-key 和 base-url容器启动时就会自动装配一个ChatClient.Builder。你只需要在 Service 里注入ChatClient调client.prompt().user(你好).call().content()就能拿到回复。这套东西对 Spring 开发者来说几乎是肌肉记忆。但这里有几个细节必须注意。第一流式返回要用stream()而不是call()返回的是FluxString如果你项目里是 Spring MVC 而不是 WebFlux需要额外处理 SSE 的输出别直接把 Flux 返回给前端会报类型不匹配。第二Prompt 模板建议用.system()和.user()分开写系统提示词定义角色和约束用户提示词放具体问题这样后期调优的时候改哪部分很清晰。第三超时和重试一定要配大模型接口偶尔会抽风默认超时可能长达几十秒生产环境必须设置合理的 connectTimeout 和 readTimeout配合 Resilience4j 做重试和熔断。我实测下来Spring AI 的ChatClient支持一种叫Advisors的机制可以在调用前后插入逻辑比如对话记忆、RAG 检索、日志记录都可以做成 Advisor。这个设计非常优雅相当于给大模型调用加了一层 AOP。比如你要加对话记忆引入MessageChatMemoryAdvisor指定一个ChatMemory实现它就会自动把历史消息带上。这比你自己手动拼历史消息清爽太多。Configuration public class AiConfig { Bean public ChatClient chatClient(ChatClient.Builder builder, ChatMemory memory) { return builder .defaultSystem(你是一个严谨的技术助手回答要准确简洁) .defaultAdvisors(new MessageChatMemoryAdvisor(memory)) .build(); } }上面这段配置就是典型的 Spring AI 用法defaultSystem设默认人设defaultAdvisors挂记忆。注意ChatMemory的实现入门用InMemoryChatMemory就行但生产环境要换成基于 Redis 的实现否则重启就丢历史而且多实例部署时内存版根本不共享。2.2 LangChain4j 的链式编排与 RAG 集成LangChain4j 的设计哲学跟 Spring AI 不太一样它更强调组件化和显式编排。你要构建一个 RAG 应用在 LangChain4j 里是这样一条链DocumentLoader加载文档DocumentSplitter切片EmbeddingModel向量化EmbeddingStore存储检索时用EmbeddingStoreContentRetriever召回最后拼进 Prompt 交给ChatLanguageModel。每一步都是显式的你能清楚看到数据怎么流动。这种显式的好处是调试方便。RAG 效果不好的时候你可以逐段排查是切片切坏了是 Embedding 模型选错了还是召回数量不够Spring AI 的 Advisor 机制虽然优雅但黑盒感更强出问题不好定位。所以我的经验是做 RAG 调优的时候LangChain4j 的显式链更好用做业务集成的时候Spring AI 的自动装配更省事。LangChain4j 里有个很好用的东西叫AiServices你可以定义一个接口用注解标注哪些方法要走大模型框架会自动生成实现。比如interface Assistant { SystemMessage(你是一个 Java 技术专家) String chat(UserMessage String question); }然后AiServices.create(Assistant.class, chatModel)就能拿到实例。这个模式对 Java 开发者特别友好因为它是面向接口的符合我们平时的编程习惯。你还可以在接口方法上挂Tool注解定义工具让模型在需要的时候调用这就是 Agent 的雏形。2.3 两者选型的决策清单我把选型决策整理成一个清单你对着自己的情况勾一下就知道选哪个了。项目是 Spring Boot 体系团队熟悉 Spring 注解优先 Spring AI需要复杂的多步链式编排、条件分支优先 LangChain4j需要接入大量小众模型或向量库优先 LangChain4j团队里有非 Java 背景、看过 LangChain 文档的LangChain4j 概念更接近追求最少代码量快速上线Spring AI需要精细控制 RAG 每一环做调优LangChain4j还有一个现实因素社区活跃度和文档。Spring AI 背靠 Spring 官方版本迭代快文档规范但有些新特性还在演进中API 偶尔有破坏性变更。LangChain4j 社区驱动迭代也快文档相对零散一些但示例代码多。我个人的做法是两个都跑一遍 demo各花半天时间跑完你自然就有感觉了比看十篇对比文章都管用。注意无论选哪个都要把大模型调用封装在一个独立的 Service 层后面业务代码只依赖你自己的接口不直接依赖框架的类。这样将来换框架或者换模型改动范围可控。我见过直接把 ChatClient 注入到 Controller 里的项目后来换模型供应商改了几十个文件。3. RAG 知识库从零搭建的完整实操3.1 RAG 到底解决了什么问题先说清楚 RAG 是什么。大模型的知识来自训练数据有两个硬伤一是知识有截止日期训练完之后发生的事它不知道二是不知道你的私有数据你公司的内部文档、产品手册它一概不知。你直接问它它要么说不知道要么一本正经地胡说八道这就是幻觉。RAG 的思路很朴素既然模型不知道那我查出来喂给它。用户提问时先把问题向量化去知识库里检索最相关的几段内容然后把这几段内容连同问题一起塞进 Prompt让模型基于这些材料回答。这样模型不需要记住你的数据只需要具备阅读理解能力就行。打个比方这就像开卷考试模型是考生知识库是参考书RAG 就是考前帮你翻到正确页码的那个动作。RAG 的核心指标是召回率hit rate也就是该被检索出来的内容有没有被检索出来。召回率上不去后面模型再强也白搭因为材料根本没喂对。很多人 RAG 效果差问题都出在召回环节而不是模型环节。所以下面我重点讲切片和召回这两个最容易翻车的地方。3.2 文档切片策略与参数计算切片是 RAG 的第一道关也是最容易被忽视的一关。所谓切片就是把长文档切成一段段小块每块单独向量化存储。为什么要切因为向量化模型有 token 上限而且整篇文档向量化成一个点检索精度极低相当于把一本书压成一个摘要去查什么都查不准。切片的核心参数是块大小chunk size和重叠长度overlap。块太小语义不完整比如一句话被切成两半检索出来缺上下文块太大噪声多一个块里混了好几个主题向量表达不纯粹。我的经验值是中文文档块大小 300 到 500 字重叠 50 到 100 字。重叠的作用是防止关键信息正好卡在切割边界上被切断前后两块都带一点保证语义连续。但这不是死规矩。技术文档、API 文档适合按结构切比如按标题层级切一个二级标题下的内容作为一块这样语义天然完整。对话记录、会议纪要适合按轮次切一问一答作为一块。法律合同、论文适合按段落切因为段落本身就是语义单元。一刀切按固定字数切是最省事但效果最差的做法我建议至少按文档类型做差异化处理。还有一个进阶技巧叫父子切片存的时候存小块保证检索精度但喂给模型的时候喂它所属的大块保证上下文完整。LangChain4j 里有ParentDocumentRetriever支持这种模式。这个技巧在长文档问答场景下提升非常明显我实测召回率能提升百分之二三十。3.3 向量化与召回环节的实操细节向量化就是把文本变成一串浮点数语义相近的文本在向量空间里距离近。选 Embedding 模型有几个考量维度、语言支持、成本。维度越高表达能力越强但存储和计算成本越高常见的有 768 维、1024 维、1536 维。中文场景一定要选对中文优化过的模型拿英文模型跑中文效果会打折扣。召回环节有几个参数要调。TopK是召回几条默认 3 到 5 条太少可能漏太多会引入噪声稀释重点。相似度阈值是过滤掉太不相关的结果低于阈值的不返回避免硬凑材料。混合检索是把向量检索和关键词检索结合向量擅长语义匹配关键词擅长精确匹配两者互补。比如用户问一个具体的错误码关键词检索能精确命中向量检索可能因为语义泛化反而漏掉。我踩过的一个坑是元数据过滤。知识库里往往有多个来源的文档检索时如果不加过滤可能召回一堆不相关来源的内容。解决办法是给每个切片打上元数据标签比如来源、部门、版本检索时带上过滤条件。LangChain4j 的EmbeddingStoreContentRetriever支持filter参数用起来很方便。ContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.7) .dynamicFilter(query - metadataFilter(query)) .build();上面这段就是典型的召回配置maxResults控制 TopKminScore控制阈值dynamicFilter做元数据过滤。注意minScore别设太高0.7 到 0.8 比较稳妥设到 0.9 可能什么都召不回来。3.4 一个可复制的本地 RAG 最小实现我用 Ollama 加 LangChain4j 搭一个最小可用的本地 RAG零成本适合入门练手。Ollama 负责跑本地模型和 EmbeddingLangChain4j 负责编排。步骤是这样的第一步装好 Ollama拉两个模型一个对话模型一个 Embedding 模型。对话模型选参数量小一点的本地跑得动Embedding 模型选专门做向量化的。第二步引入 LangChain4j 的依赖包括核心包、Ollama 适配包、内存向量库包。第三步写加载和切片逻辑把本地文档读进来切成块。第四步向量化并存入内存向量库。第五步构建检索器和对话服务把检索到的内容拼进 Prompt。// 加载并切片 DocumentSplitter splitter DocumentSplitters.recursive(400, 80); ListDocument docs FileSystemDocumentLoader.loadDocuments(/path/to/docs, splitter); // 向量化入库 EmbeddingModel embeddingModel OllamaEmbeddingModel.builder() .baseUrl(http://localhost:11434) .modelName(nomic-embed-text) .build(); EmbeddingStoreTextSegment store new InMemoryEmbeddingStore(); EmbeddingStoreIngestor.ingest(docs, store, embeddingModel); // 构建检索增强的对话服务 ContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(4) .minScore(0.7) .build(); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .contentRetriever(retriever) .build();这套代码跑起来你就能问它本地文档里的问题了。虽然模型能力比不上云端大模型但整条链路是完整的理解 RAG 足够了。等你要上生产把 Ollama 换成云端 API把内存向量库换成持久化的其他代码几乎不用动这就是框架抽象层的好处。提示本地跑模型对内存要求不低对话模型建议选 7B 以下的量化版本Embedding 模型一般几百 MB压力不大。如果机器实在跑不动Embedding 也可以用云端 API只把对话模型放本地。4. 常见问题与排查技巧实录4.1 RAG 召回率低的排查思路召回率低是 RAG 最头疼的问题表现是模型答非所问或者直接说不知道。排查要按链路顺序来别乱猜。我的排查顺序是先看切片再看向量化最后看召回参数。看切片把切好的块打印出来人工读一遍看语义是否完整。如果发现块被切得七零八落那就是切片参数问题调大块大小或者换切片策略。看向量化拿一个已知答案的问题手动算它的向量跟知识库里对应块的向量算相似度如果相似度很低说明 Embedding 模型不适合你的语料换模型。看召回参数把 TopK 调大试试如果调大后能召回正确答案说明是 TopK 太小如果调大后还是不行那就是前面两步的问题。我整理了一个速查表对着症状找原因。症状可能原因解决方向完全召不回相关内容切片太碎或 Embedding 模型不匹配调大块大小换中文优化模型召回了但排序靠后相似度计算受噪声干扰加元数据过滤用混合检索召回内容重复重叠长度过大减小 overlap召回内容缺上下文块太小用父子切片喂大块特定问题总答错该内容未被正确切片检查该文档的切片结果4.2 大模型调用超时与限流的处理生产环境调大模型超时和限流是绕不开的。大模型推理本身耗时尤其是长文本生成几秒到几十秒都正常。默认的 HTTP 超时往往不够必须显式设置。我的经验是connectTimeout 设 10 秒readTimeout 设 60 秒流式返回的话 readTimeout 可以更长因为它是持续有数据回来的。限流方面云端 API 一般有 QPS 和 TPM每分钟 token 数限制。超了会返回 429这时候要退避重试别硬刚。用 Resilience4j 的Retry配合指数退避第一次等 1 秒第二次 2 秒第三次 4 秒最多重试三次。同时要配RateLimiter做客户端限流主动控制发送速率别等服务端拒绝。还有一个容易被忽视的点是连接池。大模型调用是 IO 密集型连接池要设够但也不能无限大否则会把服务端打挂。一般设 20 到 50 个连接足够。另外流式响应一定要处理背压如果客户端消费慢服务端还在猛推内存会涨。WebFlux 的 Flux 天然支持背压但如果你用阻塞式写法就要自己控制。4.3 数据一致性与事务的坑Java 开发者习惯用事务保证一致性但大模型调用不能放在数据库事务里。原因很简单大模型调用可能耗时几十秒把事务拖这么长数据库连接会被占满锁也一直不释放整个系统都会卡。正确做法是先提交业务事务再异步调大模型或者把大模型调用放在事务外用补偿机制处理失败。还有一个坑是对话记忆的并发问题。同一个用户的多轮对话如果并发请求历史消息可能乱序。解决办法是给每个会话加锁或者用带版本号的记忆存储保证消息顺序。我见过一个项目因为这个问题用户看到的历史消息顺序是乱的体验很差。向量库的写入也有一致性问题。文档更新时旧向量要删、新向量要加这两个操作如果不是原子的中间可能出现检索到旧数据的情况。生产环境建议用支持事务的向量库或者用版本号标记检索时只取最新版本。4.4 成本控制的几个实用技巧大模型调用是按 token 计费的用不好成本会失控。几个实用技巧第一Prompt 要精简别把无关内容塞进去尤其是 RAG 召回的块TopK 别设太大召回的内容都是要计费的。第二简单问题用小模型复杂问题才用大模型可以做路由先让小模型判断难度。第三缓存高频问题相同问题直接返回缓存结果别重复调用。第四设置用量告警每天 token 消耗超过阈值就报警防止异常调用。我实测下来一个中等规模的 RAG 应用做好缓存和路由成本能降一半以上。缓存这块可以用问题文本的哈希做 key也可以用问题的向量做语义缓存后者能命中语义相同但表述不同的问题命中率更高。注意语义缓存要设过期时间因为知识库更新后旧答案可能失效。一般设几小时到一天比较合适具体看知识更新频率。5. 从 RAG 到 Agent 的进阶方向5.1 Agent 的本质与适用边界RAG 解决的是“知道”的问题Agent 解决的是“做到”的问题。Agent 的核心是让模型能调用工具、多步推理、根据中间结果决定下一步。比如用户说“帮我查一下上个月的销售数据并生成报表”Agent 会先调用查数据的工具拿到结果后再调用生成报表的工具最后返回文件。这一系列动作是模型自己编排的不是你写死的流程。但我要泼一盆冷水不是所有场景都适合 Agent。如果流程是固定的比如“查天气就调天气接口”那写死一个 if-else 比 Agent 靠谱得多又快又稳又便宜。Agent 的价值在于流程不确定、需要模型动态决策的场景。我见过太多项目为了显得“智能”硬上 Agent结果简单问题绕一大圈还经常调错工具体验反而不如传统方案。判断要不要用 Agent问自己三个问题流程是否固定工具调用顺序是否可预测错误容忍度是否高如果流程固定、顺序可预测、错误容忍度低那就别用 Agent。反之才考虑。5.2 工具调用的实现要点Agent 的工具调用在 LangChain4j 里用Tool注解实现。你定义一个方法加上注解描述清楚这个工具是干什么的、参数是什么模型就会在需要的时候调用它。关键是工具描述要写清楚模型是根据描述来决定调不调的描述模糊它就不敢调或者调错。public class SalesTools { Tool(根据月份查询销售总额月份格式为 yyyy-MM) public BigDecimal querySales(P(月份) String month) { // 实际查询逻辑 } }上面这个工具描述里写清楚了功能和参数格式模型就能正确调用。如果只写“查询销售”模型可能不知道该传什么参数。工具的参数校验也要做模型可能传错格式你的方法要能兜住返回友好的错误信息让模型重试。还有一个要点是工具数量别太多。工具一多模型选择困难容易调错。我的经验是单个 Agent 的工具控制在 5 到 10 个以内多了就拆分成多个 Agent用路由分发。这跟人一样一个人同时记太多工具也会乱。5.3 多步推理与记忆管理Agent 的多步推理本质是把之前的工具调用结果作为上下文让模型决定下一步。这里的关键是记忆管理哪些历史要保留哪些要丢弃。全保留会撑爆上下文窗口全丢弃又丢失了推理链条。常见做法是保留最近 N 轮或者用摘要压缩历史。LangChain4j 里有ChatMemory的多种实现MessageWindowChatMemory保留最近 N 条消息TokenWindowChatMemory按 token 数保留。Agent 场景我建议用 token 窗口因为工具调用的结果可能很长按条数算不准。另外工具调用的中间结果要不要进记忆这个要权衡。进了记忆模型能看到完整推理链但占 token不进记忆省 token 但模型可能重复调用同一个工具。我个人的做法是工具调用的入参和结果摘要进记忆完整结果不进。这样模型知道调过什么、大概结果是什么但不会因为完整结果太长而撑爆窗口。这个策略在实际项目里效果不错既保证了推理连续性又控制了成本。5.4 进阶路线的小结与个人体会从 RAG 到 Agent我的建议是先把 RAG 做扎实再上 Agent。RAG 是 Agent 的基础Agent 调工具很多时候也是在检索信息。RAG 的召回、切片、向量化这些基本功没练好直接上 Agent 就是空中楼阁。我见过不少项目RAG 还没调明白就急着做 Agent结果 Agent 调工具查出来的信息都是错的整个链路全崩。最后分享一个我自己的体会AI 应用工程化八成的功夫在工程两成在模型。模型能力是现成的你调不调它都在那里但怎么把它的能力稳定、可靠、低成本地集成进业务系统这才是 Java 开发者的价值所在。别被那些“AI 取代程序员”的论调吓到真正被取代的是不会用 AI 的程序员而会用 AI 的 Java 工程师现在正是稀缺的时候。把上面这条路线走一遍你手里就多了一张很有分量的牌。