項(xiàng)目里要接 AI 大模型了我把多廠商網(wǎng)關(guān)、場景配額、調(diào)用日志一次性做成了腳手架導(dǎo)讀業(yè)務(wù)方提需求給客服加個 AI 助手“給簡歷做個 OCR 識別”一個接一個。最早是各業(yè)務(wù)自己 new 一個 SDK 調(diào)密鑰散在 yml 里出了事還沒法查是誰調(diào)的。后來我把 AI 調(diào)用收斂成了一個獨(dú)立模塊多廠商 SPI、場景配置、配額限流、調(diào)用日志全在里面。先交代一下當(dāng)時的狀態(tài)。項(xiàng)目里要接大模型的地方越來越多智能客服、簡歷 OCR、內(nèi)容潤色、知識庫問答。一開始圖省事每個功能直接引 SDKDeepSeek 的、通義的、OpenAI 兼容的一起上。半年后發(fā)現(xiàn)三個問題密鑰管理混亂有人把 key 寫進(jìn) yml 提交了、沒法審計(jì)誰在什么時候調(diào)了多少 token 完全不知道、換廠商要改業(yè)務(wù)代碼。于是我在腳手架里加了qkl-ai模塊核心思路就一句話業(yè)務(wù)方不關(guān)心用的是哪家大模型只認(rèn)場景編碼。SPI 抽象所有廠商長一個樣先把各家 SDK 的差異吃掉。定義一個AiModelClient接口流式、非流式、對話、Embedding 都收斂進(jìn)去publicinterfaceAiModelClient{/** 廠商編碼如 DASHSCOPE / DOUBAO / OPENAI */StringproviderCode();/** 非流式對話 */ChatResultchat(ChatRequestrequest);/** 流式對話SSE */voidchatStream(ChatRequestrequest,StreamCallbackcallback);/** 文本向量化RAG 用 */Listembed(Listtexts);/** 連通性測試后臺測試連接按鈕用 */ConnectivityTestResulttestConnectivity();}實(shí)現(xiàn)類各自繼承一個AbstractOpenAiCompatibleClient——現(xiàn)在主流廠商都兼容 OpenAI 協(xié)議改個 baseUrl 和鑒權(quán)頭就行真正要手寫協(xié)議適配的很少。我用的是 DashScope、Doubao、OpenAI 三家全部走這個抽象ComponentpublicclassDoubaoCompatibleClientextendsAbstractOpenAiCompatibleClient{OverridepublicStringproviderCode(){returnDOUBAO;}OverrideprotectedStringresolveBaseUrl(AiProviderprovider){returnhttps://ark.cn-beijing.volces.com/api/v3;}OverrideprotectedMapresolveHeaders(AiProviderprovider){returnMap.of(Authorization,Bearer provider.getApiKey());}}客戶端注冊進(jìn)AiModelClientRegistry按providerCode取業(yè)務(wù)層永遠(yuǎn)不知道具體實(shí)現(xiàn)是誰。場景配置業(yè)務(wù)方只傳場景編碼接口暴露給業(yè)務(wù)方的就一個方法chat(scene, messages)。場景對應(yīng)哪家廠商、哪個模型、什么系統(tǒng)提示詞、溫度多少全在qkl_ai_scene表里配// 場景實(shí)體關(guān)鍵字段privateStringscene;// 場景編碼CUSTOMER_SERVICE / RESUME_OCR / CONTENT_POLISHprivateStringproviderCode;// 走哪家廠商privateStringmodelCode;// 模型編碼privateStringsystemPrompt;// 系統(tǒng)提示詞privateIntegertemperature;// 采樣溫度privateIntegerstatus;// 1 啟用 0 停用加一個新場景運(yùn)營在后臺插一條記錄開發(fā)一行代碼都不用改。之前那種新場景要改代碼發(fā)版的日子算是過去了。配額 限流防的是失控不是防人AI 調(diào)用是要花錢的必須有兩道閘。第一道是租戶維度日 token 配額第二道是Redis 窗口限流publicvoidconsume(StringtenantId,inttokens){AiQuotaquotagetOrCreate(tenantId);resetIfNewDay(quota);// 跨天自動歸零longusedquota.getDailyTokenUsed()null?0L:quota.getDailyTokenUsed();quota.setDailyTokenUsed(usedtokens);quotaMapper.updateById(quota);}publicvoidassertAllowed(){StringidentitycurrentUser();StringkeyRedisKeys.rateApi(ai.chat,user,identity);LongcurrentredisTemplate.opsForValue().increment(key);if(current!nullcurrent1){redisTemplate.expire(key,Duration.ofSeconds(Math.max(1,aiProperties.getRateLimitPeriod())));}if(current!nullcurrentaiProperties.getRateLimitCount()){thrownewQklBizException(ErrorCode.RATE_LIMITED,操作太頻繁請稍后再試);}}配額超了就拋當(dāng)日額度已用完前端友好提示限流超了就 429 類錯誤防止腳本刷。密鑰加密 調(diào)用日志出事能追責(zé)密鑰不落 yml存庫的時候加密用AiSecretCipher包了一層解密只在真正發(fā)起調(diào)用時進(jìn)行privateStringdecryptSecret(AiProviderprovider){returnsecretCipher.decrypt(provider.getApiKeyEncrypted());}每次調(diào)用無論成敗都落qkl_ai_call_log場景、模型、輸入輸出 token 數(shù)、耗時、結(jié)果狀態(tài)、失敗原因。日志保留 90 天出了事故翻日志就能還原誰、什么時候、調(diào)了什么、花了多少 token。踩坑記錄總開關(guān)一關(guān)整個模塊靜默消失問題現(xiàn)象本地沒配 AI 相關(guān)配置啟動項(xiàng)目后調(diào)用/admin/ai/scene接口返回70001頁面上一臉懵。排查過程翻代碼發(fā)現(xiàn)qkl.ai.enable默認(rèn)是falseAiAutoConfiguration用ConditionalOnProperty控制開關(guān)沒開時整個模塊的 Bean 都不注冊管理端接口統(tǒng)一返回業(yè)務(wù)碼 70001模塊未啟用。定位思路這個設(shè)計(jì)本身沒問題——AI 密鑰是敏感配置不該讓沒開通的租戶看到界面。但報錯信息太含糊前端看不出是沒啟用還是接口壞了。最終解決管理端接口把 70001 的 message 改成AI 模塊未啟用請?jiān)谂渲弥性O(shè)置 qkl.ai.enabletrue前端根據(jù)錯誤碼彈出明確提示。另外約定生產(chǎn)環(huán)境密鑰必須走配置中心/環(huán)境變量注入 cryptoSecret空 salt 回退邏輯只允許開發(fā)環(huán)境用防止線上密鑰可逆?？芍苯訌?fù)用的清單廠商差異用SPI 抽象 注冊中心吃掉業(yè)務(wù)層只認(rèn)場景編碼場景表配廠商模型提示詞新場景后臺配置即上線配額按租戶按天跨天自動歸零限流用 Redis increment expire 窗口密鑰加密存庫、調(diào)用時解密絕不進(jìn) yml 明文每次調(diào)用落日志保留 90 天審計(jì)追責(zé)全靠它模塊總開關(guān)用ConditionalOnProperty控制未啟用時錯誤提示要友好。這套 AI 網(wǎng)關(guān)是 qkl-boot 腳手架里的標(biāo)準(zhǔn)模塊。項(xiàng)目源碼https://gitee.com/gzqkl/qkl-boot