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