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