如果你是一個 Java 后端工程師過去一年里大概率經(jīng)歷過這樣的焦慮打開技術社區(qū)滿眼都是 Python 寫的 LangChain、LlamaIndex、AutoGPT打開招聘軟件AI 應用開發(fā)的崗位要求里寫滿了 Transformers、PyTorch、RAG好像 Java 開發(fā)者瞬間被排除在 AI 時代之外。但事實并不是這樣。Java 生態(tài)里不僅有 Spring AI 和 Langchain4j 兩條成熟的技術路線而且它們在工具調(diào)用、RAG 知識庫、Agent 編排這些核心場景上已經(jīng)能做出不輸 Python 生態(tài)的生產(chǎn)級應用。只是中文社區(qū)里系統(tǒng)性的教程太少了大多數(shù)資料要么是官方文檔的翻譯腔要么是只講 Demo 不講原理的碎片代碼。這篇文章不會帶你從頭啃官方文檔。我會圍繞 Spring AI 和 Langchain4j把 Tools、RAG、Agent 這三塊真正核心的內(nèi)容拆開講清楚它們各自解決什么問題、怎么在 Java 項目里落地、有哪些容易踩的坑。如果你想從 0 到 1 掌握 Java 生態(tài)的大模型應用開發(fā)這篇文章可以作為一個完整的起點。1. 這篇文章真正要解決的問題先做一個判斷Java 開發(fā)者學習 AI 應用開發(fā)真正的困難不在模型不在算法而在工程化思維方式的轉變。過去我們寫 CRUD 接口核心是把確定性的請求映射到確定性的響應。但接入大模型之后系統(tǒng)的輸入是自然語言輸出是無法 100% 預判的文本中間還夾雜著工具調(diào)用、知識檢索、多步推理。這種“不確定性的代碼”怎么寫、怎么測、怎么容錯才是 Java 開發(fā)者最陌生也最需要補課的地方。這篇文章要解決的就是這四件事Spring AI 和 Langchain4j 到底怎么選它們不是競爭關系而是各有側重的兩條路線選錯會直接影響后面的開發(fā)效率。Tools 工具調(diào)用到底在做什么很多人以為工具調(diào)用就是寫個 API 讓模型去請求實際上它改變的是模型與外部系統(tǒng)的交互方式。RAG 知識庫的核心鏈路怎么搭從文檔加載、切分、向量化、存儲到檢索和重排每一環(huán)都可能成為瓶頸。Agent 和普通代碼邏輯的邊界在哪里什么時候該用 Agent什么時候不該用這是工程上最容易被忽略的問題。讀完這篇文章你應該能獨立搭建一個包含知識庫問答和工具調(diào)用的 Java AI 應用并且能說清楚每個環(huán)節(jié)的原理和常見坑。2. Spring AI 與 Langchain4jJava 大模型開發(fā)的兩條主流路線在正式開始寫代碼之前先把兩個框架的關系理清楚。這也是很多初學者第一個困惑的地方。Spring AI是 Spring 官方生態(tài)的一部分定位是“把 AI 能力以 Spring Boot 的方式接入 Java 應用”。它提供了統(tǒng)一的 ChatClient、EmbeddingModel、VectorStore 等抽象讓開發(fā)者就像寫 JdbcTemplate 一樣去調(diào)用大模型。如果你已經(jīng)深度使用 Spring BootSpring AI 的學習成本會非常低。Langchain4j則是對標 Python 生態(tài) LangChain 的 Java 實現(xiàn)。它最大的特點是抽象層次更高提供了 AiServices 這種聲明式編程模型。你只需要定義一個接口加幾個注解框架就會自動幫你完成模型調(diào)用、提示詞模板、工具綁定、RAG 檢索這些繁瑣的過程。它們之間不是誰取代誰的關系而是兩個層次的工具如果你喜歡 Spring 官方風格、項目已經(jīng)重度依賴 Spring Boot選 Spring AI 更自然。如果你想要更接近 LangChain 的開發(fā)體驗或者希望聲明式地定義 Agent 服務Langchain4j 的抽象能力會讓你更舒服。從當前生態(tài)來看Spring AI 背靠 Spring 官方版本演進和 Spring Boot 的兼容性做得好Langchain4j 在 Agent、Tool 和 RAG 的封裝上更成熟社區(qū)也很活躍。更穩(wěn)妥的判斷是兩者都值得掌握但先用其中一個跑通一個完整項目再橫向?qū)Ρ攘硪粋€比一開始就糾結選哪個更有價值。3. 核心概念Tools、RAG、Agent 并不是并列關系很多教程把 Tools、RAG、Agent 當作三個獨立的功能模塊來講這會給初學者造成誤解。實際上它們是 AI 應用從簡單到復雜的三個階段理解這個層次關系比記住 API 更重要。3.1 工具調(diào)用讓模型從“會說”到“會做”大模型本質(zhì)上是一個文本生成器它的能力邊界在于“只能輸出文字不能執(zhí)行動作”。比如你問它“幫我查一下訂單 1001 的狀態(tài)”模型如果只憑訓練數(shù)據(jù)它只能給你一個編造的答案因為它根本訪問不到你的數(shù)據(jù)庫。工具調(diào)用Tool Calling / Function Calling解決的就是這個問題把模型和外部系統(tǒng)連接起來。當用戶的問題需要實時數(shù)據(jù)或系統(tǒng)操作時模型會生成一個結構化的調(diào)用請求由應用程序執(zhí)行真正的業(yè)務邏輯再把執(zhí)行結果返回給模型由模型組織最終的回答。它的核心價值在于模型負責“理解意圖、拆分任務、組織回答”而你的 Java 代碼負責“執(zhí)行真實的業(yè)務邏輯”。職責邊界非常清晰。3.2 RAG給模型插上外部知識工具調(diào)用解決的是“實時操作”的問題RAG 解決的是“知識獲取”的問題。大模型的訓練數(shù)據(jù)是有截止時間的而且不包含你公司的私有數(shù)據(jù)。如果你直接問模型“我們公司的請假流程是什么”它只能瞎編。RAGRetrieval-Augmented Generation檢索增強生成的思路是先把文檔切分成小塊轉成向量存入向量數(shù)據(jù)庫用戶提問時先從向量庫中檢索出最相關的文檔片段把這些片段拼進提示詞再讓模型基于這些片段來回答。它的優(yōu)勢在于不需要重新訓練模型只需要更新文檔庫就能讓模型掌握新知識而且回答可以追溯到具體的文檔來源這對企業(yè)場景非常重要。3.3 Agent從單次回答到多步任務如果說 Tools 是讓模型能“動手”RAG 是讓模型有“知識”那 Agent 就是給模型裝上了“大腦”和“計劃能力”。Agent 的核心特征是循環(huán)模型分析任務、決定調(diào)用哪個工具、執(zhí)行工具、觀察結果、決定下一步行動直到完成目標。一個典型的 Agent 場景是用戶說“幫我整理上季度的銷售報告重點分析華東區(qū)數(shù)據(jù)然后生成一份摘要發(fā)給我”這個任務需要多次調(diào)用數(shù)據(jù)查詢、計算、甚至發(fā)郵件的工具而且步驟不是預先確定的模型需要根據(jù)每一步的結果動態(tài)調(diào)整計劃。但這里必須提醒一句Agent 不是銀彈。多步循環(huán)意味著更高的延遲、更高的成本、更難以預測的結果。在工程上能夠用固定流程完成的任務永遠不要為了“炫技”而上 Agent。4. 環(huán)境準備與前置條件開始寫代碼之前先確認你的開發(fā)環(huán)境。以下版本信息以實際項目為準本文的重點是演示通用思路。JDK 17 或更高版本Spring Boot 3.x 需要Maven 3.6 或 Gradle 7一個可用的 LLM API 服務可以是 OpenAI、通義千問、DeepSeek或者本地部署的模型服務如果要跑 RAG 示例還需要一個向量數(shù)據(jù)庫Milvus、Redis、PgVector 等都可以本文以 Milvus 為例說明思路IDE 推薦 IntelliJ IDEA方便調(diào)試 Agent 的多次調(diào)用過程如果你的網(wǎng)絡環(huán)境無法直接訪問海外模型服務使用國內(nèi)模型廠商的兼容接口即可Spring AI 和 Langchain4j 都支持通過配置切換模型供應商。這也是 Java 生態(tài)做得比較成熟的地方模型供應商的差異被抽象成了統(tǒng)一的接口。創(chuàng)建 Maven 項目的核心依賴可以參考下面的配置。這里的版本號只做示意建議以你當前使用的框架官方最新穩(wěn)定版為準。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-openai/artifactId version1.0.0/version /dependencyLangchain4j 的依賴方式略有不同它是通過獨立的 starter 引入dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version1.0.0/version /dependency在動手之前先想清楚一個問題你是要做一個“研究性質(zhì)的 Demo”還是要做一個“生產(chǎn)可用的系統(tǒng)”。如果是后者模型的選擇、成本控制、日志鏈路、失敗重試這些工程細節(jié)需要在一開始就納入設計而不是等代碼寫完了再補。5. 動手實現(xiàn)Tools 工具調(diào)用的最小示例從最簡單的場景入手讓模型調(diào)用一個 Java 方法來獲取實時數(shù)據(jù)。這里以一個“查詢當前天氣”的工具為例所有天氣數(shù)據(jù)都是模擬數(shù)據(jù)重點看鏈路如何打通。5.1 定義數(shù)據(jù)記錄// 文件路徑src/main/java/com/example/ai/weather/WeatherInfo.java public record WeatherInfo(String city, double temperature, String description) { }5.2 定義工具類Spring AI 中使用 Tool 注解的方法會自動暴露給模型調(diào)用。每個參數(shù)都要寫清楚描述因為模型是靠描述來理解參數(shù)的語義的。// 文件路徑src/main/java/com/example/ai/weather/WeatherService.java import org.springframework.ai.tool.annotation.Tool; import org.springframework.stereotype.Service; Service public class WeatherService { Tool(description 查詢指定城市的當前天氣) public WeatherInfo getWeather(String city) { // 實際項目中這里會調(diào)用真實天氣 API return new WeatherInfo(city, 25.5, 晴); } }5.3 編寫調(diào)用入口// 文件路徑src/main/java/com/example/ai/ToolDemoApplication.java import org.springframework.ai.chat.client.ChatClient; import org.springframework.boot.CommandLineRunner; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class ToolDemoApplication implements CommandLineRunner { private final ChatClient chatClient; public ToolDemoApplication(ChatClient.Builder builder, WeatherService weatherService) { this.chatClient builder .defaultTools(weatherService) .build(); } public static void main(String[] args) { SpringApplication.run(ToolDemoApplication.class, args); } Override public void run(String... args) { String answer chatClient.prompt() .user(北京今天的天氣怎么樣) .call() .content(); System.out.println(answer); } }5.4 運行邏輯說明整個流程是用戶問題傳入模型 → 模型識別出需要調(diào)用 getWeather 方法生成一個包含城市參數(shù)的結構化調(diào)用請求 → Spring AI 攔截這個請求通過反射調(diào)用 WeatherService 中的方法 → 方法返回的天氣數(shù)據(jù)被回傳給模型 → 模型根據(jù)這些數(shù)據(jù)生成最終回答。這個示例雖然簡單但揭示了工具調(diào)用的三個關鍵點工具的“描述質(zhì)量”直接影響模型的準確率。描述寫得越詳細模型越不容易用錯參數(shù)。工具方法是同步阻塞的如果方法里有外部 API 調(diào)用要做好超時和重試。模型返回的工具調(diào)用參數(shù)是文本形式的框架負責反序列化但參數(shù)數(shù)量多時要仔細設計 DTO。很多人第一次跑這個示例會困惑為什么我的工具沒有被調(diào)用最常見的幾個原因一是工具類沒有注冊為 Spring Bean二是 Tool 注解的包引錯了三是模型的工具調(diào)用能力沒有在請求中開啟。先從這三處排查。6. RAG 知識庫實戰(zhàn)從文檔到檢索問答工具調(diào)用解決了“讓模型獲取實時數(shù)據(jù)”的問題接下來看企業(yè)場景里更常見的 RAG。模擬場景公司內(nèi)部有一份《新員工入職手冊》包含請假流程、報銷規(guī)則等需要讓模型基于這份手冊回答員工問題。完整的 RAG 鏈路是文檔加載 → 文本切分 → Embedding 向量化 → 存入向量庫 → 檢索 → 重排可選 → 拼入提示詞 → 模型生成回答。6.1 文檔加載與切分文檔加載是最容易被低估的一步。PDF、Word、Markdown 的解析方式完全不同解析出來的內(nèi)容質(zhì)量直接決定后續(xù)檢索效果。// 文件路徑src/main/java/com/example/ai/rag/DocumentLoader.java import org.springframework.ai.reader.TextReader; import org.springframework.ai.transformer.splitter.TokenTextSplitter; import org.springframework.ai.document.Document; import org.springframework.core.io.ClassPathResource; import java.util.List; public class DocumentLoader { public ListDocument loadAndSplit() { // 1. 讀取 Markdown 文檔 TextReader reader new TextReader(new ClassPathResource(docs/employee-handbook.md)); ListDocument documents reader.get(); // 2. 按 Token 切分設置重疊保持上下文連貫 TokenTextSplitter splitter new TokenTextSplitter(500, 100); return splitter.apply(documents); } }切分策略是 RAG 效果好壞的分水嶺。切得太短單個片段信息量不足檢索出來也回答不完整切得太長向量檢索的語義精度下降而且會增加 Token 消耗。常見做法是結構清晰的文檔按標題切分普通文檔按固定 Token 數(shù)切分并設置 10%~20% 的重疊。6.2 Embedding 向量化并存入 Milvus向量化是讓文本變成計算機可以計算相似度的數(shù)學向量的過程。不同模型的向量維度不同常見的 Embedding 模型輸出 1024 維或 1536 維向量。// 文件路徑src/main/java/com/example/ai/rag/VectorStoreConfig.java import org.springframework.ai.embedding.EmbeddingModel; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.ai.vectorstore.milvus.MilvusVectorStore; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class VectorStoreConfig { Bean public VectorStore vectorStore(EmbeddingModel embeddingModel) { MilvusVectorStore.MilvusVectorStoreConfig config MilvusVectorStore.MilvusVectorStoreConfig.builder() .withCollectionName(employee_handbook) .build(); return new MilvusVectorStore(embeddingModel, config); } }寫入向量庫的代碼非常短因為核心向量化過程被框架封裝了// 文件路徑src/main/java/com/example/ai/rag/RagIngestionService.java import org.springframework.ai.vectorstore.VectorStore; import org.springframework.stereotype.Service; import java.util.List; Service public class RagIngestionService { private final VectorStore vectorStore; public RagIngestionService(VectorStore vectorStore) { this.vectorStore vectorStore; } public void ingest(ListDocument documents) { vectorStore.add(documents); } }6.3 檢索問答當用戶提出問題后需要把問題向量化然后去向量庫中找出最相似的幾個文檔片段連同問題一起發(fā)給模型。// 文件路徑src/main/java/com/example/ai/rag/RagQueryService.java import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.ai.vectorstore.SearchRequest; import org.springframework.stereotype.Service; Service public class RagQueryService { private final VectorStore vectorStore; private final ChatClient chatClient; public RagQueryService(VectorStore vectorStore, ChatClient.Builder builder) { this.vectorStore vectorStore; this.chatClient builder.build(); } public String answer(String question) { // 1. 檢索相關文檔片段取 Top-K ListDocument similarDocuments vectorStore.similaritySearch( SearchRequest.builder() .query(question) .topK(4) .build() ); // 2. 拼接上下文 String context similarDocuments.stream() .map(Document::getText) .reduce((a, b) - a \n\n b) .orElse(); // 3. 帶入提示詞后讓模型回答 return chatClient.prompt() .system(你是一個企業(yè)知識庫助手請基于提供的文檔內(nèi)容回答用戶問題。 如果文檔中沒有相關信息請直接回答不知道。回答請注明信息來源段落。) .user(文檔內(nèi)容\n context \n\n問題 question) .call() .content(); } }這段代碼的核心思維是“先檢索后回答”。模型看不到整個知識庫只能看到檢索出來的幾個片段因此檢索質(zhì)量直接決定回答質(zhì)量。6.4 RAG 常見的優(yōu)化方向如果 RAG 效果不理想不要急著換模型先按以下順序排查文檔切分是否合理是否破壞了文檔的語義完整性。Embedding 模型是否合適通用模型檢索專業(yè)領域內(nèi)容效果會打折扣。Top-K 是否合理K 值太小容易漏信息K 值太大容易引入噪音。是否缺少重排環(huán)節(jié)向量檢索的“相似”不等于“相關”加一個重排模型可以顯著提升精度。7. Agent 實戰(zhàn)讓模型編排多步任務理解了 Tools 和 RAG 之后Agent 的理解門檻就低了。Agent 本質(zhì)上是“循環(huán) 工具 決策”的組合。下面用 Langchain4j 實現(xiàn)一個簡單的 Agent讓它能同時使用天氣查詢和 RAG 檢索兩個工具完成一次需要多步推理的任務。7.1 定義 Agent 服務接口Langchain4j 的核心抽象是 AiServices它允許你用接口來描述 Agent 的“能力”。// 文件路徑src/main/java/com/example/ai/agent/CustomerAssistant.java import dev.langchain4j.service.AiServices; import dev.langchain4j.service.SystemMessage; import dev.langchain4j.service.UserMessage; import dev.langchain4j.service.tool.Tool; import java.time.LocalDate; AiServices public interface CustomerAssistant { SystemMessage(你是一個企業(yè)智能助理可以根據(jù)用戶的請求調(diào)用工具。回答要簡潔、準確。) String chat(UserMessage String userMessage); }7.2 組合多個工具同一屆面中工具方法分散在多個服務里也沒關系AiServices 支持傳入多個工具實例。// 文件路徑src/main/java/com/example/ai/agent/TimeTool.java import dev.langchain4j.service.tool.Tool; public class TimeTool { Tool(獲取當前日期) public String currentDate() { return LocalDate.now().toString(); } }然后組裝 Agent 入口// 文件路徑src/main/java/com/example/ai/agent/AgentDemo.java import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.model.openai.OpenAiChatModel; public class AgentDemo { public static void main(String[] args) { // 模型實例具體 API Key 通過環(huán)境變量注入 OpenAiChatModel model OpenAiChatModel.builder() .apiKey(System.getenv(LLM_API_KEY)) .baseUrl(System.getenv(LLM_BASE_URL)) .build(); CustomerAssistant assistant AiServices.builder(CustomerAssistant.class) .chatLanguageModel(model) .chatMemory(MessageWindowChatMemory.withMaxMessages(20)) .tools(new TimeTool(), new WeatherServiceAgent()) .build(); String answer assistant.chat(北京今天天氣怎么樣適合穿什么衣服); System.out.println(answer); } }7.3 Agent 與普通代碼的邊界Agent 的高級感容易讓人上頭但工程上必須克制。判斷一個場景是否需要 Agent可以從兩個維度考慮任務步驟是否確定能寫死流程的用普通代碼只有任務目標確定、步驟無法預判的才用 Agent。失敗成本是否可控Agent 的多步循環(huán)意味著錯誤會累積如果一步執(zhí)行錯的結果被帶入下一步最終輸出可能完全偏離預期。涉及資金、審批等高風險場景必須給 Agent 加人工確認環(huán)節(jié)。8. 常見問題與排查思路把實踐中最常遇到的幾類問題整理成一個排查表方便對照處理問題現(xiàn)象可能原因排查方式解決方案模型沒有調(diào)用工具工具方法未注冊為 Bean / Tool 注解失效查看應用啟動日志中的工具注冊信息確認工具類被 Spring 容器掃描檢查注解包路徑工具參數(shù)反序列化失敗參數(shù)類型和模型生成的 JSON 不匹配打印本次請求的工具調(diào)用請求體調(diào)整 DTO 結構盡量使用簡單類型參數(shù)RAG 回答不準確文檔切分不合理 / 檢索 Top-K 太少打印檢索到的文檔片段人工檢查相關度調(diào)整切分策略增加重排環(huán)節(jié)RAG 回答編造信息沒有控制提示詞中的回答邊界檢查 system 提示詞是否有“不知道就直說”強化提示詞約束必要時對輸出做關鍵詞過濾Agent 循環(huán)不終止缺少最大迭代次數(shù)限制查看請求日志中的工具調(diào)用次數(shù)為 Agent 設置最大循環(huán)次數(shù)和超時時間模型調(diào)用超時網(wǎng)絡波動 / 模型服務響應慢查看模型服務端監(jiān)控和客戶端超時日志增加超時配置加入重試和熔斷機制還有一個很典型的工程問題容易被忽略工具方法里的異常處理。如果工具方法拋出異常不同的框架處理方式不同有的是把異常信息返回給模型讓模型自行決定有的會直接中斷整個流程。生產(chǎn)環(huán)境中建議把異常信息作為工具返回值的一部分交給模型這樣 Agent 可以基于異常信息調(diào)整策略而不是整個任務直接失敗。9. 工程化最佳實踐從 Demo 到生產(chǎn)中間隔著的不是代碼量而是一整套工程意識。以下幾件事應該在項目初期就規(guī)劃好。第一日志鏈路必須完整。大模型應用是黑盒你無法直接看到模型“為什么這么回答”。因此每次請求都要記錄用戶的原始輸入、檢索到的上下文片段、模型完整輸出、工具調(diào)用的參數(shù)和結果。一旦線上出現(xiàn)問題這些日志是唯一的判斷依據(jù)。第二成本控制要前置。LLM API 調(diào)用的成本不是線性的Agent 的多輪循環(huán)可能讓單次提問消耗幾十倍的 Token。建議在 Agent 場景設置 Token 上限和費用預警并對工具的調(diào)用次數(shù)做限制。第三提示詞也是一種代碼。提示詞要像管理代碼一樣管理進版本控制、寫清晰注釋、做效果對比。不要用大段 Markdown 風格提示詞塞在 Java 代碼里要抽成獨立的資源文件方便業(yè)務人員一起校對參數(shù)。第四安全邊界要明確。工具調(diào)用賦予模型執(zhí)行操作的能力這本身就是高風險。所有工具方法都必須做權限校驗和參數(shù)校驗隔離敏感操作工具執(zhí)行要有審計記錄。涉及數(shù)據(jù)庫寫入、文件刪除、資金變動等操作一定要強制人工二次確認。第五評估機制不能缺。每次調(diào)整提示詞或切分策略都要有一套固定的評估問題集記錄回答質(zhì)量。否則你可能只是“感覺”這次改好了實際上在另一些問題上效果變差了。10. 總結與后續(xù)學習方向這篇文章從 Java 開發(fā)者視角把 Spring AI 和 Langchain4j 兩套框架的核心鏈路串了一遍工具調(diào)用讓模型具備了執(zhí)行能力RAG 讓模型接入了私有知識Agent 讓模型能夠自主編排多步任務。這三者不是孤立的技能點而是一條完整的能力升級路徑。下一步的實踐建議是先用 Spring AI 跑通一個包含工具調(diào)用的最小項目理解模型和代碼之間的交互機制然后為核心業(yè)務文檔搭建一個 RAG 知識庫注意切分策略和檢索質(zhì)量的調(diào)優(yōu)最后再嘗試用 Langchain4j 的 AiServices 把一個需要多步操作的真實場景封裝成 Agent。過程中一定要搭好日志和評估體系否則很難判斷改動到底是變好還是變壞。Spring AI 和 Langchain4j 的更新速度都很快新特性層出不窮。但只要掌握了工具調(diào)用、RAG、Agent 這三條主線任何新特性對你來說都只是細節(jié)擴展。建議收藏這篇文章按章節(jié)逐步實踐。紙上得來終覺淺尤其是這種交互式 AI 應用開發(fā)跑通一次真實鏈路比看十篇教程都管用。