做平臺(tái)架構(gòu)這幾年我有個(gè)越來(lái)越強(qiáng)烈的體會(huì)AI 項(xiàng)目真正難的不是模型選型而是模型落地之后的“雜活”。模型換了一家性能更好的老業(yè)務(wù)代碼得跟著改A 部門接得飛起B(yǎng) 部門還抱著舊 SDK 不放好不容易跑通一條 Agent 鏈路模型一升級(jí)輸出格式直接崩給你看。你會(huì)發(fā)現(xiàn)所有團(tuán)隊(duì)都在圍繞“模型的不可控”和“系統(tǒng)的多樣化”做無(wú)邊無(wú)際的適配工作。這個(gè)矛盾堆到最后基本都會(huì)指向同一個(gè)解法——在網(wǎng)絡(luò)層和業(yè)務(wù)層之間塞一個(gè)專門管模型流量的“AI 網(wǎng)關(guān)”。它的作用可以一句話概括把大模型、Agent、內(nèi)部老系統(tǒng)全部掛在一個(gè)統(tǒng)一的出入口上模型變了你不用動(dòng)業(yè)務(wù)代碼老系統(tǒng)接新模型也不用重寫(xiě)接口Agent 團(tuán)隊(duì)甚至可以像訪問(wèn)一個(gè)普通服務(wù)一樣去調(diào)用多個(gè)模型。這篇文章我就把“AI 網(wǎng)關(guān)”這件事從設(shè)計(jì)思路、核心能力、選型對(duì)比、落地實(shí)操到排坑經(jīng)驗(yàn)完整地講一遍。不管你是架構(gòu)師、后端負(fù)責(zé)人還是正要搞 Agent 的工程師都值得看完。1. AI 網(wǎng)關(guān)到底在管什么1.1 模型層管不住API 越來(lái)越多治理跟不上先說(shuō)最直接的痛點(diǎn)。公司里一旦開(kāi)始正經(jīng)用 AI模型供應(yīng)方大概率不會(huì)只有一家。你可能有 OpenAI 系的模型、有開(kāi)源的 Qwen、有國(guó)產(chǎn)商業(yè) API也可能有自建微調(diào)模型。每個(gè)模型的鑒權(quán)方式不一樣有的用 API Key有的用 Bearer Token有的還要帶組織 ID每個(gè)模型的計(jì)價(jià)方式也不一樣有按 token 的有按調(diào)用次數(shù)的有按并發(fā)數(shù)的每個(gè)模型還有各自的頻率限制有的每分鐘 60 次有的每小時(shí) 1000 次。如果每個(gè)業(yè)務(wù)團(tuán)隊(duì)都自己對(duì)接那你最后會(huì)收獲一堆不可控的東西代碼里寫(xiě)死的模型 API Key、散落在各處的模型配置、誰(shuí)也不知道每個(gè)月花了多少錢的賬單一堆亂碼。更麻煩的是模型本身還經(jīng)常出問(wèn)題供應(yīng)商限流了、模型臨時(shí)不可用、新版本輸出格式變了。你在業(yè)務(wù)代碼里根本沒(méi)法快速響應(yīng)這些變化只能等著報(bào)錯(cuò)、改代碼、重新發(fā)布。AI 網(wǎng)關(guān)在這里的作用就是把“模型供應(yīng)”抽象成一種可插拔的統(tǒng)一資源。業(yè)務(wù)側(cè)只需要知道“我要調(diào)一個(gè)大語(yǔ)言模型走這個(gè)地址就行”網(wǎng)關(guān)負(fù)責(zé)具體選哪個(gè)模型、怎么鑒權(quán)、怎么計(jì)費(fèi)、怎么限流。當(dāng)我需要把主力模型從 A 換到 B 的時(shí)候只需要改網(wǎng)關(guān)側(cè)的配置業(yè)務(wù)代碼一行都不用動(dòng)。1.2 老系統(tǒng)接不上協(xié)議、鑒權(quán)、返回格式全是坑老系統(tǒng)接入 AI 的痛比新項(xiàng)目明顯得多。這里說(shuō)的老系統(tǒng)可能是運(yùn)行了五六年的 Java 服務(wù)可能是銀行對(duì)接場(chǎng)景下那種只能走 HTTP 的內(nèi)部系統(tǒng)也可能是一套還在用 SOAP 的歷史中間件。它們普遍有幾個(gè)共同問(wèn)題調(diào)用外部服務(wù)的方式極其固定改造成本高沒(méi)有統(tǒng)一的 API Key 管理規(guī)定對(duì)“長(zhǎng)連接”“流式傳輸”這種新玩法消化不良。舉例說(shuō)某個(gè)內(nèi)部 OA 系統(tǒng)想要接一個(gè)“智能摘要”的能力它的技術(shù)棧是真的很舊只支持 POST JSON 后同步返回結(jié)果。但今天主流大模型 API 基本都是流式 SSE 輸出有的還要 WebSocket 或者長(zhǎng)輪詢。你讓老系統(tǒng)去改造支持 SSE不是不能做但開(kāi)發(fā)排期、聯(lián)調(diào)成本都很高。這時(shí)候如果有一個(gè) AI 網(wǎng)關(guān)在中間做“協(xié)議翻譯”事情就簡(jiǎn)單了。你可以讓老系統(tǒng)繼續(xù)用它的同步 POST網(wǎng)關(guān)在內(nèi)部把請(qǐng)求轉(zhuǎn)成流式調(diào)用攢齊完整響應(yīng)后再同步返回。老系統(tǒng)只看到一個(gè)普通的 HTTP 接口感知不到背后是流式還是非流式。這就是網(wǎng)關(guān)層做“適配”的核心價(jià)值——它把新世界的復(fù)雜協(xié)議翻譯成舊世界能聽(tīng)懂的話。1.3 Agent 連不起來(lái)多模型協(xié)作不是“調(diào)兩次 API”那么簡(jiǎn)單Agent 是這兩年最火的方向也是把 AI 網(wǎng)關(guān)問(wèn)題暴露得最徹底的場(chǎng)景。一個(gè)正經(jīng)的 Agent 系統(tǒng)背后通常要調(diào)度多個(gè)模型一個(gè)負(fù)責(zé)意圖識(shí)別一個(gè)負(fù)責(zé)工具調(diào)用一個(gè)負(fù)責(zé)生成最終回復(fù)可能還有一個(gè)負(fù)責(zé)反思和糾錯(cuò)。有的 Agent 還需要在多個(gè)任務(wù)之間切換模型比如簡(jiǎn)單任務(wù)用小模型省錢復(fù)雜任務(wù)用大模型保證質(zhì)量。如果你在代碼里硬編碼這些調(diào)用的目標(biāo)地址和 KeyAgent 的邏輯就會(huì)和模型供應(yīng)商深度綁定。模型一升級(jí)、地址一變化、限流策略一調(diào)整Agent 就直接躺平。更麻煩的是Agent 的調(diào)試和觀測(cè)成本本來(lái)就高你還很難說(shuō)清楚“這次 Agent 行為異常到底是因?yàn)槟Ｐ洼敵霾粚?duì)還是工具調(diào)用失敗還是上下文被截?cái)嗔恕?。AI 網(wǎng)關(guān)能把 Agent 對(duì)模型的依賴降級(jí)為對(duì)“一個(gè)服務(wù)”的依賴。Agent 不需要關(guān)心模型是 GPT 還是 Qwen只需要告訴網(wǎng)關(guān)“我這次任務(wù)比較難給我用高智能模型”網(wǎng)關(guān)來(lái)做路由、限流、降級(jí)、日志跟蹤。這樣一來(lái)Agent 的開(kāi)發(fā)和迭代速度會(huì)有非常明顯的提升因?yàn)槟Ｐ偷摹凹夹g(shù)債”被網(wǎng)關(guān)接住了。2. AI 網(wǎng)關(guān)的核心設(shè)計(jì)邏輯先想清楚要管什么2.1 統(tǒng)一抽象把“模型”變成可替換資源我自己最早做 AI 網(wǎng)關(guān)時(shí)犯過(guò)一個(gè)錯(cuò)誤一上來(lái)就想把所有模型 API 的全部參數(shù)都透?jìng)鞒鋈ソY(jié)果網(wǎng)關(guān)越做越像代理工具沒(méi)有真正的治理能力。后來(lái)我悟了網(wǎng)關(guān)的第一要義不是“原樣轉(zhuǎn)發(fā)”而是“定義一個(gè)公司內(nèi)部統(tǒng)一的模型調(diào)用抽象層”。這個(gè)抽象層大概長(zhǎng)這樣統(tǒng)一請(qǐng)求格式、統(tǒng)一返回格式、統(tǒng)一鑒權(quán)、統(tǒng)一錯(cuò)誤碼。這意味著不管底層是 OpenAI 風(fēng)格接口還是 Claude 風(fēng)格接口還是國(guó)產(chǎn)模型的特殊風(fēng)格到了網(wǎng)關(guān)這一層都要轉(zhuǎn)成內(nèi)部約定的標(biāo)準(zhǔn)格式。業(yè)務(wù)方只需要掌握一種調(diào)用方式剩下的由網(wǎng)關(guān)內(nèi)的“模型適配器”負(fù)責(zé)。這樣做還有一個(gè)隱藏好處當(dāng)你引入新模型時(shí)只需要寫(xiě)一個(gè)新的適配器而不需要說(shuō)服所有業(yè)務(wù)團(tuán)隊(duì)改代碼。模型團(tuán)隊(duì)和業(yè)務(wù)團(tuán)隊(duì)之間的協(xié)作邊界一下子就清晰了——業(yè)務(wù)團(tuán)隊(duì)直接對(duì)接網(wǎng)關(guān)模型團(tuán)隊(duì)只跟網(wǎng)關(guān)的適配器層打交道。我后面會(huì)詳細(xì)展示這個(gè)適配器層該怎么設(shè)計(jì)。2.2 流控與降級(jí)別讓模型供應(yīng)商把你拖死模型供應(yīng)商的 API 并不總是可靠的這是所有 AI 網(wǎng)關(guān)都必須正視的事實(shí)。在實(shí)際運(yùn)營(yíng)中你會(huì)遇到供應(yīng)商限流、區(qū)域網(wǎng)絡(luò)抖動(dòng)、模型臨時(shí)過(guò)載、甚至 Key 被封禁等一堆情況。如果不做流控和降級(jí)任何一個(gè)供應(yīng)商出問(wèn)題都會(huì)直接打到業(yè)務(wù)上。流控這件事不能只看“每分鐘調(diào)用次數(shù)”。你需要做的是多維度限流按調(diào)用方哪個(gè)部門、哪個(gè)應(yīng)用、按模型哪個(gè)供應(yīng)商、按時(shí)間窗口分鐘/小時(shí)/天。比如你有一個(gè)內(nèi)部工具應(yīng)用每天調(diào)大模型幾千次它在高峰期把供應(yīng)商額度全打光了另一個(gè)核心業(yè)務(wù)卻等著同一個(gè)模型出結(jié)果那就麻煩了。所以一定要在網(wǎng)關(guān)層做好“優(yōu)先級(jí)流控”核心業(yè)務(wù)保底非核心業(yè)務(wù)可以排隊(duì)、降級(jí)、或者直接拒絕。降級(jí)策略同樣重要。常規(guī)做法是給同一個(gè)模型組配置多個(gè)可用供應(yīng)源主模型掛了自動(dòng)切備用。比如 A 模型供應(yīng)商整體超時(shí)網(wǎng)關(guān)直接轉(zhuǎn)給 B 供應(yīng)商的等價(jià)模型。更復(fù)雜一點(diǎn)的還可以做“智能降級(jí)”如果用戶輸入很短、任務(wù)簡(jiǎn)單可以自動(dòng)降到一個(gè)小模型延遲低還省錢只有復(fù)雜任務(wù)才走到大模型。網(wǎng)關(guān)把這些策略配置化之后業(yè)務(wù)方完全不需要感知。2.3 審計(jì)與安全你的系統(tǒng)需要知道誰(shuí)在調(diào)模型AI 網(wǎng)關(guān)還有一個(gè)容易被忽視、但特別重要的職責(zé)審計(jì)與安全。大模型服務(wù)本質(zhì)上是一個(gè)黑盒外部依賴你把企業(yè)內(nèi)部數(shù)據(jù)發(fā)給它這里面的合規(guī)風(fēng)險(xiǎn)、數(shù)據(jù)安全風(fēng)險(xiǎn)都是實(shí)際存在的。如果沒(méi)有任何審計(jì)機(jī)制你壓根不知道哪個(gè)部門把什么數(shù)據(jù)發(fā)給了哪個(gè)模型。網(wǎng)關(guān)的統(tǒng)一出口優(yōu)勢(shì)在這里體現(xiàn)得很充分。所有模型請(qǐng)求都過(guò)網(wǎng)關(guān)你就能在網(wǎng)關(guān)層記錄誰(shuí)在什么時(shí)間、調(diào)用了哪個(gè)模型、上傳了什么 Content、消耗了多少 token、返回結(jié)果是什么。這些日志可以作為事后審計(jì)依據(jù)也可以用來(lái)做成本拆分——月底給各個(gè)部門出賬單的時(shí)候直接從網(wǎng)關(guān)日志里拉數(shù)據(jù)清清楚楚。安全方面網(wǎng)關(guān)側(cè)至少要做到幾件事敏感信息脫敏比如請(qǐng)求里的身份證號(hào)、手機(jī)號(hào)在日志里自動(dòng)打星號(hào)IP 白名單/內(nèi)網(wǎng)訪問(wèn)控制針對(duì)模型返回內(nèi)容的合規(guī)檢查比如判斷是否存在涉政、涉黃等違規(guī)內(nèi)容再返回給用戶。這幾點(diǎn)加在一起才能讓業(yè)務(wù)方放心把數(shù)據(jù)流交給一個(gè)統(tǒng)一入口。我自己做的時(shí)候還把“用戶身份標(biāo)識(shí)”強(qiáng)制加入了調(diào)用鏈意思是網(wǎng)關(guān)會(huì)要求每個(gè)業(yè)務(wù)請(qǐng)求必須帶一個(gè)業(yè)務(wù)側(cè)的用戶 ID方便事后定位問(wèn)題而不是只看到一個(gè)應(yīng)用級(jí)別的 Key。3. 技術(shù)選型自建、開(kāi)源還是云托管3.1 三個(gè)選型方向的適用場(chǎng)景聊完設(shè)計(jì)邏輯進(jìn)入實(shí)操層面。第一步肯定是選型AI 網(wǎng)關(guān)這個(gè)領(lǐng)域現(xiàn)在也有不少輪子了不必什么都自己造。大體上分三個(gè)方向自研輕量網(wǎng)關(guān)、基于開(kāi)源項(xiàng)目二次開(kāi)發(fā)、直接采購(gòu)云托管網(wǎng)關(guān)。自研輕量網(wǎng)關(guān)適合什么場(chǎng)景你的業(yè)務(wù)形態(tài)極其特殊比如要對(duì)接公司內(nèi)部自研模型的 RPC 協(xié)議或者有非常強(qiáng)的私有化安全要求必須把網(wǎng)關(guān)部署在完全隔離的內(nèi)網(wǎng)并且要做一些非標(biāo)準(zhǔn)的擴(kuò)展。自研的優(yōu)勢(shì)是靈活性極高但代價(jià)是后續(xù)的穩(wěn)定性、性能、觀測(cè)能力都得自己一點(diǎn)點(diǎn)填。開(kāi)源項(xiàng)目二次開(kāi)發(fā)是當(dāng)前的主流選擇。比較常見(jiàn)的有 LiteLLM、Higress AI 網(wǎng)關(guān)、Portkey 網(wǎng)關(guān)等。它們的共同點(diǎn)是把“統(tǒng)一模型抽象”“多供應(yīng)商路由”“限流降級(jí)”“日志審計(jì)”這些基礎(chǔ)能力都做好了你拿來(lái)部署改一改配置再按需加一個(gè)自定義插件就能貼合自己公司的場(chǎng)景。我建議大多數(shù)團(tuán)隊(duì)從這個(gè)方向起步。云托管網(wǎng)關(guān)則是“開(kāi)箱即用”路線。像很多云廠商現(xiàn)在都提供 AI 網(wǎng)關(guān)服務(wù)你只要把模型 API Key 填進(jìn)去它自動(dòng)幫你做代理、監(jiān)控、計(jì)費(fèi)。適合手上云資源已經(jīng)用得很深、不想自己運(yùn)維的團(tuán)隊(duì)。缺點(diǎn)是你對(duì)網(wǎng)關(guān)內(nèi)部的策略邏輯把控力弱想要搞一些“非常規(guī)”的路由策略會(huì)比較費(fèi)勁。3.2 開(kāi)源方案橫向?qū)Ρ确桨附尤敕绞较蘖?降級(jí)觀測(cè)能力二次開(kāi)發(fā)成本適合場(chǎng)景LiteLLMPython 庫(kù) / 代理服務(wù)基礎(chǔ)限流、多模型 fallback有日志、可自定義導(dǎo)出低Python 生態(tài)友好中小團(tuán)隊(duì)快速接入偏 Python 技術(shù)棧Higress AI 網(wǎng)關(guān)獨(dú)立網(wǎng)關(guān)支持 K8s 部署插件式限流、灰度、熔斷集成 Prometheus / 阿里云 SLS中需要了解插件機(jī)制已有 K8s/微服務(wù)體系的團(tuán)隊(duì)Portkey云服務(wù) / 自托管較強(qiáng)支持多級(jí)緩存自帶觀測(cè)面板低但深度定制需商業(yè)版想要快速上線且重視可觀測(cè)性的團(tuán)隊(duì)我實(shí)測(cè)下來(lái)的感受是如果團(tuán)隊(duì)偏 Python、希望盡快跑起來(lái)驗(yàn)證效果LiteLLM 很順手如果公司已經(jīng)有成熟的 K8s 基礎(chǔ)設(shè)施對(duì)網(wǎng)關(guān)性能和治理能力要求比較高Higress 這類獨(dú)立網(wǎng)關(guān)更持久如果只想給 Agent 項(xiàng)目加個(gè)可控入口Portkey 的開(kāi)箱體驗(yàn)確實(shí)省心。3.3 我最終選擇的方案與理由我自己的最終選擇是“開(kāi)源網(wǎng)關(guān) 少量自研”具體組合是底層用 LiteLLM 作為模型路由和適配核心前面加一層 Nginx 做流量控制和簡(jiǎn)單的 IP 白名單再配套一套自研的配置管理接口和審計(jì)日志存儲(chǔ)。這么選主要看中了三點(diǎn)。第一LiteLLM 對(duì)主流模型格式的兼容性做得非常好接入 OpenAI、Anthropic、Azure OpenAI、各種開(kāi)源模型服務(wù)都很快不用自己寫(xiě)一堆適配器。第二它的多模型 fallback 功能支持在請(qǐng)求層面配置“主模型失敗后自動(dòng)走備選模型”這是我業(yè)務(wù)中最急需的能力省了我自己寫(xiě)重試邏輯。第三團(tuán)隊(duì)整體偏 Python 和 Node.jsLiteLLM 的生態(tài)貼合度更高。自研的部分則聚焦在“企業(yè)定制需求”上比如把網(wǎng)關(guān)的管理接口接入內(nèi)部權(quán)限系統(tǒng)、把審計(jì)日志同步到公司的日志平臺(tái)等等這些開(kāi)源方案給不了只能自己補(bǔ)。4. 從零落地一個(gè)輕量 AI 網(wǎng)關(guān)實(shí)操4.1 最小架構(gòu)與目錄設(shè)計(jì)下面我拿一個(gè)簡(jiǎn)化版的自研 AI 網(wǎng)關(guān)示例幫你把上面的設(shè)計(jì)思路落到代碼里。這個(gè)示例不追求生產(chǎn)級(jí)完整度但能讓你看清核心鏈路長(zhǎng)什么樣統(tǒng)一接入層、模型路由、協(xié)議適配、審計(jì)日志、以及給 Agent 和舊系統(tǒng)用的專用接口。ai-gateway/ ├── main.py # FastAPI 入口統(tǒng)一暴露 HTTP 接口 ├── config.yaml # 模型供應(yīng)商、路由策略、限流閾值配置 ├── router.py # 模型路由核心邏輯 ├── adapters/ # 協(xié)議適配器目錄 │ ├── openai_adapter.py │ ├── qwen_adapter.py │ └── fallback_adapter.py ├── middleware/ │ ├── auth.py # 內(nèi)部應(yīng)用鑒權(quán) │ ├── audit.py # 審計(jì)日志 │ └── ratelimit.py # 簡(jiǎn)單限流 └── client_demo/ # 存放對(duì)接示例代碼其實(shí)你不用照著這個(gè)目錄原樣抄關(guān)鍵是理解它的分層邏輯路由和適配分開(kāi)原因在于“路由決定去哪個(gè)模型適配決定怎么跟那個(gè)模型說(shuō)話”。如果混在一起寫(xiě)每加一個(gè)模型就要?jiǎng)勇酚纱a很容易出 bug。4.2 實(shí)現(xiàn)統(tǒng)一模型路由路由層的核心是根據(jù)請(qǐng)求里的元信息選擇正確的模型。我常用的做法是讓業(yè)務(wù)方在請(qǐng)求 Header 里帶兩個(gè)字段一個(gè)是X-Tenant-ID租戶/部門標(biāo)識(shí)另一個(gè)是X-Model-Tier模型檔位比如fast/smart/expensive。網(wǎng)關(guān)拿到這兩個(gè)字段后結(jié)合配置中心的路由表決定最終調(diào)哪個(gè)模型。# router.py 核心片段 MODEL_TIERS { fast: [qwen-turbo, gpt-4o-mini], smart: [qwen-max, gpt-4o], expensive: [o1-preview], } def resolve_model(tenant_id: str, tier: str) - str: candidates MODEL_TIERS.get(tier, []) if not candidates: raise ValueError(funknown model tier: {tier}) # 根據(jù)租戶這個(gè)月的消耗情況決定是否用便宜檔位 if get_tenant_quota_remaining(tenant_id) 100: return qwen-turbo return candidates[0]這個(gè)設(shè)計(jì)的好處是業(yè)務(wù)方不用感知具體模型名只用表達(dá)“我要什么樣的智能程度”。這樣當(dāng)模型團(tuán)隊(duì)上線了新模型或者采購(gòu)策略調(diào)整只需要在配置中心改MODEL_TIERS映射業(yè)務(wù)代碼完全不用動(dòng)。從我的實(shí)踐經(jīng)驗(yàn)看這是網(wǎng)關(guān)層最有價(jià)值的設(shè)計(jì)之一。4.3 接上老系統(tǒng)協(xié)議適配器協(xié)議適配器是網(wǎng)關(guān)里最“臟活累活”的部分也是老系統(tǒng)能順利接入的關(guān)鍵。我這邊處理過(guò)幾種典型情況老系統(tǒng)只支持同步 HTTP JSON 返回老系統(tǒng)拿不到 API Key 只能走內(nèi)部服務(wù)賬號(hào)老系統(tǒng)連不上外網(wǎng)需要網(wǎng)關(guān)側(cè)做代理轉(zhuǎn)發(fā)。下面這段偽代碼展示了一個(gè)最常用的“同步轉(zhuǎn)流式”適配場(chǎng)景。老系統(tǒng)發(fā)一個(gè)普通 POST網(wǎng)關(guān)內(nèi)部用流式方式調(diào)用大模型等全部 token 收齊后再一次性返回給老系統(tǒng)。# adapters/sync_to_stream_adapter.py import httpx, json async def call_model_with_sse_collect(url: str, payload: dict) - dict: async with httpx.AsyncClient() as client: async with client.stream(POST, url, jsonpayload) as resp: full_text async for line in resp.aiter_lines(): if not line.startswith(data:): continue data json.loads(line[5:].strip()) full_text data.get(delta, {}).get(content, ) return {result: full_text, usage: {total_tokens: len(full_text)}}老系統(tǒng)的接入流程也因此簡(jiǎn)化成三步把請(qǐng)求地址改成網(wǎng)關(guān)的地址把 Header 里的鑒權(quán)換成內(nèi)部服務(wù)賬號(hào)體系把返回結(jié)果里“嵌套的 content 字段”提取邏輯調(diào)整一下。整個(gè)過(guò)程不涉及老系統(tǒng)對(duì) SSE 的理解對(duì)老系統(tǒng)的改造成本壓到了最低。4.4 給 Agent 提供專用觀測(cè)端點(diǎn)Agent 場(chǎng)景下我對(duì)網(wǎng)關(guān)的要求會(huì)比普通業(yè)務(wù)接口更高因?yàn)?Agent 是多步驟、多模型的出了問(wèn)題很難靠人肉排查。我通常會(huì)在網(wǎng)關(guān)上加一個(gè)/v1/agent/traces的觀測(cè)端點(diǎn)用于記錄一次 Agent 完整運(yùn)行過(guò)程中調(diào)用了哪些模型、每次調(diào)用的耗時(shí)、token 消耗、以及每個(gè)環(huán)節(jié)的輸入輸出摘要。# 在網(wǎng)關(guān)記錄 Agent 調(diào)用鏈 app.post(/v1/agent/traces) async def record_agent_trace(trace: AgentTrace): trace.trace_id uuid4().hex save_trace_to_storage(trace) return {trace_id: trace.trace_id}有了這個(gè) trace_idAgent 開(kāi)發(fā)者在出問(wèn)題時(shí)可以直接去日志平臺(tái)拉取整條鏈路看到底是哪個(gè)模型返回異常、哪個(gè)工具調(diào)用超時(shí)、哪一步的上下文被截?cái)唷＿@個(gè)能力在自研 Agent 項(xiàng)目中的價(jià)值極大。畢竟 Agent 的調(diào)試本身就是難點(diǎn)如果網(wǎng)關(guān)能提前把關(guān)鍵鏈路數(shù)據(jù)沉淀下來(lái)排查效率能翻倍。5. Agent 場(chǎng)景下的高級(jí)玩法5.1 多模型路由與 Failover 鏈路Agent 場(chǎng)景里Failover 不是“可選功能”而是“保命功能”。因?yàn)?Agent 的任務(wù)往往是長(zhǎng)鏈路一旦中途模型供應(yīng)商限流或超時(shí)整個(gè)任務(wù)就可能前功盡棄。一個(gè)好的做法是在網(wǎng)關(guān)層為 Agent 任務(wù)設(shè)計(jì)多級(jí) fallback 鏈路主模型失敗后自動(dòng)切換到備胎模型備胎模型也失敗再切換到本地輕量模型兜底。比如一個(gè)意圖識(shí)別模型正常走qwen-max一旦 qwen-max 連續(xù)兩次超時(shí)網(wǎng)關(guān)自動(dòng)把流量切到gpt-4o-mini這樣 Agent 至少不會(huì)因?yàn)槟Ｐ筒豢捎枚袛?。切流量這個(gè)動(dòng)作對(duì) Agent 來(lái)說(shuō)是透明的它只看到“調(diào)用網(wǎng)關(guān)還是成功的只是響應(yīng)速度變慢了或者模型換了一個(gè)”。Failover 鏈路的配置通常放在網(wǎng)關(guān)的配置中心里這樣可以在不改代碼的情況下動(dòng)態(tài)調(diào)整。5.2 技能注冊(cè)與模型分配策略有些 Agent 框架會(huì)允許開(kāi)發(fā)者注冊(cè)“技能節(jié)點(diǎn)”比如“搜索工具”“代碼執(zhí)行器”“知識(shí)庫(kù)檢索”。這些技能節(jié)點(diǎn)在調(diào)用模型時(shí)往往需要不同的模型參數(shù)和不同的計(jì)費(fèi)策略。網(wǎng)關(guān)在這個(gè)場(chǎng)景下可以做一個(gè)“技能感知路由”根據(jù) Agent 傳過(guò)來(lái)的技能標(biāo)識(shí)自動(dòng)匹配最適合的模型和超時(shí)時(shí)間。我做過(guò)一個(gè)比較有效的設(shè)計(jì)網(wǎng)關(guān)維護(hù)一個(gè)“技能到模型檔位”的映射表例如代碼生成類技能默認(rèn)走smart檔知識(shí)庫(kù)問(wèn)答類技能默認(rèn)走fast檔長(zhǎng)文本摘要?jiǎng)t走expensive檔。Agent 在上游只聲明“我這個(gè)節(jié)點(diǎn)是代碼生成”網(wǎng)關(guān)自己決定用哪個(gè)模型。這樣有兩個(gè)直接好處一是 Agent 邏輯更干凈不摻和模型選擇二是新模型上線可以直接通過(guò)改映射表生效連 Agent 代碼都不需要重新發(fā)版。5.3 上下文與配額管理Agent 的上下文管理是我在網(wǎng)關(guān)實(shí)踐中踩坑最多的點(diǎn)。起初我以為上下文處理是 Agent 框架自己的事后來(lái)發(fā)現(xiàn)如果不在網(wǎng)關(guān)層做統(tǒng)一管控就會(huì)出現(xiàn)Agent 開(kāi)發(fā)者在每個(gè)節(jié)點(diǎn)手動(dòng)拼 prompt拼著拼著把關(guān)鍵系統(tǒng)提示詞覆蓋了或者把歷史消息里的大段工具返回全塞進(jìn)去token 成本直接失控。在網(wǎng)關(guān)層面能做的事情有兩件。第一限制單次請(qǐng)求的最大輸入 token 數(shù)超出部分直接報(bào)錯(cuò)或自動(dòng)截?cái)啾苊饽Ｐ鸵驗(yàn)?prompt 太長(zhǎng)而拒絕服務(wù)或產(chǎn)生低質(zhì)量回答。第二對(duì)系統(tǒng)消息和工具返回結(jié)果做結(jié)構(gòu)化區(qū)分在網(wǎng)關(guān)日志里單獨(dú)記錄方便分析 Agent 到底消耗了多少 token 在“工具返回內(nèi)容”上。這個(gè)數(shù)據(jù)對(duì)后面的成本優(yōu)化很有價(jià)值。配額管理則主要面向多租戶場(chǎng)景。你可以給每個(gè)部門、每個(gè) Agent 項(xiàng)目設(shè)置每日/每月的 token 預(yù)算達(dá)到閾值后自動(dòng)降級(jí)到便宜的模型或者直接拒絕非核心請(qǐng)求。有了這個(gè)月底財(cái)務(wù)結(jié)算的時(shí)候就不需要人工去各個(gè)模型控制臺(tái)導(dǎo)賬單了直接用網(wǎng)關(guān)的配額報(bào)表就行。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 問(wèn)題排查速查表現(xiàn)象可能原因排查思路網(wǎng)關(guān)返回 401但業(yè)務(wù)側(cè)說(shuō) Key 沒(méi)問(wèn)題網(wǎng)關(guān)側(cè)未識(shí)別租戶身份檢查請(qǐng)求頭X-Tenant-ID是否傳遞以及該租戶是否有權(quán)限調(diào)用當(dāng)前模型檔位某個(gè)模型頻繁超時(shí)但供應(yīng)商控制臺(tái)顯示正常網(wǎng)關(guān)連接池不夠或網(wǎng)絡(luò)到供應(yīng)商側(cè)延遲高檢查網(wǎng)關(guān)到模型 API 的平均延遲調(diào)大連接池上限必要時(shí)啟 fallback 模型老系統(tǒng)接入后返回格式跟預(yù)期不一致網(wǎng)關(guān)適配層未做老系統(tǒng)兼容查看適配層里“同步轉(zhuǎn)流式”的邏輯確認(rèn)返回字段是否有額外嵌套Agent 任務(wù)中斷日志里沒(méi)有任何報(bào)錯(cuò)可能是上下文長(zhǎng)度超過(guò)模型上限但報(bào)錯(cuò)被吞了在網(wǎng)關(guān)層檢查請(qǐng)求的預(yù)估 token 數(shù)看是否觸發(fā)截?cái)嗷蚓芙^策略審計(jì)日志有流量但成本數(shù)據(jù)和模型控制臺(tái)對(duì)不上有請(qǐng)求走了緩存或 fallback 到低價(jià)模型核查該租戶是否有緩存策略以及 fallback 鏈路是否記錄到了實(shí)際使用模型這張表是我自己在運(yùn)維過(guò)程中積累的排錯(cuò)手冊(cè)。每次遇到線上問(wèn)題先對(duì)著表看一遍通常能定位個(gè)八九不離十。如果不在這個(gè)范圍里那基本就是網(wǎng)關(guān)自身的 bug 或者配置問(wèn)題再去代碼層排查。6.2 上線初期最容易踩的 5 個(gè)坑第一個(gè)坑是“網(wǎng)關(guān)變成新瓶頸”。這個(gè)隱患在我早期的測(cè)試環(huán)境中就暴露過(guò)所有模型流量都過(guò)網(wǎng)關(guān)但網(wǎng)關(guān)只開(kāi)了一個(gè)單實(shí)例模型響應(yīng)稍微慢一點(diǎn)線程池就堵死導(dǎo)致所有業(yè)務(wù)超時(shí)。我的建議是網(wǎng)關(guān)服務(wù)必須支持橫向擴(kuò)容并且要做好連接池和超時(shí)時(shí)間的調(diào)優(yōu)至少保證網(wǎng)關(guān)自身的處理速度要遠(yuǎn)快于模型響應(yīng)速度。第二個(gè)坑是“限流失真”。有一段時(shí)間我用的是單機(jī)版限流結(jié)果網(wǎng)關(guān)一擴(kuò)容限流就失效了因?yàn)槊總€(gè)節(jié)點(diǎn)各自算自己的請(qǐng)求數(shù)。后來(lái)把限流存儲(chǔ)換成 Redis 或者其他分布式存儲(chǔ)才算真正解決問(wèn)題。做限流之前先想清楚網(wǎng)關(guān)是不是要部署多節(jié)點(diǎn)別等到擴(kuò)容完才發(fā)現(xiàn)限流不準(zhǔn)。第三個(gè)坑是“日志太多但觀測(cè)不夠”。日志量大不代表你能快速定位問(wèn)題。我建議在網(wǎng)關(guān)側(cè)除了記錄原始請(qǐng)求日志還要埋一些關(guān)鍵指標(biāo)模型單次請(qǐng)求耗時(shí)、消耗 token 數(shù)、錯(cuò)誤類型分布、供應(yīng)商可用率。這些指標(biāo)通過(guò) Prometheus 采集再接上 Grafana 面板比單純翻日志有效得多。第四個(gè)坑是“fallback 配置太激進(jìn)”。我見(jiàn)過(guò)有團(tuán)隊(duì)把所有請(qǐng)求都配成主模型失敗后立即走備胎模型結(jié)果主模型偶發(fā)抖動(dòng)時(shí)流量全部涌向備胎模型備胎也被打崩。fallback 一定要加“健康檢查”和“連續(xù)失敗次數(shù)”的門檻不能一超時(shí)就連環(huán)切換。第五個(gè)坑是“忽略了模型輸出格式的差異”。不同模型對(duì)同樣的指令可能生成不同的 JSON 結(jié)構(gòu)尤其是老系統(tǒng)對(duì)接時(shí)這個(gè)問(wèn)題很容易被忽略。網(wǎng)關(guān)側(cè)最好對(duì)關(guān)鍵輸出做一次“格式規(guī)范化”比如強(qiáng)行提取 JSON 中的某個(gè)字段或者對(duì)返回做一次 schema 校驗(yàn)。這個(gè)能力看似簡(jiǎn)單但能避免很多線上兼容性問(wèn)題。6.3 性能調(diào)優(yōu)與成本控制建議性能調(diào)優(yōu)方面我最想強(qiáng)調(diào)的是“不要把網(wǎng)關(guān)做成同步阻塞的集中式設(shè)施”。很多業(yè)務(wù)方把網(wǎng)關(guān)當(dāng)成普通 API 網(wǎng)關(guān)用發(fā)一個(gè)請(qǐng)求等它轉(zhuǎn)發(fā)到模型模型流式返回再轉(zhuǎn)發(fā)回來(lái)。這個(gè)過(guò)程聽(tīng)起來(lái)沒(méi)問(wèn)題但如果并發(fā)一高網(wǎng)關(guān)的代理線程會(huì)被模型的長(zhǎng)時(shí)間占用拖垮。要解決這個(gè)問(wèn)題可以引入異步 I/O 和流式轉(zhuǎn)發(fā)網(wǎng)關(guān)不要攢完整響應(yīng)后再吐給客戶端而是邊收模型 token 邊轉(zhuǎn)發(fā)給調(diào)用方這樣網(wǎng)關(guān)注入的延遲幾乎可以忽略。成本控制方面我有三個(gè)比較有效的實(shí)踐。第一是緩存對(duì)重復(fù)性的請(qǐng)求比如相似的問(wèn)題、相似的知識(shí)庫(kù)檢索做語(yǔ)義緩存直接返回歷史結(jié)果或模板結(jié)果能省下可觀的大模型調(diào)用費(fèi)用。注意這個(gè)緩存必須做到“按租戶、按內(nèi)容哈?！彪p重維度不能緩存到用戶隱私數(shù)據(jù)。第二是 token 壓縮網(wǎng)關(guān)可以在轉(zhuǎn)發(fā)前把歷史對(duì)話做摘要壓縮減少每一輪調(diào)用的輸入 token 數(shù)量。第三是模型檔位選擇對(duì)周期性的非關(guān)鍵任務(wù)自動(dòng)切到低價(jià)模型跑比如凌晨的定時(shí)分析報(bào)告完全沒(méi)必要用最貴的大模型。7. 寫(xiě)在最后一個(gè)讓你少踩坑的實(shí)戰(zhàn)習(xí)慣如果你問(wèn)我AI 網(wǎng)關(guān)落地過(guò)程中最重要的經(jīng)驗(yàn)是什么我的回答不是技術(shù)選型也不是代碼細(xì)節(jié)而是“上線前把統(tǒng)一的接入規(guī)范文檔寫(xiě)好”。剛開(kāi)始做網(wǎng)關(guān)的時(shí)候我以為把接口部署好大家自然就會(huì)用了。后來(lái)發(fā)現(xiàn)業(yè)務(wù)團(tuán)隊(duì)根本不知道怎么表達(dá)自己的模型需求有的傳模型名有的傳檔位有的啥都不傳全靠網(wǎng)關(guān)猜。我后來(lái)專門花了兩天時(shí)間寫(xiě)了一份《AI 網(wǎng)關(guān)接入指南》明確規(guī)定了每個(gè)部門和業(yè)務(wù)線必須上報(bào)的元數(shù)據(jù)字段、需要申請(qǐng)的權(quán)限等級(jí)、以及模型檔位的可選范圍。從那之后接入效率一下子上來(lái)了。另外一個(gè)習(xí)慣是每個(gè)新模型上線先在網(wǎng)關(guān)上做一周的灰度只放 5% 的流量過(guò)去觀察延遲、錯(cuò)誤率和 token 消耗穩(wěn)定后再慢慢切到全量。不要因?yàn)槟硞€(gè)模型“聽(tīng)起來(lái)很強(qiáng)”就直接全量切你永遠(yuǎn)不知道它在實(shí)際業(yè)務(wù)場(chǎng)景會(huì)輸出什么奇怪的東西。網(wǎng)關(guān)的價(jià)值恰恰在于它能讓你“灰度切換模型”這件事變得無(wú)比輕松。最后說(shuō)一句AI 網(wǎng)關(guān)不是一個(gè)固定形態(tài)的“盒子”它是你公司模型治理體系的載體。剛開(kāi)始可以做得輕一點(diǎn)先解決“統(tǒng)一入口”的問(wèn)題等用的人多了再加限流、審計(jì)、緩存、配額這些高級(jí)能力。重要的是先把入口立起來(lái)讓所有模型流量有跡可循后續(xù)的治理才有素材和抓手。