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