1. 為什么要在項(xiàng)目里做多 Provider 切換做過(guò) AI 應(yīng)用的人大概都有過(guò)這種體驗(yàn)項(xiàng)目剛起步時(shí)接了一家大模型代碼寫(xiě)得挺順結(jié)果業(yè)務(wù)方突然說(shuō)“我們想試試另一家的效果”或者某天接口開(kāi)始限流、響應(yīng)變慢你才發(fā)現(xiàn)整個(gè)調(diào)用邏輯跟那家 SDK 綁得死死的改起來(lái)牽一發(fā)動(dòng)全身。這就是我在做這個(gè) AI 模塊架構(gòu)時(shí)踩過(guò)的第一個(gè)坑也是我把“多 Provider 切換”放在架構(gòu)最底層的原因。所謂多 Provider說(shuō)白了就是讓系統(tǒng)能同時(shí)對(duì)接多家大模型服務(wù)并且能在運(yùn)行時(shí)按需切換。它解決的核心問(wèn)題是解耦——業(yè)務(wù)代碼不應(yīng)該關(guān)心底層到底調(diào)的是哪家模型只關(guān)心“我發(fā)一段話拿回一個(gè)結(jié)果”。這個(gè)思路跟數(shù)據(jù)庫(kù)連接池、消息隊(duì)列抽象層是一個(gè)道理只不過(guò)對(duì)象換成了大模型。我見(jiàn)過(guò)太多項(xiàng)目把模型調(diào)用直接寫(xiě)死在 Service 里new OpenAiClient()一掛后面想換模型就得全局搜索替換。這種寫(xiě)法在 Demo 階段沒(méi)問(wèn)題一旦進(jìn)入真實(shí)業(yè)務(wù)尤其是需要做 A/B 測(cè)試、成本控制、故障降級(jí)的場(chǎng)景就會(huì)非常痛苦。舉個(gè)實(shí)際例子我們有個(gè)功能對(duì)響應(yīng)速度要求高用某家模型延遲穩(wěn)定在 800ms 左右但另一家只要 400ms 卻貴一倍。如果沒(méi)有 Provider 抽象層你只能二選一有了抽象層你可以讓這個(gè)功能走快的、那個(gè)功能走便宜的甚至高峰期自動(dòng)降級(jí)到便宜的那家。從技術(shù)選型上看我最終選了LangChain4j作為基礎(chǔ)框架。原因很直接它原生支持多家模型 Provider接口統(tǒng)一而且對(duì) RAG 和 Agent 的支持是內(nèi)建的不用自己從零搭輪子。LangChain4j 的ChatLanguageModel接口就是那個(gè)抽象層OpenAI、通義千問(wèn)、DeepSeek、Ollama 本地模型都實(shí)現(xiàn)了它切換時(shí)只需要換一個(gè)實(shí)現(xiàn)類業(yè)務(wù)代碼一行不用動(dòng)。這里有個(gè)關(guān)鍵設(shè)計(jì)點(diǎn)值得展開(kāi)說(shuō)Provider 的配置不能硬編碼。我采用的是“配置驅(qū)動(dòng) 工廠模式”的組合。配置文件里定義每個(gè) Provider 的base_url、api_key、model_name、timeout等參數(shù)啟動(dòng)時(shí)由工廠類讀取配置并實(shí)例化對(duì)應(yīng)的 Model 對(duì)象注冊(cè)到一個(gè)ProviderRegistry里。業(yè)務(wù)層通過(guò)ProviderRegistry.get(providerName)拿到模型實(shí)例。這樣做的好處是新增一家 Provider 只需要加一段配置不用改代碼、不用重新編譯。注意base_url配置缺失是新手最容易犯的錯(cuò)。我見(jiàn)過(guò)好幾次報(bào)錯(cuò)信息里寫(xiě)著“provider 缺少 base_url 配置”排查半天發(fā)現(xiàn)是配置文件里漏了一行。建議在工廠類里做啟動(dòng)時(shí)校驗(yàn)缺參數(shù)直接拋異常別等到運(yùn)行時(shí)才報(bào)錯(cuò)。還有一個(gè)容易被忽略的點(diǎn)是超時(shí)和重試策略。不同 Provider 的響應(yīng)特性差異很大有的首包快但整體慢有的首包慢但流式輸出穩(wěn)。我在每個(gè) Provider 的配置里都單獨(dú)設(shè)了connectTimeout、readTimeout和maxRetries并且重試邏輯做了區(qū)分網(wǎng)絡(luò)類錯(cuò)誤重試參數(shù)類錯(cuò)誤直接失敗不重試。這個(gè)細(xì)節(jié)后面在問(wèn)題排查章節(jié)還會(huì)細(xì)說(shuō)。2. RAG 知識(shí)庫(kù)的架構(gòu)設(shè)計(jì)與落地細(xì)節(jié)RAG 這個(gè)詞這兩年已經(jīng)被說(shuō)爛了但真正落地時(shí)你會(huì)發(fā)現(xiàn)從“知道 RAG 是什么”到“RAG 命中率能看”之間隔著一條鴻溝。我在這個(gè)模塊里把 RAG 拆成了四個(gè)獨(dú)立環(huán)節(jié)文檔加載、切分、向量化、檢索每個(gè)環(huán)節(jié)都可以單獨(dú)調(diào)優(yōu)這樣出問(wèn)題時(shí)能快速定位是哪一步拖了后腿。先說(shuō)文檔加載。LangChain4j 提供了DocumentLoader接口支持從文件系統(tǒng)、URL、數(shù)據(jù)庫(kù)等多種來(lái)源加載。我實(shí)際項(xiàng)目里主要是 PDF、Word 和 Markdown 三種格式。PDF 解析用的是 Apache PDFBox這里有個(gè)坑掃描版 PDF 直接解析出來(lái)是空的需要先做 OCR。我的處理方式是加載時(shí)先判斷文本提取結(jié)果的長(zhǎng)度如果低于閾值就標(biāo)記為“需 OCR”走另一條處理鏈路。Word 文檔相對(duì)簡(jiǎn)單但要注意表格內(nèi)容的提取默認(rèn)解析器會(huì)把表格拍平成純文本丟失結(jié)構(gòu)信息如果知識(shí)庫(kù)里有大量表格建議自定義解析邏輯保留行列關(guān)系。文檔切分是影響檢索質(zhì)量的關(guān)鍵一步。LangChain4j 內(nèi)置了多種DocumentSplitter我常用的是RecursiveCharacterTextSplitter它按段落、句子、字符的優(yōu)先級(jí)遞歸切分盡量保持語(yǔ)義完整。參數(shù)上chunkSize我一般設(shè) 500 到 800 個(gè)字符chunkOverlap設(shè) 50 到 100。為什么是這個(gè)范圍因?yàn)樘×苏Z(yǔ)義不完整檢索出來(lái)答非所問(wèn)太大了向量表示會(huì)被稀釋相似度計(jì)算不準(zhǔn)。這個(gè)值沒(méi)有標(biāo)準(zhǔn)答案得根據(jù)你的文檔類型調(diào)。技術(shù)文檔可以小一點(diǎn)敘述性內(nèi)容可以大一點(diǎn)。向量化環(huán)節(jié)我選的是本地嵌入模型加遠(yuǎn)程嵌入模型雙軌制。本地用 Ollama 跑一個(gè)輕量嵌入模型適合開(kāi)發(fā)調(diào)試和隱私敏感場(chǎng)景生產(chǎn)環(huán)境用遠(yuǎn)程嵌入 API效果好但要注意成本和限流。LangChain4j 的EmbeddingModel接口同樣做了抽象切換嵌入模型和切換對(duì)話模型一樣簡(jiǎn)單。這里要提醒一句嵌入模型換了整個(gè)向量庫(kù)必須重建因?yàn)椴煌Ｐ蜕傻南蛄靠臻g不兼容混用會(huì)導(dǎo)致檢索結(jié)果完全錯(cuò)亂。檢索環(huán)節(jié)我做了兩層優(yōu)化。第一層是混合檢索把向量相似度檢索和關(guān)鍵詞檢索的結(jié)果做融合。純向量檢索對(duì)語(yǔ)義匹配好但對(duì)專有名詞、型號(hào)、代碼片段這類精確匹配弱關(guān)鍵詞檢索正好互補(bǔ)。LangChain4j 支持通過(guò)EmbeddingStoreContentRetriever配置我在此基礎(chǔ)上加了一個(gè)基于 Lucene 的關(guān)鍵詞檢索器兩路結(jié)果用 RRF倒數(shù)排名融合算法合并。第二層是重排序檢索出 Top 20 后用一個(gè)交叉編碼器模型對(duì)每個(gè)候選做精排取 Top 5 送給大模型。這一步能把命中率提升 15% 到 25%代價(jià)是增加一點(diǎn)延遲但非常值得。環(huán)節(jié)常用方案關(guān)鍵參數(shù)調(diào)優(yōu)方向文檔加載PDFBox 自定義解析文本長(zhǎng)度閾值表格保留、OCR 兜底文檔切分RecursiveCharacterTextSplitterchunkSize500-800按文檔類型調(diào)整向量化本地 Ollama / 遠(yuǎn)程 API維度、批量大小成本與效果平衡檢索向量 關(guān)鍵詞混合TopK、RRF 參數(shù)加交叉編碼器重排實(shí)操心得RAG 的瓶頸往往不在檢索算法而在文檔質(zhì)量。我花在清洗文檔上的時(shí)間比調(diào)參多得多。建議在入庫(kù)前做一輪預(yù)處理去掉頁(yè)眉頁(yè)腳、合并斷行、統(tǒng)一標(biāo)點(diǎn)、剔除亂碼。這些臟數(shù)據(jù)對(duì)檢索的負(fù)面影響遠(yuǎn)超你的想象。另外提一下 GraphRAG 和本體 RAG 這兩個(gè)進(jìn)階方向。GraphRAG 是把文檔里的實(shí)體和關(guān)系抽出來(lái)構(gòu)建知識(shí)圖譜檢索時(shí)同時(shí)走圖查詢和向量查詢適合關(guān)系密集型知識(shí)庫(kù)比如專利、法律、醫(yī)療領(lǐng)域。本體 RAG 則是預(yù)先定義好領(lǐng)域本體結(jié)構(gòu)讓檢索和生成都圍繞本體展開(kāi)。這兩個(gè)方案效果確實(shí)好但構(gòu)建成本高我一般建議先用基礎(chǔ) RAG 跑通有明確瓶頸再上。3. Agent 編排的核心機(jī)制與實(shí)現(xiàn)路徑Agent 是這個(gè)模塊里最復(fù)雜也最有意思的部分。簡(jiǎn)單說(shuō)Agent 就是讓大模型不只是“回答問(wèn)題”而是能“決定做什么、調(diào)用什么工具、按什么順序做”。LangChain4j 對(duì) Agent 的支持主要通過(guò)AiServices和工具調(diào)用機(jī)制實(shí)現(xiàn)我在此基礎(chǔ)上做了一層編排層。先講工具調(diào)用。LangChain4j 允許你用Tool注解把一個(gè) Java 方法暴露給大模型模型在需要時(shí)會(huì)生成調(diào)用請(qǐng)求框架負(fù)責(zé)執(zhí)行并把結(jié)果回傳。這個(gè)機(jī)制是 Agent 的基礎(chǔ)能力。我項(xiàng)目里定義了幾類工具知識(shí)庫(kù)檢索工具、數(shù)據(jù)庫(kù)查詢工具、外部 API 調(diào)用工具、計(jì)算工具。每個(gè)工具都有清晰的描述和參數(shù)說(shuō)明因?yàn)槟Ｐ褪强窟@些描述來(lái)決定用哪個(gè)工具的。描述寫(xiě)得含糊模型就會(huì)亂調(diào)或者不調(diào)。工具定義有個(gè)細(xì)節(jié)參數(shù)類型要簡(jiǎn)單。我試過(guò)用復(fù)雜的嵌套對(duì)象做參數(shù)模型經(jīng)常生成不合法的 JSON。后來(lái)改成扁平的基本類型加字符串成功率大幅提升。如果確實(shí)需要復(fù)雜結(jié)構(gòu)就讓參數(shù)是 JSON 字符串在工具方法內(nèi)部自己解析這樣模型只需要保證 JSON 格式正確即可。Agent 編排的核心是執(zhí)行循環(huán)。一個(gè)典型的 Agent 執(zhí)行流程是這樣的接收用戶輸入模型判斷是否需要調(diào)用工具如果需要就生成工具調(diào)用請(qǐng)求框架執(zhí)行工具并把結(jié)果追加到對(duì)話歷史模型基于新上下文繼續(xù)判斷直到模型認(rèn)為可以給出最終答案。這個(gè)循環(huán)要有最大輪次限制否則模型可能陷入死循環(huán)。我設(shè)的是 10 輪超過(guò)就強(qiáng)制終止并返回當(dāng)前結(jié)果。LangChain4j 的AiServices提供了聲明式的 Agent 定義方式你定義一個(gè)接口用注解標(biāo)注哪些方法需要工具支持框架自動(dòng)生成實(shí)現(xiàn)。這種方式適合簡(jiǎn)單場(chǎng)景。復(fù)雜場(chǎng)景我建議自己寫(xiě)編排邏輯因?yàn)槟阈枰刂泼恳徊降漠惓Ｌ幚?、超時(shí)、日志和狀態(tài)管理。我的做法是定義一個(gè)AgentExecutor內(nèi)部維護(hù)對(duì)話狀態(tài)、工具注冊(cè)表和執(zhí)行策略每一步都有明確的輸入輸出和錯(cuò)誤處理。多 Agent 協(xié)作是另一個(gè)層次。我項(xiàng)目里有一個(gè)“研究 Agent”負(fù)責(zé)檢索和整理資料一個(gè)“寫(xiě)作 Agent”負(fù)責(zé)生成內(nèi)容一個(gè)“審核 Agent”負(fù)責(zé)檢查事實(shí)和格式。它們之間通過(guò)消息傳遞協(xié)作由一個(gè)協(xié)調(diào)器決定任務(wù)分配和流轉(zhuǎn)。這種架構(gòu)適合復(fù)雜任務(wù)但調(diào)試難度也大。我的經(jīng)驗(yàn)是先從單 Agent 加多工具開(kāi)始確實(shí)需要分工再拆多 Agent否則你會(huì)花大量時(shí)間在 Agent 之間的通信和狀態(tài)同步上。注意Agent 執(zhí)行中最常見(jiàn)的錯(cuò)誤是“工具調(diào)用參數(shù)不合法”和“模型不按預(yù)期調(diào)用工具”。前者靠簡(jiǎn)化參數(shù)類型解決后者靠?jī)?yōu)化工具描述和給模型提供 few-shot 示例解決。我在系統(tǒng)提示詞里會(huì)放兩三個(gè)工具調(diào)用的正確示例效果立竿見(jiàn)影。還有一個(gè)實(shí)際問(wèn)題是執(zhí)行終止條件。除了最大輪次我還加了“連續(xù)兩次調(diào)用同一工具且參數(shù)相同”就終止的邏輯防止模型卡在某個(gè)工具上反復(fù)調(diào)用。另外如果工具執(zhí)行拋異常我會(huì)把異常信息作為工具結(jié)果返回給模型讓它自己決定是重試還是換方案而不是直接中斷整個(gè)流程。這個(gè)設(shè)計(jì)讓 Agent 的魯棒性好了很多。4. 多 Provider 切換的實(shí)操配置與代碼落地理論說(shuō)完了這一節(jié)直接上可復(fù)制的配置和代碼。我用的是 Spring Boot 加 LangChain4j 的組合配置走application.yml工廠類負(fù)責(zé)實(shí)例化。先看配置文件結(jié)構(gòu)。我為每個(gè) Provider 定義一組參數(shù)用前綴區(qū)分ai: providers: openai: base-url: https://api.openai.com/v1 api-key: ${OPENAI_API_KEY} model-name: gpt-4o timeout: 30s max-retries: 2 deepseek: base-url: https://api.deepseek.com/v1 api-key: ${DEEPSEEK_API_KEY} model-name: deepseek-chat timeout: 60s max-retries: 1 ollama: base-url: http://localhost:11434 model-name: qwen2.5:7b timeout: 120s max-retries: 0 default-provider: openai工廠類的核心邏輯是讀取配置、校驗(yàn)必填項(xiàng)、創(chuàng)建對(duì)應(yīng)的ChatLanguageModel實(shí)例并注冊(cè)。LangChain4j 對(duì)不同 Provider 有不同的構(gòu)建器OpenAI 兼容的用OpenAiChatModelOllama 用OllamaChatModel。我寫(xiě)了一個(gè)ProviderFactory根據(jù)配置里的類型字段決定用哪個(gè)構(gòu)建器。Component public class ProviderFactory { private final MapString, ChatLanguageModel registry new ConcurrentHashMap(); public void register(String name, ProviderConfig config) { if (config.getBaseUrl() null || config.getBaseUrl().isBlank()) { throw new IllegalStateException(Provider [ name ] 缺少 base_url 配置); } ChatLanguageModel model switch (config.getType()) { case OPENAI_COMPATIBLE - OpenAiChatModel.builder() .baseUrl(config.getBaseUrl()) .apiKey(config.getApiKey()) .modelName(config.getModelName()) .timeout(config.getTimeout()) .maxRetries(config.getMaxRetries()) .build(); case OLLAMA - OllamaChatModel.builder() .baseUrl(config.getBaseUrl()) .modelName(config.getModelName()) .timeout(config.getTimeout()) .build(); }; registry.put(name, model); } public ChatLanguageModel get(String name) { ChatLanguageModel model registry.get(name); if (model null) { throw new IllegalArgumentException(未注冊(cè)的 Provider: name); } return model; } }業(yè)務(wù)層調(diào)用時(shí)通過(guò)一個(gè)ModelRouter決定用哪個(gè) Provider。路由策略我實(shí)現(xiàn)了三種固定路由按配置指定、權(quán)重路由按比例分流做 A/B 測(cè)試、降級(jí)路由主 Provider 失敗時(shí)切備用。降級(jí)路由的實(shí)現(xiàn)是在調(diào)用外層包一個(gè) try-catch捕獲超時(shí)和連接異常后切換到備用 Provider 重試一次。public String chat(String providerName, String userMessage) { try { return providerFactory.get(providerName).generate(userMessage); } catch (Exception e) { log.warn(Provider [{}] 調(diào)用失敗嘗試降級(jí), providerName, e); String fallback routingConfig.getFallback(providerName); if (fallback ! null) { return providerFactory.get(fallback).generate(userMessage); } throw e; } }這里有個(gè)實(shí)操細(xì)節(jié)降級(jí)不能無(wú)腦切。如果失敗原因是參數(shù)錯(cuò)誤比如消息格式不對(duì)切到另一個(gè) Provider 一樣會(huì)失敗白白增加延遲。所以我在 catch 里判斷異常類型只對(duì)網(wǎng)絡(luò)類、超時(shí)類、限流類異常做降級(jí)參數(shù)類異常直接拋出。提示base_url末尾不要帶斜杠有些 SDK 會(huì)拼接出雙斜杠導(dǎo)致 404。這個(gè)坑我踩過(guò)排查了半小時(shí)才發(fā)現(xiàn)是配置里多了一個(gè)/。流式輸出也要考慮。LangChain4j 的StreamingChatLanguageModel接口支持流式返回但不同 Provider 的流式實(shí)現(xiàn)細(xì)節(jié)有差異。我在路由層統(tǒng)一做了適配對(duì)外暴露的接口是FluxString內(nèi)部把各家的流式回調(diào)轉(zhuǎn)成響應(yīng)式流。這樣前端只需要處理一種數(shù)據(jù)格式。5. RAG 知識(shí)庫(kù)從零搭建的完整流程這一節(jié)我把 RAG 的搭建過(guò)程拆成可執(zhí)行的步驟你照著做就能跑起來(lái)。我用 Ollama 加本地嵌入模型做演示因?yàn)榱愠杀?、可離線、適合入門。第一步是環(huán)境準(zhǔn)備。裝好 Ollama 后拉兩個(gè)模型一個(gè)對(duì)話模型一個(gè)嵌入模型。對(duì)話模型我選qwen2.5:7b中文效果好且體積適中嵌入模型選nomic-embed-text維度 768夠用且快。命令很簡(jiǎn)單ollama pull qwen2.5:7b和ollama pull nomic-embed-text等下載完就行。第二步是引入 LangChain4j 依賴。Maven 里加langchain4j、langchain4j-ollama、langchain4j-easy-rag三個(gè)包。easy-rag是 LangChain4j 提供的一站式 RAG 組件適合快速驗(yàn)證但生產(chǎn)環(huán)境我建議自己組裝各環(huán)節(jié)可控性更強(qiáng)。第三步是文檔入庫(kù)。核心代碼邏輯是加載文檔、切分、向量化、存入向量庫(kù)。向量庫(kù)我用的是內(nèi)存版InMemoryEmbeddingStore適合小規(guī)模知識(shí)庫(kù)數(shù)據(jù)量大就換 Milvus 或 PgVector。入庫(kù)代碼大概長(zhǎng)這樣EmbeddingModel embeddingModel OllamaEmbeddingModel.builder() .baseUrl(http://localhost:11434) .modelName(nomic-embed-text) .build(); EmbeddingStoreTextSegment store new InMemoryEmbeddingStore(); DocumentSplitter splitter new RecursiveCharacterTextSplitter(600, 80); ListDocument documents FileSystemDocumentLoader.loadDocuments(/path/to/docs); ListTextSegment segments splitter.splitAll(documents); ListEmbedding embeddings embeddingModel.embedAll(segments).content(); store.addAll(embeddings, segments);第四步是檢索配置。我配了向量檢索加關(guān)鍵詞檢索的混合模式檢索 Top 10再用重排序取 Top 3。重排序模型可以用bge-reranker系列Ollama 也支持。如果不想加重排序至少把 TopK 設(shè)大一點(diǎn)比如 8 到 10讓大模型自己從更多上下文里挑。第五步是接入對(duì)話。把檢索到的內(nèi)容拼進(jìn)提示詞讓模型基于上下文回答。提示詞模板很關(guān)鍵我用的結(jié)構(gòu)是系統(tǒng)指令說(shuō)明“只基于提供的上下文回答上下文沒(méi)有的信息不要編造”然后是上下文內(nèi)容最后是用戶問(wèn)題。這個(gè)模板能顯著降低幻覺(jué)。步驟操作耗時(shí)參考常見(jiàn)問(wèn)題環(huán)境準(zhǔn)備安裝 Ollama 拉模型10-30 分鐘模型下載慢依賴引入加 Maven 依賴2 分鐘版本沖突文檔入庫(kù)加載切分向量化視文檔量編碼亂碼檢索配置混合檢索加重排30 分鐘命中率低對(duì)話接入提示詞加檢索20 分鐘幻覺(jué)實(shí)操心得文檔入庫(kù)時(shí)一定要打印每個(gè)環(huán)節(jié)的中間結(jié)果。我習(xí)慣在切分后打印前三個(gè) segment 的內(nèi)容向量化后打印向量維度檢索后打印命中的文本片段。這樣出問(wèn)題時(shí)一眼就能看出是哪一步不對(duì)。很多人跳過(guò)這步結(jié)果檢索效果差卻不知道差在哪。關(guān)于 RAG 命中率我再補(bǔ)充一個(gè)技巧給文檔加元數(shù)據(jù)。每個(gè) segment 除了文本內(nèi)容還存來(lái)源文件名、章節(jié)標(biāo)題、頁(yè)碼等信息。檢索時(shí)可以按元數(shù)據(jù)過(guò)濾比如只在某個(gè)章節(jié)里搜或者把來(lái)源信息一起送給模型幫助它判斷可信度。LangChain4j 的TextSegment支持Metadata用起來(lái)很方便。6. Agent 編排的實(shí)操與工具定義Agent 的落地我分三塊講工具定義、執(zhí)行器實(shí)現(xiàn)、多 Agent 協(xié)作。工具定義用Tool注解方法描述要寫(xiě)清楚“這個(gè)工具做什么、什么時(shí)候用、參數(shù)是什么”。我舉個(gè)例子public class KnowledgeTools { Tool(根據(jù)關(guān)鍵詞檢索內(nèi)部知識(shí)庫(kù)返回相關(guān)文檔片段。當(dāng)用戶問(wèn)題涉及公司內(nèi)部資料時(shí)使用。) public String searchKnowledge( P(檢索關(guān)鍵詞多個(gè)關(guān)鍵詞用空格分隔) String query) { ListTextSegment results retriever.retrieve(query); return results.stream() .map(TextSegment::text) .collect(Collectors.joining(\n---\n)); } }描述里的“當(dāng)用戶問(wèn)題涉及公司內(nèi)部資料時(shí)使用”這句話很重要它告訴模型觸發(fā)條件。我試過(guò)不寫(xiě)觸發(fā)條件模型要么不用工具要么濫用工具。加上之后準(zhǔn)確率明顯提升。執(zhí)行器我手寫(xiě)了一個(gè)核心是一個(gè) while 循環(huán)加狀態(tài)機(jī)。每輪把當(dāng)前對(duì)話歷史發(fā)給模型解析返回結(jié)果是文本還是工具調(diào)用請(qǐng)求。如果是工具調(diào)用執(zhí)行工具、把結(jié)果追加到歷史、繼續(xù)循環(huán)如果是文本返回給用戶并結(jié)束。循環(huán)上限 10 輪同時(shí)記錄每輪的 token 消耗和耗時(shí)方便后續(xù)優(yōu)化。public AgentResult execute(String userInput) { ListChatMessage history new ArrayList(); history.add(SystemMessage.from(SYSTEM_PROMPT)); history.add(UserMessage.from(userInput)); for (int round 0; round MAX_ROUNDS; round) { ChatResponse response model.generate(history); AiMessage aiMessage response.content(); history.add(aiMessage); if (!aiMessage.hasToolExecutionRequests()) { return AgentResult.success(aiMessage.text()); } for (ToolExecutionRequest request : aiMessage.toolExecutionRequests()) { String result toolExecutor.execute(request); history.add(ToolExecutionResultMessage.from(request, result)); } } return AgentResult.maxRoundsExceeded(history); }多 Agent 協(xié)作我用的是“協(xié)調(diào)器 消息總線”模式。協(xié)調(diào)器持有多個(gè) Agent 的引用根據(jù)任務(wù)類型決定調(diào)用哪個(gè)。Agent 之間不直接通信都通過(guò)協(xié)調(diào)器轉(zhuǎn)發(fā)消息。這樣做的好處是解耦每個(gè) Agent 只關(guān)心自己的輸入輸出不關(guān)心上下游是誰(shuí)。缺點(diǎn)是協(xié)調(diào)器邏輯會(huì)變復(fù)雜需要仔細(xì)設(shè)計(jì)任務(wù)路由規(guī)則。注意多 Agent 場(chǎng)景下每個(gè) Agent 的提示詞要明確邊界。我見(jiàn)過(guò)“研究 Agent”和“寫(xiě)作 Agent”職責(zé)重疊結(jié)果兩個(gè)都在檢索資料浪費(fèi)資源還互相干擾。解決辦法是在系統(tǒng)提示詞里寫(xiě)清楚“你只負(fù)責(zé) X不要做 Y”并且協(xié)調(diào)器在分配任務(wù)時(shí)明確告訴 Agent 當(dāng)前階段的目標(biāo)。工具執(zhí)行的安全問(wèn)題也要考慮。Agent 能調(diào)用的工具必須做權(quán)限控制尤其是涉及寫(xiě)操作、外部 API 調(diào)用的工具。我的做法是給工具加一個(gè)RequiresPermission注解執(zhí)行前檢查當(dāng)前會(huì)話的權(quán)限沒(méi)權(quán)限直接返回錯(cuò)誤信息給模型。另外所有工具調(diào)用都記審計(jì)日志包括入?yún)?、出參、耗時(shí)、調(diào)用者方便追溯。7. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄這一節(jié)是我踩坑最多的地方整理成速查表你遇到問(wèn)題時(shí)可以直接對(duì)照。問(wèn)題現(xiàn)象可能原因排查方向解決方案provider 缺少 base_url配置漏寫(xiě)或拼寫(xiě)錯(cuò)檢查配置文件補(bǔ)全配置啟動(dòng)時(shí)校驗(yàn)?zāi)Ｐ筒豢捎媚Ｐ兔e(cuò)誤或服務(wù)未啟動(dòng)確認(rèn)模型名和端點(diǎn)核對(duì)文檔檢查服務(wù)狀態(tài)請(qǐng)求被拒絕參數(shù)格式不符看錯(cuò)誤詳情按 Provider 要求調(diào)整RAG 答非所問(wèn)切分粒度或檢索參數(shù)問(wèn)題打印檢索結(jié)果調(diào) chunkSize 和 TopKAgent 死循環(huán)工具反復(fù)調(diào)用看執(zhí)行日志加輪次和重復(fù)調(diào)用限制流式輸出中斷超時(shí)或網(wǎng)絡(luò)問(wèn)題看超時(shí)配置調(diào)大 readTimeout第一個(gè)高頻問(wèn)題是配置錯(cuò)誤。報(bào)錯(cuò)信息里經(jīng)常出現(xiàn)“缺少 base_url 配置”或“缺少 api_key”這類問(wèn)題最好在啟動(dòng)時(shí)就暴露。我在工廠類的register方法里做了必填校驗(yàn)缺任何一項(xiàng)直接拋異常應(yīng)用啟動(dòng)失敗。這樣比運(yùn)行時(shí)才發(fā)現(xiàn)要好得多。另外配置項(xiàng)建議用環(huán)境變量注入密鑰別寫(xiě)死在文件里。第二個(gè)高頻問(wèn)題是模型不可用。原因可能是模型名寫(xiě)錯(cuò)、服務(wù)沒(méi)啟動(dòng)、或者賬號(hào)額度用完。排查時(shí)先確認(rèn)服務(wù)端點(diǎn)能通再確認(rèn)模型名和文檔一致最后看賬號(hào)狀態(tài)。我習(xí)慣在啟動(dòng)時(shí)發(fā)一個(gè)簡(jiǎn)單的測(cè)試請(qǐng)求驗(yàn)證每個(gè) Provider 都可用不可用的打警告日志但不阻塞啟動(dòng)運(yùn)行時(shí)再降級(jí)。第三個(gè)問(wèn)題是RAG 命中率低。這個(gè)最考驗(yàn)?zāi)托摹Ｎ业呐挪轫樞蚴窍瓤辞蟹纸Y(jié)果是否合理再看檢索返回的片段是否相關(guān)最后看提示詞是否把上下文用好了。很多時(shí)候問(wèn)題出在切分比如把一句話切成兩半或者把不相關(guān)的內(nèi)容切到一起。調(diào)整chunkSize和chunkOverlap通常能解決大部分問(wèn)題。如果還不行就上重排序。第四個(gè)問(wèn)題是Agent 行為不符合預(yù)期。表現(xiàn)是亂調(diào)工具、不調(diào)工具、或者調(diào)了工具不用結(jié)果。亂調(diào)工具通常是工具描述太模糊模型分不清該用哪個(gè)不調(diào)工具是描述里沒(méi)寫(xiě)觸發(fā)條件調(diào)了不用結(jié)果是提示詞沒(méi)強(qiáng)調(diào)“必須基于工具結(jié)果回答”。這三個(gè)問(wèn)題我都遇到過(guò)解決辦法分別是細(xì)化描述、加觸發(fā)條件、強(qiáng)化系統(tǒng)提示詞。實(shí)操心得排查 Agent 問(wèn)題時(shí)把完整的對(duì)話歷史和工具調(diào)用記錄打出來(lái)看。我一般會(huì)記錄每一輪的輸入消息、模型輸出、工具調(diào)用請(qǐng)求、工具執(zhí)行結(jié)果。這樣一眼就能看出模型在哪一步“想歪了”。光看最終結(jié)果很難定位問(wèn)題。還有一個(gè)隱蔽的問(wèn)題是并發(fā)下的狀態(tài)污染。Agent 執(zhí)行器如果設(shè)計(jì)成有狀態(tài)的單例多個(gè)請(qǐng)求同時(shí)進(jìn)來(lái)會(huì)互相干擾。我的做法是每次執(zhí)行創(chuàng)建一個(gè)新的執(zhí)行上下文所有狀態(tài)都存在上下文對(duì)象里執(zhí)行器本身無(wú)狀態(tài)。這個(gè)設(shè)計(jì)在壓測(cè)時(shí)驗(yàn)證過(guò)并發(fā) 50 個(gè)請(qǐng)求沒(méi)有出現(xiàn)串?dāng)?shù)據(jù)的情況。最后說(shuō)一個(gè)性能相關(guān)的坑向量檢索的延遲。數(shù)據(jù)量小的時(shí)候內(nèi)存檢索很快上萬(wàn)條之后延遲明顯上升。解決辦法是換專業(yè)向量庫(kù)或者加緩存。我給檢索結(jié)果加了基于查詢文本的緩存相同查詢直接返回緩存結(jié)果命中率在重復(fù)問(wèn)題多的場(chǎng)景下能到 30% 以上延遲降得很明顯。8. 架構(gòu)擴(kuò)展與后續(xù)優(yōu)化方向這套架構(gòu)跑通之后我陸續(xù)做了一些擴(kuò)展這里分享幾個(gè)覺(jué)得有價(jià)值的方向。第一個(gè)是成本追蹤。每個(gè) Provider 的計(jì)費(fèi)方式不同我在調(diào)用層記錄了每次請(qǐng)求的輸入輸出 token 數(shù)按 Provider 的單價(jià)算出成本匯總到監(jiān)控面板。這樣能清楚看到哪個(gè)功能燒錢最多有針對(duì)性地優(yōu)化。比如發(fā)現(xiàn)某個(gè)功能用貴模型但效果提升有限就切到便宜模型。第二個(gè)是效果評(píng)估。我建了一個(gè)小規(guī)模的評(píng)測(cè)集包含問(wèn)題和標(biāo)準(zhǔn)答案定期跑一遍看各 Provider 和 RAG 配置的準(zhǔn)確率。這個(gè)評(píng)測(cè)集不用很大幾十條就夠關(guān)鍵是持續(xù)跑能發(fā)現(xiàn)模型更新或配置調(diào)整帶來(lái)的效果波動(dòng)。第三個(gè)是提示詞版本管理。提示詞改動(dòng)對(duì)效果影響很大我把提示詞存在數(shù)據(jù)庫(kù)里帶版本號(hào)每次改動(dòng)記錄變更內(nèi)容和評(píng)測(cè)結(jié)果。這樣能回溯“哪個(gè)版本效果最好”也方便 A/B 測(cè)試。第四個(gè)是降級(jí)鏈路細(xì)化。除了 Provider 降級(jí)我還加了 RAG 降級(jí)檢索失敗時(shí)直接用模型知識(shí)回答和 Agent 降級(jí)工具調(diào)用失敗時(shí)退化為普通對(duì)話。每一層降級(jí)都有明確的觸發(fā)條件和日志保證系統(tǒng)在部分組件故障時(shí)仍能提供基本服務(wù)。這套東西搭下來(lái)最大的體會(huì)是架構(gòu)的價(jià)值在于應(yīng)對(duì)變化。模型會(huì)換、需求會(huì)變、數(shù)據(jù)會(huì)增長(zhǎng)好的架構(gòu)讓你在這些變化面前只需要改配置或加模塊而不是推倒重來(lái)。多 Provider 切換、RAG、Agent 編排這三塊本質(zhì)上都是在為“變化”留出空間。我一開(kāi)始也覺(jué)得抽象層麻煩但經(jīng)歷過(guò)幾次緊急切換 Provider 之后就再也不想回到硬編碼的時(shí)代了。