1. 企業(yè)大模型網(wǎng)關(guān)到底解決什么問題1.1 從一個(gè)真實(shí)痛點(diǎn)說起去年我?guī)鸵患易銎髽I(yè)服務(wù)的團(tuán)隊(duì)做技術(shù)咨詢他們內(nèi)部有十幾個(gè)業(yè)務(wù)系統(tǒng)客服、工單、代碼助手、文檔問答各用各的模型接口。結(jié)果就是OpenAI的key散落在七八個(gè)項(xiàng)目的環(huán)境變量里有人用GPT-4有人用GPT-3.5賬單月底對(duì)不上某個(gè)服務(wù)超時(shí)了也不知道是網(wǎng)絡(luò)問題還是模型限流。更麻煩的是某天一個(gè)開發(fā)同學(xué)離職帶走了他電腦上那份“唯一能跑通”的配置。這不是個(gè)例。只要團(tuán)隊(duì)超過五個(gè)人、接入超過兩個(gè)模型供應(yīng)商幾乎必然會(huì)遇到三個(gè)問題密鑰管理混亂、調(diào)用成本不可控、模型切換成本高。企業(yè)大模型網(wǎng)關(guān)就是在這個(gè)背景下出現(xiàn)的——它本質(zhì)上是一個(gè)位于業(yè)務(wù)應(yīng)用和模型供應(yīng)商之間的中間層統(tǒng)一收口所有模型調(diào)用請(qǐng)求做鑒權(quán)、路由、限流、計(jì)費(fèi)、日志和緩存。你可以把它理解成公司內(nèi)部的“模型調(diào)度中心”。業(yè)務(wù)方不再直接對(duì)接OpenAI、Anthropic或者國(guó)內(nèi)各家模型而是統(tǒng)一請(qǐng)求網(wǎng)關(guān)由網(wǎng)關(guān)決定這次請(qǐng)求走哪個(gè)模型、用哪個(gè)key、要不要緩存、超時(shí)怎么降級(jí)。這樣做的好處很直接密鑰只存在網(wǎng)關(guān)一處換模型不用改業(yè)務(wù)代碼成本可以按部門/項(xiàng)目維度統(tǒng)計(jì)出問題有完整的調(diào)用鏈路日志。1.2 網(wǎng)關(guān)的核心能力拆解一個(gè)能落地的大模型網(wǎng)關(guān)至少要具備以下幾層能力我按重要性排序統(tǒng)一API適配層把不同供應(yīng)商的接口格式OpenAI的chat/completions、Anthropic的messages、國(guó)內(nèi)模型的各類私有協(xié)議統(tǒng)一成一套內(nèi)部標(biāo)準(zhǔn)。業(yè)務(wù)方只認(rèn)一種請(qǐng)求格式網(wǎng)關(guān)負(fù)責(zé)轉(zhuǎn)換。密鑰與租戶管理每個(gè)業(yè)務(wù)線分配獨(dú)立的虛擬key網(wǎng)關(guān)持有真實(shí)的上游key。虛擬key可以設(shè)置額度、過期時(shí)間、可訪問的模型范圍。路由與負(fù)載均衡同一個(gè)模型請(qǐng)求可以配置多個(gè)上游渠道按權(quán)重、優(yōu)先級(jí)或健康狀態(tài)分發(fā)。某個(gè)渠道掛了自動(dòng)切到備用渠道。限流與配額按租戶、按模型、按時(shí)間窗口限制請(qǐng)求頻率和token消耗防止某個(gè)業(yè)務(wù)把額度跑爆。可觀測(cè)性記錄每次請(qǐng)求的耗時(shí)、token數(shù)、成本、上游渠道、錯(cuò)誤碼支持按維度聚合查詢。緩存對(duì)相同或相似的請(qǐng)求做結(jié)果緩存尤其是那些高頻重復(fù)的問答場(chǎng)景能省下可觀的成本。這六項(xiàng)里前兩項(xiàng)是剛需后四項(xiàng)決定了網(wǎng)關(guān)是“能用”還是“好用”。很多團(tuán)隊(duì)一開始只做了統(tǒng)一轉(zhuǎn)發(fā)結(jié)果用著用著發(fā)現(xiàn)沒有限流一個(gè)爬蟲腳本把當(dāng)月預(yù)算跑光了或者沒有日志線上回答質(zhì)量下降時(shí)完全無法定位是哪個(gè)環(huán)節(jié)出了問題。1.3 為什么不是“直接調(diào)API就完了”有人會(huì)問我們團(tuán)隊(duì)就三五個(gè)模型調(diào)用直接調(diào)不就行了搞網(wǎng)關(guān)是不是過度設(shè)計(jì)我的判斷標(biāo)準(zhǔn)是當(dāng)你出現(xiàn)以下任意一種情況時(shí)網(wǎng)關(guān)就該上了。第一有超過兩個(gè)業(yè)務(wù)方在調(diào)用模型第二月調(diào)用成本超過你愿意讓一個(gè)人手動(dòng)對(duì)賬的閾值第三你需要對(duì)模型輸出做審計(jì)或合規(guī)留痕第四你計(jì)劃接入第二個(gè)模型供應(yīng)商做備份或?qū)Ρ?。直接調(diào)API在早期確實(shí)快但它的隱性成本在于每次換模型、加限流、做統(tǒng)計(jì)都要改業(yè)務(wù)代碼。網(wǎng)關(guān)把這些橫切關(guān)注點(diǎn)抽出來業(yè)務(wù)代碼只關(guān)心“我要問模型什么”不關(guān)心“模型從哪來、花多少錢、掛了怎么辦”。這個(gè)分離帶來的長(zhǎng)期收益遠(yuǎn)大于搭建網(wǎng)關(guān)的一次性投入。2. 網(wǎng)關(guān)架構(gòu)設(shè)計(jì)與技術(shù)選型2.1 整體架構(gòu)分層我推薦的分層是這樣的從上到下依次是接入層負(fù)責(zé)接收業(yè)務(wù)請(qǐng)求做初步的鑒權(quán)虛擬key校驗(yàn)和協(xié)議解析。這一層可以用Nginx或者直接由應(yīng)用層處理取決于你的并發(fā)量。如果QPS在幾百以內(nèi)應(yīng)用層直接處理完全夠用。路由層根據(jù)請(qǐng)求中的模型標(biāo)識(shí)、租戶配置、渠道健康狀態(tài)決定這次請(qǐng)求發(fā)往哪個(gè)上游。這一層是網(wǎng)關(guān)的大腦需要支持權(quán)重、優(yōu)先級(jí)、故障轉(zhuǎn)移三種策略。適配層把內(nèi)部標(biāo)準(zhǔn)請(qǐng)求轉(zhuǎn)換成各供應(yīng)商的實(shí)際請(qǐng)求格式同時(shí)把響應(yīng)轉(zhuǎn)換回標(biāo)準(zhǔn)格式。每個(gè)供應(yīng)商一個(gè)適配器新增供應(yīng)商只需加一個(gè)適配器。上游管理層維護(hù)所有上游渠道的連接池、密鑰、超時(shí)配置、重試策略。這一層要處理供應(yīng)商的限流響應(yīng)429、超時(shí)、連接失敗等異常。數(shù)據(jù)層記錄調(diào)用日志、token消耗、成本、緩存。日志建議異步寫入不要阻塞主請(qǐng)求鏈路。這個(gè)分層的好處是每一層職責(zé)單一適配層和上游管理層可以獨(dú)立擴(kuò)展。比如你要加一個(gè)新的模型供應(yīng)商只需要寫一個(gè)適配器路由層和數(shù)據(jù)層完全不用動(dòng)。2.2 技術(shù)棧選型考量網(wǎng)關(guān)本身的技術(shù)棧選擇我建議優(yōu)先考慮團(tuán)隊(duì)最熟悉的語(yǔ)言。原因很簡(jiǎn)單網(wǎng)關(guān)是基礎(chǔ)設(shè)施出問題時(shí)要能快速定位和修復(fù)用不熟悉的語(yǔ)言寫會(huì)拖慢排障速度。如果團(tuán)隊(duì)沒有強(qiáng)偏好我的經(jīng)驗(yàn)是Go適合高并發(fā)場(chǎng)景goroutine模型處理大量IO等待很自然單機(jī)扛幾千QPS沒問題Node.js/TypeScript適合快速迭代生態(tài)里OpenAI SDK成熟寫適配器快Python適合原型驗(yàn)證但生產(chǎn)環(huán)境高并發(fā)下要注意異步框架的選擇FastAPI httpx異步客戶端是常見組合。數(shù)據(jù)庫(kù)方面調(diào)用日志這種寫多讀少的場(chǎng)景我傾向于用ClickHouse或者TimescaleDB按時(shí)間分區(qū)聚合查詢快。如果量不大PostgreSQL加合適的索引也能撐很久。緩存用Redis存請(qǐng)求指紋到響應(yīng)的映射設(shè)置合理的TTL。配置管理建議用數(shù)據(jù)庫(kù)加本地緩存的方式而不是純配置文件。因?yàn)榍赖膯⑼?、?quán)重的調(diào)整、額度的變更這些操作應(yīng)該能在線完成不需要重啟網(wǎng)關(guān)。2.3 關(guān)鍵設(shè)計(jì)決策同步還是異步網(wǎng)關(guān)處理請(qǐng)求時(shí)有一個(gè)容易踩坑的地方日志和計(jì)費(fèi)是同步寫還是異步寫。我見過有團(tuán)隊(duì)在請(qǐng)求鏈路里同步寫數(shù)據(jù)庫(kù)記錄日志結(jié)果數(shù)據(jù)庫(kù)稍微慢一點(diǎn)整個(gè)網(wǎng)關(guān)的響應(yīng)時(shí)間就被拖上去了。正確做法是主請(qǐng)求鏈路只做轉(zhuǎn)發(fā)和響應(yīng)日志和計(jì)費(fèi)數(shù)據(jù)先寫入內(nèi)存隊(duì)列或消息隊(duì)列由獨(dú)立的消費(fèi)者異步落庫(kù)。這樣即使日志系統(tǒng)短暫不可用也不影響模型調(diào)用的正常進(jìn)行。另一個(gè)決策點(diǎn)是流式響應(yīng)怎么處理。大模型很多場(chǎng)景是流式輸出streaming網(wǎng)關(guān)需要支持SSEServer-Sent Events的透?jìng)?。這里要注意流式響應(yīng)下token計(jì)數(shù)和成本統(tǒng)計(jì)需要在流結(jié)束后才能準(zhǔn)確計(jì)算不能在請(qǐng)求發(fā)出時(shí)就確定。所以計(jì)費(fèi)邏輯要能處理“先調(diào)用、后結(jié)算”的模式。3. 自動(dòng)化編程與CLI工具鏈實(shí)踐3.1 為什么CLI在Agent時(shí)代重新重要起來這兩年Agent開發(fā)火起來之后一個(gè)有意思的現(xiàn)象是CLI工具重新變成了核心交互界面。原因在于Agent需要執(zhí)行具體操作——讀寫文件、運(yùn)行命令、調(diào)用API、操作Git——這些操作天然適合用命令行完成。相比圖形界面CLI更容易被程序調(diào)用也更容易組合成工作流。熱詞里出現(xiàn)的codex cli、gitlab cli、minimax cli、trae cli、openspec cli本質(zhì)上都是把某種能力封裝成命令行工具讓Agent或者開發(fā)者可以通過統(tǒng)一的方式調(diào)用。比如codex cli讓你在終端里直接和模型交互gitlab cli讓你用命令管理倉(cāng)庫(kù)這些工具的設(shè)計(jì)哲學(xué)是一致的把復(fù)雜操作收斂成一條命令降低調(diào)用方的認(rèn)知負(fù)擔(dān)。對(duì)于企業(yè)來說CLI工具鏈的價(jià)值在于可編排。你可以寫一個(gè)腳本依次調(diào)用幾個(gè)CLI完成“拉取代碼、運(yùn)行測(cè)試、生成報(bào)告、提交結(jié)果”的完整流程每個(gè)CLI只負(fù)責(zé)一件事組合起來就是自動(dòng)化流水線。3.2 codex cli的安裝與常見問題codex cli是近期討論度很高的一個(gè)工具安裝過程中最常見的問題就是熱詞里提到的那個(gè)報(bào)錯(cuò)missing optional dependency openai/codex-win32-x64. reinstall codex: npm in這個(gè)報(bào)錯(cuò)的本質(zhì)是codex cli依賴平臺(tái)特定的二進(jìn)制包npm在安裝時(shí)可能因?yàn)榫W(wǎng)絡(luò)原因或者平臺(tái)識(shí)別問題沒有正確拉取對(duì)應(yīng)的可選依賴。解決方法通常是先卸載再重裝npm uninstall -g openai/codex npm install -g openai/codex如果還是不行可以嘗試清除npm緩存后重裝npm cache clean --force npm install -g openai/codex在Windows環(huán)境下有時(shí)候需要確認(rèn)Node.js的版本是否匹配以及是否有權(quán)限寫入全局node_modules目錄。我個(gè)人的經(jīng)驗(yàn)是用nvm管理Node版本避免權(quán)限問題比直接裝系統(tǒng)級(jí)Node要省心很多。安裝完成后配置API key是下一步。codex cli通常讀取環(huán)境變量或者配置文件中的key。我建議不要把key寫在命令行歷史里而是通過環(huán)境變量注入export OPENAI_API_KEYyour-key-here然后在項(xiàng)目目錄下運(yùn)行codex cli它會(huì)自動(dòng)讀取當(dāng)前環(huán)境的配置。如果你有多個(gè)項(xiàng)目用不同的key可以在項(xiàng)目根目錄放一個(gè)配置文件codex cli會(huì)優(yōu)先讀取項(xiàng)目級(jí)配置。3.3 codex cli的常用命令與工作流codex cli提供了一組交互命令熱詞里提到的/compact、/model、/resume是其中比較常用的/model切換當(dāng)前會(huì)話使用的模型。不同任務(wù)用不同模型是常見做法簡(jiǎn)單問答用便宜的小模型復(fù)雜推理用大模型。/compact壓縮當(dāng)前會(huì)話的上下文。當(dāng)對(duì)話歷史太長(zhǎng)、接近上下文窗口上限時(shí)用這個(gè)命令把歷史摘要化騰出空間繼續(xù)對(duì)話。/resume恢復(fù)之前的會(huì)話。適合中斷后繼續(xù)之前的工作不用重新描述背景。我實(shí)際用下來的體會(huì)是把codex cli當(dāng)成一個(gè)可編程的結(jié)對(duì)助手而不是聊天窗口。你可以讓它讀一個(gè)文件、改一段代碼、跑一個(gè)測(cè)試然后根據(jù)結(jié)果繼續(xù)下一步。這種“命令式”的用法比純對(duì)話效率高很多因?yàn)槊恳徊蕉加忻鞔_的輸入和輸出。一個(gè)典型的工作流是這樣的先用/model選一個(gè)推理能力強(qiáng)的模型讓它分析一段代碼的問題確認(rèn)問題后切換到執(zhí)行速度快的模型讓它生成修改方案最后用命令行工具跑測(cè)試驗(yàn)證。整個(gè)過程在終端里完成不需要切換到瀏覽器。3.4 刪除與清理codex cli熱詞里有人問“刪除codex cli指令”這里補(bǔ)充一下。卸載codex cli用npm uninstall -g openai/codex但要注意卸載包本身不會(huì)刪除配置文件和會(huì)話歷史。這些通常存在用戶目錄下的隱藏文件夾里比如~/.codex或者~/.config/codex。如果你要徹底清理需要手動(dòng)刪除這些目錄。我建議在刪除前先備份會(huì)話歷史因?yàn)橛行┱{(diào)試記錄后面可能還用得上。4. Agent開發(fā)的核心概念與架構(gòu)4.1 Agent到底是什么和普通程序有什么區(qū)別熱詞里“agent是什么”“ai agent”“agent架構(gòu)”出現(xiàn)頻率很高說明很多人還在概念階段。我用一句話概括Agent是一個(gè)能感知環(huán)境、做出決策、執(zhí)行動(dòng)作、并根據(jù)反饋調(diào)整的循環(huán)系統(tǒng)。和普通程序的區(qū)別在于普通程序是“輸入→處理→輸出”的直線流程Agent是“感知→決策→執(zhí)行→觀察→再?zèng)Q策”的循環(huán)。普通程序遇到?jīng)]預(yù)料到的輸入會(huì)報(bào)錯(cuò)Agent會(huì)嘗試?yán)斫獠⒄{(diào)整策略。舉個(gè)例子普通程序讀取一個(gè)CSV文件如果格式不對(duì)就拋異常。Agent讀取同樣的文件發(fā)現(xiàn)格式不對(duì)會(huì)嘗試推斷正確的格式或者去問用戶或者換一種解析方式。這個(gè)“嘗試”的能力來自它背后的模型推理和工具調(diào)用。熱詞里“harness和agent區(qū)別”也是一個(gè)常見困惑。Harness通常指測(cè)試框架或者執(zhí)行環(huán)境負(fù)責(zé)給Agent提供運(yùn)行時(shí)的工具和約束Agent是決策主體。打個(gè)比方Harness是駕駛艙和儀表盤Agent是飛行員。飛行員做決策駕駛艙提供信息和操作接口。4.2 Agent的核心組件一個(gè)完整的Agent系統(tǒng)通常包含以下組件規(guī)劃模塊把用戶的目標(biāo)拆解成可執(zhí)行的步驟。比如“幫我整理這個(gè)項(xiàng)目的文檔”規(guī)劃模塊會(huì)拆成“掃描目錄、識(shí)別文檔類型、提取關(guān)鍵信息、生成匯總”。工具集Agent可以調(diào)用的外部能力比如讀寫文件、執(zhí)行命令、搜索、調(diào)用API。工具的設(shè)計(jì)要遵循“單一職責(zé)”一個(gè)工具只做一件事參數(shù)盡量簡(jiǎn)單。記憶模塊短期記憶保存當(dāng)前會(huì)話的上下文長(zhǎng)期記憶保存跨會(huì)話的知識(shí)。熱詞里“agent記憶”討論的就是這個(gè)。短期記憶通常用對(duì)話歷史實(shí)現(xiàn)長(zhǎng)期記憶需要向量數(shù)據(jù)庫(kù)或者結(jié)構(gòu)化存儲(chǔ)。執(zhí)行器實(shí)際調(diào)用工具、執(zhí)行動(dòng)作的組件。執(zhí)行器要處理超時(shí)、重試、錯(cuò)誤恢復(fù)。反饋循環(huán)觀察執(zhí)行結(jié)果判斷是否達(dá)到目標(biāo)如果沒有則調(diào)整策略繼續(xù)。這個(gè)循環(huán)的質(zhì)量決定了Agent的可靠性。4.3 Agent框架與編排的選擇熱詞里出現(xiàn)了很多框架名agent框架、agent scope、spring ai agent、adk.dev的Kotlin方案、基于Rust的Agent。我的建議是不要一上來就選框架先用最樸素的方式跑通一個(gè)最小Agent。最小Agent可以用幾百行代碼實(shí)現(xiàn)一個(gè)循環(huán)每次調(diào)用模型模型返回要執(zhí)行的動(dòng)作執(zhí)行后把結(jié)果喂回模型直到模型返回最終答案。跑通這個(gè)循環(huán)之后你才會(huì)真正理解Agent的瓶頸在哪里——是模型推理不穩(wěn)定還是工具調(diào)用出錯(cuò)還是上下文管理有問題。理解瓶頸之后再選框架就有依據(jù)了。如果你需要復(fù)雜的多Agent協(xié)作看agent scope這類編排框架如果你在JVM生態(tài)spring ai agent可能更順手如果你追求性能和并發(fā)Rust方案值得考慮。但框架解決的是工程問題不解決“Agent該做什么”的問題后者需要你自己想清楚。4.4 Agent安全不能忽視熱詞里“agent安全”是一個(gè)必須認(rèn)真對(duì)待的話題。Agent能執(zhí)行命令、讀寫文件、調(diào)用API這意味著一旦被惡意輸入操控后果可能很嚴(yán)重。我總結(jié)了幾條實(shí)踐原則第一最小權(quán)限。Agent能訪問的目錄、能調(diào)用的API嚴(yán)格限制在完成任務(wù)必需的范圍內(nèi)。第二操作確認(rèn)。涉及刪除、修改、發(fā)送等不可逆操作時(shí)要求人工確認(rèn)。第三輸入隔離。用戶輸入和系統(tǒng)指令要明確分隔防止提示注入。第四審計(jì)日志。Agent的每一步?jīng)Q策和動(dòng)作都要記錄便于事后追溯。這些原則聽起來簡(jiǎn)單但實(shí)際落地時(shí)容易被忽略。我見過有Agent直接以管理員權(quán)限運(yùn)行能讀寫整個(gè)文件系統(tǒng)這在生產(chǎn)環(huán)境是不可接受的。5. 大模型網(wǎng)關(guān)與Agent的協(xié)同落地5.1 網(wǎng)關(guān)如何支撐Agent的高并發(fā)熱詞里“ai agent怎么扛并發(fā)”是一個(gè)很實(shí)際的問題。Agent的并發(fā)壓力和普通API不同一個(gè)Agent任務(wù)可能包含幾十次模型調(diào)用每次調(diào)用的上下文長(zhǎng)度不同還有工具執(zhí)行的等待時(shí)間。這意味著并發(fā)不是簡(jiǎn)單的QPS概念而是“同時(shí)活躍的Agent任務(wù)數(shù) × 每個(gè)任務(wù)的平均調(diào)用頻率”。網(wǎng)關(guān)在這里的作用是削峰和隔離。通過限流防止某個(gè)Agent任務(wù)占滿所有模型配額通過優(yōu)先級(jí)保證交互式任務(wù)比后臺(tái)批處理任務(wù)優(yōu)先獲得資源通過緩存減少重復(fù)的模型調(diào)用。我實(shí)測(cè)下來一個(gè)配置合理的網(wǎng)關(guān)能把Agent任務(wù)的整體成功率提升不少因?yàn)樯嫌蜗蘖骱统瑫r(shí)被網(wǎng)關(guān)統(tǒng)一處理了Agent本身不用關(guān)心這些。具體做法上我建議給Agent任務(wù)分配獨(dú)立的租戶標(biāo)識(shí)在網(wǎng)關(guān)上設(shè)置專門的配額和優(yōu)先級(jí)。這樣即使Agent任務(wù)突發(fā)流量也不會(huì)影響其他業(yè)務(wù)線的正常調(diào)用。5.2 自動(dòng)化編程場(chǎng)景的網(wǎng)關(guān)配置自動(dòng)化編程是Agent的一個(gè)典型應(yīng)用場(chǎng)景讓Agent讀代碼、改代碼、跑測(cè)試、提交。這個(gè)場(chǎng)景對(duì)網(wǎng)關(guān)的要求有幾個(gè)特殊點(diǎn)長(zhǎng)上下文支持代碼文件可能很長(zhǎng)需要模型支持大上下文窗口。網(wǎng)關(guān)要能根據(jù)請(qǐng)求的token數(shù)路由到支持相應(yīng)窗口的模型。低延遲要求編程助手是交互式的用戶等待時(shí)間不能太長(zhǎng)。網(wǎng)關(guān)要能優(yōu)先路由到響應(yīng)快的渠道超時(shí)閾值要設(shè)置合理。成本敏感編程場(chǎng)景調(diào)用頻繁成本容易累積。網(wǎng)關(guān)的緩存和模型分級(jí)策略在這里價(jià)值很大——簡(jiǎn)單的代碼補(bǔ)全用小模型復(fù)雜的重構(gòu)建議用大模型。我一般的配置是給編程Agent設(shè)置兩個(gè)模型檔位快速檔用便宜的小模型處理補(bǔ)全和簡(jiǎn)單問答深度檔用大模型處理重構(gòu)和調(diào)試。網(wǎng)關(guān)根據(jù)請(qǐng)求的復(fù)雜度自動(dòng)路由或者由Agent顯式指定檔位。5.3 從開發(fā)到生產(chǎn)的檢查清單在把網(wǎng)關(guān)和Agent推向生產(chǎn)之前我建議對(duì)照這份清單逐項(xiàng)檢查檢查項(xiàng)具體要求常見遺漏密鑰管理上游key不落地業(yè)務(wù)代碼虛擬key可吊銷測(cè)試環(huán)境的key混用生產(chǎn)限流配置按租戶、按模型、按時(shí)間窗口只做了全局限流超時(shí)與重試區(qū)分連接超時(shí)和響應(yīng)超時(shí)重試有上限無限重試導(dǎo)致雪崩降級(jí)策略主渠道故障時(shí)切備用或返回緩存沒有備用渠道日志完整性記錄請(qǐng)求、響應(yīng)、耗時(shí)、token、成本只記成功不記失敗成本告警日/周成本超過閾值時(shí)通知月底才發(fā)現(xiàn)超支Agent權(quán)限最小權(quán)限危險(xiǎn)操作需確認(rèn)默認(rèn)全權(quán)限審計(jì)追溯能還原任意一次調(diào)用的完整鏈路日志分散在多處這份清單里的每一項(xiàng)我都在實(shí)際項(xiàng)目中見過因?yàn)檫z漏而引發(fā)的問題。尤其是“無限重試”和“沒有備用渠道”在供應(yīng)商偶發(fā)故障時(shí)會(huì)直接導(dǎo)致業(yè)務(wù)不可用。6. 常見問題與排查技巧實(shí)錄6.1 網(wǎng)關(guān)層面的典型故障問題一上游返回429業(yè)務(wù)側(cè)看到的是500。這是因?yàn)榫W(wǎng)關(guān)沒有正確處理供應(yīng)商的限流響應(yīng)直接透?jìng)髁隋e(cuò)誤碼。解決方法是網(wǎng)關(guān)識(shí)別429后要么重試其他渠道要么返回一個(gè)明確的“請(qǐng)求過多請(qǐng)稍后重試”提示而不是讓業(yè)務(wù)方困惑。問題二流式響應(yīng)中途斷開。常見原因是網(wǎng)關(guān)的超時(shí)設(shè)置比上游的流式輸出時(shí)間短。流式請(qǐng)求的超時(shí)應(yīng)該設(shè)置為“兩次數(shù)據(jù)塊之間的最大間隔”而不是整個(gè)請(qǐng)求的總時(shí)長(zhǎng)。問題三token計(jì)數(shù)和賬單對(duì)不上。這通常是因?yàn)榫W(wǎng)關(guān)只統(tǒng)計(jì)了成功請(qǐng)求沒有統(tǒng)計(jì)失敗但已經(jīng)消耗token的請(qǐng)求。有些供應(yīng)商在返回錯(cuò)誤前已經(jīng)處理了部分輸入這部分也要計(jì)費(fèi)。解決方法是記錄所有發(fā)往上游的請(qǐng)求無論成功失敗。6.2 Agent層面的典型故障問題一Agent陷入循環(huán)。表現(xiàn)是反復(fù)執(zhí)行同一個(gè)動(dòng)作無法推進(jìn)。原因通常是反饋信號(hào)不明確Agent無法判斷動(dòng)作是否成功。解決方法是在工具返回中增加明確的狀態(tài)標(biāo)識(shí)讓Agent能區(qū)分“成功”“失敗”“部分成功”。問題二上下文溢出。Agent任務(wù)執(zhí)行到一半上下文超過模型窗口。解決方法是用/compact類似的機(jī)制壓縮歷史或者把中間結(jié)果存到外部存儲(chǔ)只在上下文中保留摘要。問題三工具調(diào)用參數(shù)錯(cuò)誤。模型生成的工具調(diào)用參數(shù)格式不對(duì)導(dǎo)致執(zhí)行失敗。解決方法是在工具定義中提供清晰的參數(shù)說明和示例并在執(zhí)行前做參數(shù)校驗(yàn)校驗(yàn)失敗時(shí)把錯(cuò)誤信息返回給模型讓它修正。6.3 排查思路速查表現(xiàn)象可能原因排查方向響應(yīng)突然變慢上游限流或網(wǎng)絡(luò)抖動(dòng)查看網(wǎng)關(guān)日志中各渠道的耗時(shí)分布成本異常升高某租戶調(diào)用量突增或緩存失效按租戶聚合token消耗檢查緩存命中率Agent任務(wù)失敗率高模型輸出不穩(wěn)定或工具報(bào)錯(cuò)查看失敗任務(wù)的最后幾步動(dòng)作和返回密鑰報(bào)錯(cuò)key過期或額度耗盡檢查上游賬戶狀態(tài)和網(wǎng)關(guān)的key配置流式中斷超時(shí)設(shè)置或網(wǎng)絡(luò)問題檢查流式超時(shí)配置和中間網(wǎng)絡(luò)設(shè)備這張表是我在實(shí)際排障中總結(jié)的基本上覆蓋了八成以上的常見問題。遇到新問題時(shí)先對(duì)照這張表定位方向再去查具體日志比盲目翻代碼效率高得多。6.4 幾個(gè)容易踩的坑坑一在網(wǎng)關(guān)里做業(yè)務(wù)邏輯。網(wǎng)關(guān)應(yīng)該保持“薄”只做轉(zhuǎn)發(fā)和橫切關(guān)注點(diǎn)。一旦開始在網(wǎng)關(guān)里寫業(yè)務(wù)判斷它就會(huì)變成難以維護(hù)的巨石。業(yè)務(wù)邏輯放在業(yè)務(wù)側(cè)網(wǎng)關(guān)只提供通用能力?？佣雎岳鋯?dòng)。網(wǎng)關(guān)剛啟動(dòng)時(shí)連接池是空的第一批請(qǐng)求會(huì)明顯變慢。解決方法是啟動(dòng)時(shí)預(yù)熱連接池或者用健康檢查提前建立連接?？尤罩居涗浢舾行畔?。請(qǐng)求和響應(yīng)里可能包含用戶隱私數(shù)據(jù)日志要脫敏后再存儲(chǔ)。我見過有團(tuán)隊(duì)把完整的對(duì)話內(nèi)容明文存日志后來做合規(guī)審查時(shí)不得不全部清理?？铀腁gent工具沒有超時(shí)。一個(gè)工具調(diào)用卡住整個(gè)Agent任務(wù)就掛起。每個(gè)工具調(diào)用都要設(shè)置超時(shí)超時(shí)后返回明確的錯(cuò)誤讓Agent決定是重試還是換方案。這些坑的共同點(diǎn)是在開發(fā)環(huán)境不會(huì)暴露一到生產(chǎn)就出問題。所以我的建議是網(wǎng)關(guān)和Agent在上線前一定要做故障注入測(cè)試——手動(dòng)模擬上游超時(shí)、限流、返回錯(cuò)誤觀察系統(tǒng)的反應(yīng)。這個(gè)測(cè)試花的時(shí)間遠(yuǎn)比線上出故障后排查的時(shí)間少。我個(gè)人在實(shí)際操作中的體會(huì)是大模型網(wǎng)關(guān)和Agent的落地技術(shù)選型只占三成剩下七成是工程細(xì)節(jié)的打磨。統(tǒng)一API、限流、日志這些聽起來不酷但它們是系統(tǒng)能穩(wěn)定跑起來的基礎(chǔ)。Agent的智能程度取決于模型但Agent的可靠性取決于工程。先把工程做扎實(shí)再談智能這個(gè)順序不能反。