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