簡(jiǎn)介在大模型應(yīng)用快速落地的今天企業(yè)普遍面臨多廠商API協(xié)議不統(tǒng)一、密鑰分散、計(jì)費(fèi)不透明等痛點(diǎn)。API網(wǎng)關(guān)作為微服務(wù)架構(gòu)中的核心組件能夠在接入層統(tǒng)一處理鑒權(quán)、限流、路由與監(jiān)控這一原理同樣適用于大模型調(diào)用場(chǎng)景。通過協(xié)議適配機(jī)制將OpenAI、Claude、DeepSeek、通義千問等異構(gòu)供應(yīng)商接口轉(zhuǎn)換為標(biāo)準(zhǔn)格式結(jié)合Redis令牌桶限流、熔斷降級(jí)、AES-GCM密鑰加密存儲(chǔ)和用量計(jì)量計(jì)費(fèi)可以構(gòu)建一套輕量級(jí)LLM API統(tǒng)一管理系統(tǒng)。文章完整展示了基于Java 17、Spring Boot 3、Redis和MySQL的實(shí)現(xiàn)細(xì)節(jié)涵蓋從系統(tǒng)架構(gòu)設(shè)計(jì)、核心模塊編碼到Docker Compose部署上線的全流程并給出了流式響應(yīng)轉(zhuǎn)發(fā)、連接池調(diào)優(yōu)等真實(shí)踩坑經(jīng)驗(yàn)適合企業(yè)統(tǒng)一模型接入和畢業(yè)設(shè)計(jì)參考。 最近在做一個(gè)統(tǒng)一管理大模型 API 的項(xiàng)目調(diào)研了一圈市面上的方案要么太重、要么只適配單一廠商最后決定自己動(dòng)手實(shí)現(xiàn)一套 LLM API 統(tǒng)一管理系統(tǒng)。從項(xiàng)目立項(xiàng)、系統(tǒng)設(shè)計(jì)、源碼編寫到部署上線整個(gè)過程踩了不少坑今天把我的完整思路和核心代碼實(shí)現(xiàn)整理出來分享給大家。這個(gè)項(xiàng)目不只是一個(gè)簡(jiǎn)單的 API 轉(zhuǎn)發(fā)代理而是一套完整的管理體系統(tǒng)一協(xié)議轉(zhuǎn)換、多廠商適配、密鑰安全管控、限流熔斷、計(jì)量計(jì)費(fèi)、可視化監(jiān)控、審計(jì)日志全部都有。源碼和論文我都整理好了項(xiàng)目中使用到的設(shè)計(jì)模式、技術(shù)方案、關(guān)鍵配置本文都會(huì)給出具體實(shí)現(xiàn)細(xì)節(jié)。我寫代碼的工具這邊用的是 Java 17 Spring Boot 3 Redis MySQL Vue3這些技術(shù)棧比較主流方便有基礎(chǔ)的同學(xué)直接上手改造。如果你是剛開始接觸大模型應(yīng)用開發(fā)或者正在做畢設(shè)、公司內(nèi)部想搭一套統(tǒng)一的模型網(wǎng)關(guān)這篇文章應(yīng)該能幫到你。1. 為什么需要一套“統(tǒng)一管理”大模型 API1.1 大模型 API 擴(kuò)散帶來的真實(shí)痛點(diǎn)先說一個(gè)我實(shí)際工作中遇到的情況。公司內(nèi)部有好幾個(gè)業(yè)務(wù)團(tuán)隊(duì)算法團(tuán)隊(duì)接了 OpenAI 和 Claude后端團(tuán)隊(duì)接了 DeepSeek 和通義千問前端團(tuán)隊(duì)還自己注冊(cè)了智譜的 key。發(fā)展到后來每一個(gè)團(tuán)隊(duì)的代碼里都藏著半打 API key調(diào)用的協(xié)議五花八門OpenAI 用/v1/chat/completionsClaude 用/v1/messagesDeepSeek 兼容 OpenAI 但參數(shù)細(xì)節(jié)不完全相同通義千問又有一套自己的風(fēng)格。最頭疼的是下面幾個(gè)問題密鑰失控每個(gè)團(tuán)隊(duì)自己管 key什么時(shí)候過期了、有沒有超預(yù)算、被誰拿去調(diào)用了完全不可控。項(xiàng)目代碼倉庫的.env文件里就躺著好幾個(gè)生產(chǎn)環(huán)境 key。計(jì)費(fèi)不透明月底財(cái)務(wù)拿過來一堆大模型賬單根本分不清哪個(gè)業(yè)務(wù)線花得多、哪個(gè)頁面調(diào)得太頻繁甚至分不清哪部分是測(cè)試環(huán)境調(diào)的、哪部分是生產(chǎn)環(huán)境調(diào)的。切換廠商成本高今天 DeepSeek 的 API 不穩(wěn)定想臨時(shí)切到通義千問但因?yàn)楦骷覅f(xié)議不同代碼要改好幾處才能切過去改完還得回歸測(cè)試。重復(fù)代碼嚴(yán)重每個(gè)團(tuán)隊(duì)都自己封裝了一套“對(duì)接大模型的 SDK”只是參數(shù)略有不同。后來我統(tǒng)計(jì)了一下全公司至少有 7 套類似的封裝。1.2 這套系統(tǒng)要解決的核心問題所以我要做的這套 LLM API 統(tǒng)一管理系統(tǒng)核心目標(biāo)很明確所有業(yè)務(wù)方不直接對(duì)接任何一家大模型廠商而是統(tǒng)一走我們自己的網(wǎng)關(guān)。業(yè)務(wù)方的代碼里只出現(xiàn)一個(gè) baseURL用標(biāo)準(zhǔn)協(xié)議發(fā)請(qǐng)求由網(wǎng)關(guān)做協(xié)議適配、流量調(diào)度、密鑰管理和計(jì)量統(tǒng)計(jì)。這個(gè)思路跟微服務(wù)架構(gòu)里的 API 網(wǎng)關(guān)是一樣的把“鑒權(quán)、限流、路由、監(jiān)控”這些橫切關(guān)注點(diǎn)從業(yè)務(wù)代碼里剝出來下沉到網(wǎng)關(guān)層統(tǒng)一處理。這樣設(shè)計(jì)有幾個(gè)明顯的好處業(yè)務(wù)方接入成本極低統(tǒng)一協(xié)議后端只需要維護(hù)一套對(duì)接代碼廠商切換只發(fā)生在網(wǎng)關(guān)層業(yè)務(wù)代碼零改動(dòng)所有密鑰集中在網(wǎng)關(guān)側(cè)加密存儲(chǔ)從源頭上消滅密鑰散落的問題每一次調(diào)用都有日志、有計(jì)量、有審計(jì)成本歸屬一目了然2. 系統(tǒng)架構(gòu)與核心模塊設(shè)計(jì)2.1 整體分層思路整個(gè)系統(tǒng)的架構(gòu)并不復(fù)雜但設(shè)計(jì)的時(shí)候我特意按照“控制面”和“數(shù)據(jù)面”分離的思路來組織。所謂控制面就是管理后臺(tái)、配置中心、審計(jì)報(bào)表這些不直接參與請(qǐng)求轉(zhuǎn)發(fā)的部分?jǐn)?shù)據(jù)面則是真正處理 API 請(qǐng)求的網(wǎng)關(guān)核心鏈路。下面是系統(tǒng)分層的邏輯接入層面向業(yè)務(wù)方提供一個(gè)統(tǒng)一的 HTTP 入口兼容 OpenAI 風(fēng)格的請(qǐng)求格式這樣業(yè)務(wù)方幾乎不需要修改代碼就能接入。核心網(wǎng)關(guān)層包含路由分發(fā)、協(xié)議適配、鑒權(quán)認(rèn)證、限流熔斷、計(jì)量計(jì)費(fèi)、審計(jì)日志等六大部分。這里就是整個(gè)系統(tǒng)的“大腦”和“調(diào)度中心”。存儲(chǔ)層MySQL 存放用戶、API Key、模型配置、調(diào)用日志等結(jié)構(gòu)化數(shù)據(jù)Redis 存放限流計(jì)數(shù)器、令牌桶、分布式鎖等實(shí)時(shí)性要求高的數(shù)據(jù)?？刂婆_(tái)層Vue3 管理頁面用于配置模型供應(yīng)商、管理 API Key、查看調(diào)用監(jiān)控、導(dǎo)出賬單報(bào)表。這個(gè)分層借鑒了 API 網(wǎng)關(guān)的經(jīng)典架構(gòu)但又針對(duì)大模型場(chǎng)景做了專門的優(yōu)化協(xié)議適配層是核心因?yàn)榇竽Ｐ蛷S商的協(xié)議實(shí)在太不統(tǒng)一了。2.2 核心模塊劃分與職責(zé)我畫模塊圖的時(shí)候把整個(gè)系統(tǒng)拆成了下面這些模塊每個(gè)模塊的職責(zé)邊界都比較清晰模塊核心職責(zé)關(guān)鍵技術(shù)點(diǎn)路由分發(fā)根據(jù)請(qǐng)求參數(shù)決定轉(zhuǎn)發(fā)到哪家廠商模型名到供應(yīng)商映射、加權(quán)輪詢協(xié)議適配各家廠商請(qǐng)求/響應(yīng)格式統(tǒng)一轉(zhuǎn)換適配器模式、SSE 流解析密鑰管理存儲(chǔ)和注入上游廠商 API KeyAES 加密 每次請(qǐng)求動(dòng)態(tài)注入鑒權(quán)認(rèn)證識(shí)別調(diào)用方身份、校驗(yàn)權(quán)限API Key 前綴模式 哈希校驗(yàn)限流熔斷保護(hù)上游資源和下游穩(wěn)定性Redis 令牌桶、滑動(dòng)窗口熔斷計(jì)量計(jì)費(fèi)記錄 token 用量、費(fèi)用分?jǐn)倀oken 校驗(yàn)與用量解析審計(jì)日志全鏈路調(diào)用留痕異步落庫、日志采樣系統(tǒng)管理用戶管理、供應(yīng)商管理、模型配置RBAC 權(quán)限模型2.3 技術(shù)選型的取舍我選型的時(shí)候有兩個(gè)核心考量一是生態(tài)成熟度二是團(tuán)隊(duì)后續(xù)維護(hù)成本。后端選了 Java Spring Boot 3因?yàn)槲业纳a(chǎn)環(huán)境里已經(jīng)有很多 Spring 基礎(chǔ)設(shè)施運(yùn)維工具鏈都是現(xiàn)成的。網(wǎng)關(guān)核心沒有引入 Spring Cloud Gateway而是自己封裝了一層基于 Servlet 的轉(zhuǎn)發(fā)邏輯原因是我們的場(chǎng)景沒有那么龐大的服務(wù)發(fā)現(xiàn)需求大模型 API 的轉(zhuǎn)發(fā)本質(zhì)上是 HTTP 調(diào)用不需要走 Service Mesh 那套。存儲(chǔ)方面MySQL 存元數(shù)據(jù)和調(diào)用流水Redis 做實(shí)時(shí)計(jì)數(shù)和分布式限流。因?yàn)橐獙?duì)上游 key 做細(xì)粒度的緩存和防抖Redis 是剛需。前端控制臺(tái)選了 Vue3 Element Plus這是目前國內(nèi)使用率最高的中后臺(tái)技術(shù)組合接手門檻低。3. 核心實(shí)現(xiàn)協(xié)議適配層如何做到“一次接入隨處調(diào)用”協(xié)議適配是整個(gè)系統(tǒng)里技術(shù)含量最高的部分。不同大模型廠商的 API 差異很大我一開始接到一個(gè)需求“是不是只要把請(qǐng)求轉(zhuǎn)發(fā)出去就行了”實(shí)際做起來才發(fā)現(xiàn)完全不是這么回事。3.1 統(tǒng)一 API 協(xié)議設(shè)計(jì)我定義了一套內(nèi)部的“標(biāo)準(zhǔn)協(xié)議”所有請(qǐng)求進(jìn)入網(wǎng)關(guān)后先轉(zhuǎn)換成這個(gè)標(biāo)準(zhǔn)格式再交給適配器去轉(zhuǎn)換成各家廠商的格式。核心請(qǐng)求模型長這樣public class UnifiedChatRequest { private String requestId; // 全局唯一請(qǐng)求ID private String provider; // 指定供應(yīng)商可選 private String model; // 模型名如 gpt-4o-mini / deepseek-chat private ListChatMessage messages; // 對(duì)話消息列表 private Double temperature; // 采樣溫度 private Integer maxTokens; // 最大輸出 token 數(shù) private Boolean stream; // 是否流式返回 private MapString, Object extraParams; // 各家特有參數(shù)透?jìng)?} public class ChatMessage { private String role; // system / user / assistant private String content; private String name; // 可選多輪對(duì)話時(shí)使用 }選擇這個(gè)模型有兩個(gè)關(guān)鍵考量第一它完全兼容 OpenAI 的請(qǐng)求格式這樣從 OpenAI 切換過來的業(yè)務(wù)方基本零成本第二message 結(jié)構(gòu)上留了name字段和extraParams可以承接各家特有參數(shù)。3.2 適配器模式的具體實(shí)現(xiàn)我用適配器模式把“標(biāo)準(zhǔn)協(xié)議”轉(zhuǎn)換成各家協(xié)議。核心是一個(gè)接口public interface LLMProviderAdapter { String getProviderName(); UnifiedChatResponse chat(UnifiedChatRequest request); void chatStream(UnifiedChatRequest request, StreamCallbackUnifiedChatResponse callback); }每個(gè)廠商實(shí)現(xiàn)一個(gè) Adapter 類例如OpenAIAdapter、DeepSeekAdapter、QwenAdapter、ClaudeAdapter。路由分發(fā)的時(shí)候根據(jù)請(qǐng)求里的模型名或指定的 provider從 Spring 容器里取出對(duì)應(yīng)的 Bean 執(zhí)行。這里最關(guān)鍵的一個(gè)設(shè)計(jì)細(xì)節(jié)是模型名到適配器的映射關(guān)系是數(shù)據(jù)驅(qū)動(dòng)的存在 MySQL 表里而不是寫死在代碼里。這樣運(yùn)營人員可以在控制臺(tái)上配置一個(gè)新的模型名deepseek-chat映射到 DeepSeek 供應(yīng)商不需要改一行代碼。數(shù)據(jù)庫表設(shè)計(jì)如下CREATE TABLE llm_model_registry ( id bigint(20) NOT NULL AUTO_INCREMENT, model_name varchar(128) NOT NULL COMMENT 業(yè)務(wù)可見的模型名, provider_code varchar(64) NOT NULL COMMENT 供應(yīng)商編碼, upstream_model_name varchar(128) NOT NULL COMMENT 上游真實(shí)模型名, status tinyint(4) NOT NULL DEFAULT 1 COMMENT 0-停用 1-啟用, remark varchar(512) DEFAULT NULL, PRIMARY KEY (id), UNIQUE KEY uk_model_name (model_name) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;這樣設(shè)計(jì)的好處是當(dāng)上游廠商把gpt-4o換成了gpt-4o-mini只需要在配置中心后臺(tái)把upstream_model_name改掉業(yè)務(wù)方完全無感知。3.3 流式響應(yīng)的處理細(xì)節(jié)流式接口是整個(gè)協(xié)議適配里最容易出 bug 的地方。OpenAI 的 SSE 流返回格式跟 Claude 的流返回格式完全不一樣而且還有一個(gè)大坑業(yè)務(wù)方連接斷開時(shí)網(wǎng)關(guān)必須能感知到并立即終止上游請(qǐng)求否則 token 費(fèi)用會(huì)一直累計(jì)下去。我的實(shí)現(xiàn)方案是在轉(zhuǎn)發(fā)層使用 OkHttp 的異步流式調(diào)用把上游的 SSE 字節(jié)流實(shí)時(shí)轉(zhuǎn)發(fā)給下游。核心是一個(gè) ResponseBodyCallbackprivate void forwardStream(okhttp3.Response upstreamResponse, HttpServletResponse downstreamResponse) throws IOException { downstreamResponse.setContentType(text/event-stream); downstreamResponse.setCharacterEncoding(UTF-8); downstreamResponse.setHeader(Cache-Control, no-cache); try (BufferedReader reader new BufferedReader( new InputStreamReader(upstreamResponse.body().byteStream(), StandardCharsets.UTF_8))) { String line; while ((line reader.readLine()) ! null) { if (downstreamResponse.getWriter().checkError()) { // 下游連接已斷開立即終止 upstreamResponse.close(); break; } downstreamResponse.getWriter().write(line \n); downstreamResponse.getWriter().flush(); } } }這里有一個(gè)細(xì)節(jié)每一次 write 之后必須 flush否則下游客戶端會(huì)一直等不到數(shù)據(jù)。而且用checkError()判斷下游是否已經(jīng)斷開是一個(gè)性價(jià)比很高的做法比監(jiān)聽回調(diào)里的異常要可靠得多。4. 核心實(shí)現(xiàn)密鑰管理、限流熔斷與計(jì)量計(jì)費(fèi)4.1 密鑰安全存儲(chǔ)與隔離密鑰管理是整個(gè)系統(tǒng)的安全基石。上游廠商的 Key 如果明文存在數(shù)據(jù)庫里一旦數(shù)據(jù)庫泄露就是重大事故。我的方案是AES-GCM 加密后存儲(chǔ)密鑰從環(huán)境變量注入且應(yīng)用配置文件里絕不出現(xiàn)明文 Key。Component public class SecretCipher { private static final String TRANSFORMATION AES/GCM/NoPadding; private final SecretKey secretKey; public SecretCipher(Value(${cipher.secret-key}) String base64Key) { byte[] keyBytes Base64.getDecoder().decode(base64Key); this.secretKey new SecretKeySpec(keyBytes, AES); } public String encrypt(String plainText) { try { Cipher cipher Cipher.getInstance(TRANSFORMATION); byte[] iv new byte[12]; SecureRandom random new SecureRandom(); random.nextBytes(iv); cipher.init(Cipher.ENCRYPT_MODE, secretKey, new GCMParameterSpec(128, iv)); byte[] encrypted cipher.doFinal(plainText.getBytes(StandardCharsets.UTF_8)); // 把 iv 和密文拼接存儲(chǔ) ByteBuffer buffer ByteBuffer.allocate(iv.length encrypted.length); buffer.put(iv); buffer.put(encrypted); return Base64.getEncoder().encodeToString(buffer.array()); } catch (Exception e) { throw new RuntimeException(密鑰加密失敗, e); } } }網(wǎng)關(guān)發(fā)起上游調(diào)用時(shí)從數(shù)據(jù)庫取出密文解密后再放入請(qǐng)求頭。這里有一個(gè)性能優(yōu)化點(diǎn)對(duì)解密結(jié)果做 10 分鐘的本地緩存避免每一個(gè)請(qǐng)求都走一次 AES 解密因?yàn)榻饷鼙旧磉€是有 CPU 開銷的。密鑰隔離也有講究。我給每個(gè)上游供應(yīng)商單獨(dú)建一張密鑰表每個(gè)供應(yīng)商可以配置多個(gè) Key網(wǎng)關(guān)發(fā)起請(qǐng)求時(shí)可以輪詢使用。當(dāng)一個(gè) Key 因?yàn)橛囝~不足或限流返回 401/429 時(shí)自動(dòng)標(biāo)記異常并切換到下一個(gè) Key。4.2 限流策略與實(shí)現(xiàn)大模型 API 比普通 HTTP API 更需要限流因?yàn)橐坏┠硞€(gè)業(yè)務(wù)方代碼出現(xiàn)死循環(huán)每分鐘可能消耗上千元 token 費(fèi)用。我的限流方案是雙層限流第一層按 API Key 維度每個(gè)調(diào)用方每分鐘最多 N 次請(qǐng)求第二層按模型維度每個(gè)上游模型全局每分鐘最多 M 次請(qǐng)求實(shí)現(xiàn)用的 Redis 令牌桶。之所以用令牌桶而不是固定窗口是因?yàn)樗梢栽试S一定程度的突發(fā)流量更貼近實(shí)際業(yè)務(wù)場(chǎng)景。Component public class RedisRateLimiter { Autowired private StringRedisTemplate redisTemplate; private static final String TOKEN_KEY_PREFIX rate:token:; private static final String TIME_KEY_PREFIX rate:time:; public boolean tryAcquire(String key, int capacity, int refillRate) { long now System.currentTimeMillis(); String tokenKey TOKEN_KEY_PREFIX key; String timeKey TIME_KEY_PREFIX key; // Lua 腳本保證原子性 String luaScript local token_key KEYS[1] local time_key KEYS[2] local now tonumber(ARGV[1]) local capacity tonumber(ARGV[2]) local refill_rate tonumber(ARGV[3]) local refill_interval tonumber(ARGV[4]) local current_tokens tonumber(redis.call(get, token_key) or capacity) local last_refill tonumber(redis.call(get, time_key) or now) local elapsed now - last_refill local refill_count math.floor(elapsed / refill_interval) if refill_count 0 then current_tokens math.min(capacity, current_tokens refill_count * refill_rate) redis.call(set, time_key, now) end if current_tokens 0 then redis.call(set, token_key, current_tokens - 1) return 1 else return 0 end ; Long result redisTemplate.execute( new DefaultRedisScript(luaScript, Long.class), Arrays.asList(tokenKey, timeKey), String.valueOf(now), String.valueOf(capacity), String.valueOf(refillRate), String.valueOf(1000) // 每秒補(bǔ)充一次 ); return Long.valueOf(1).equals(result); } }這個(gè) Lua 腳本的妙處在于令牌補(bǔ)充邏輯和扣減邏輯在 Redis 端原子執(zhí)行不會(huì)出現(xiàn)并發(fā)情況下多扣或少補(bǔ)的問題。4.3 熔斷與重試策略上游大模型 API 有時(shí)候會(huì)突然不穩(wěn)定返回 5xx 或響應(yīng)超時(shí)。如果網(wǎng)關(guān)不做熔斷保護(hù)所有請(qǐng)求都堆積在慢調(diào)用上很快整個(gè)系統(tǒng)都會(huì)被拖死。我的熔斷器實(shí)現(xiàn)借鑒了 Hystrix 的三態(tài)模型關(guān)閉、打開、半開。public enum CircuitState { CLOSED, // 正常狀態(tài)放行所有請(qǐng)求 OPEN, // 熔斷狀態(tài)直接拒絕請(qǐng)求 HALF_OPEN // 半開狀態(tài)放行少量探測(cè)請(qǐng)求 }狀態(tài)轉(zhuǎn)換規(guī)則默認(rèn) CLOSED狀態(tài)滑動(dòng)窗口統(tǒng)計(jì)最近 60 秒內(nèi)的失敗率失敗率超過閾值比如 50%且請(qǐng)求量超過最小請(qǐng)求數(shù)比如 20 次狀態(tài)切換為 OPENOPEN 狀態(tài)持續(xù) 30 秒期間所有請(qǐng)求快速失敗直接返回 50330 秒后進(jìn)入 HALF_OPEN放行 5 個(gè)探測(cè)請(qǐng)求全部成功則恢復(fù) CLOSED否則回到 OPEN熔斷器是每個(gè)上游供應(yīng)商維度的代碼里用ConcurrentHashMapString, CircuitBreaker保存避免一個(gè)模型故障拖累所有模型。重試策略我也做了很嚴(yán)格的約束只能對(duì)冪等請(qǐng)求重試且最多重試 1 次。對(duì)于流式請(qǐng)求如果已經(jīng)向下游客戶端輸出了部分?jǐn)?shù)據(jù)絕不能重試否則會(huì)產(chǎn)生內(nèi)容錯(cuò)亂。4.4 計(jì)量計(jì)費(fèi)的設(shè)計(jì)與實(shí)現(xiàn)計(jì)量計(jì)費(fèi)開始時(shí)我本來想放在一個(gè)獨(dú)立的日志消費(fèi)模塊里后來為了簡(jiǎn)化部署直接用了異步寫庫 定時(shí)匯總的方案。上游的響應(yīng)里都會(huì)帶 usage 字段里面包含prompt_tokens、completion_tokens、total_tokens三個(gè)值。網(wǎng)關(guān)把這個(gè)原始 JSON 透?jìng)鹘o業(yè)務(wù)方的同時(shí)也同步解析并記錄到數(shù)據(jù)庫public class UsageRecord { private Long id; private String requestId; private String apiKeyId; // 哪個(gè)調(diào)用方 private String providerCode; // 哪個(gè)供應(yīng)商 private String modelName; // 哪個(gè)模型 private Long promptTokens; private Long completionTokens; private Long totalTokens; private BigDecimal cost; // 計(jì)算出的費(fèi)用 private LocalDateTime createTime; }費(fèi)用計(jì)算是基于供應(yīng)商配置的單價(jià)表。我建了一張provider_price表字段包括input_price_per_million、output_price_per_million單位為元/百萬 token。計(jì)費(fèi)時(shí)BigDecimal cost inputPrice.multiply(BigDecimal.valueOf(promptTokens)) .divide(BigDecimal.valueOf(1_000_000), 6, RoundingMode.HALF_UP) .add(outputPrice.multiply(BigDecimal.valueOf(completionTokens)) .divide(BigDecimal.valueOf(1_000_000), 6, RoundingMode.HALF_UP));這個(gè)方法雖然沒有官方計(jì)價(jià)那么精確各家有時(shí)按緩存命中與否區(qū)分價(jià)格但對(duì)于按業(yè)務(wù)線做成本分?jǐn)偼耆珘蛴谩?. 控制臺(tái)與可視化讓 API 調(diào)用狀態(tài)可觀測(cè)一個(gè)管理系統(tǒng)的價(jià)值很大程度上取決于控制臺(tái)做得是否好用。我沒有把精力花在花哨的圖表上而是優(yōu)先保證“調(diào)用方能快速定位問題”。5.1 管理臺(tái)功能設(shè)計(jì)控制臺(tái)的核心頁面有五個(gè)每個(gè)頁面解決一類問題儀表盤展示今日總調(diào)用量、總 token 消耗、預(yù)估費(fèi)用、成功率、P95 響應(yīng)延遲。這些數(shù)據(jù)每 5 秒刷新一次方便運(yùn)維盯大屏。調(diào)用日志按時(shí)間、調(diào)用方、模型、狀態(tài)碼篩選點(diǎn)開詳情能看到完整的請(qǐng)求參數(shù)和響應(yīng)內(nèi)容支持一鍵復(fù)制 curl 命令復(fù)現(xiàn)問題。密鑰管理創(chuàng)建/禁用/輪換業(yè)務(wù)方的 API Key支持設(shè)置 key 的預(yù)算上限和日調(diào)用次數(shù)上限。模型管理維護(hù)供應(yīng)商、模型注冊(cè)表、單價(jià)表配置模型開關(guān)。用量報(bào)表按天/按周/按月匯總每個(gè)調(diào)用方的費(fèi)用和 token 消耗支持導(dǎo)出 Excel。5.2 數(shù)據(jù)看板的實(shí)現(xiàn)細(xì)節(jié)儀表盤的后端接口我用了兩個(gè)手段保證性能調(diào)用日志和用量數(shù)據(jù)都做了預(yù)聚合每 5 分鐘把明細(xì)記錄匯總成一條call_stats_hourly記錄大屏查詢只查聚合表不直接掃明細(xì)表。儀表盤的接口都加了 Redis 緩存緩存時(shí)間 5 秒。對(duì)于大屏場(chǎng)景響應(yīng)速度比實(shí)時(shí)性更重要。GetMapping(/api/dashboard/overview) public ResultDashboardOverviewVO overview() { String cacheKey dashboard:overview; DashboardOverviewVO vo redisTemplate.opsForValue().get(cacheKey); if (vo null) { vo buildOverview(); redisTemplate.opsForValue().set(cacheKey, vo, 5, TimeUnit.SECONDS); } return Result.success(vo); }另外一個(gè)比較重要的監(jiān)控是上游供應(yīng)商健康狀態(tài)。我在系統(tǒng)里做了一套定時(shí)探測(cè)機(jī)制每 30 秒向各供應(yīng)商發(fā)一個(gè)最小化的 chat 請(qǐng)求只請(qǐng)求 1 個(gè) token如果連續(xù)失敗 3 次就在控制臺(tái)標(biāo)紅并發(fā)告警通知到群。6. 部署實(shí)踐與踩坑記錄系統(tǒng)開發(fā)完成之后部署到測(cè)試環(huán)境、壓測(cè)、上生產(chǎn)這個(gè)過程中又踩了不少坑。我把一些非常有價(jià)值的經(jīng)驗(yàn)整理出來。6.1 Docker Compose 一鍵部署項(xiàng)目的交付物里包含一套完整的docker-compose.yml啟動(dòng)之后就是一套可用的環(huán)境version: 3.8 services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: root123456 MYSQL_DATABASE: llm_gateway volumes: - ./sql/init.sql:/docker-entrypoint-initdb.d/init.sql - mysql-data:/var/lib/mysql ports: - 3306:3306 redis: image: redis:7.0-alpine ports: - 6379:6379 volumes: - redis-data:/data backend: build: ./backend environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/llm_gateway?useUnicodetruecharacterEncodingutf8 SPRING_DATA_REDIS_HOST: redis CIPHER_SECRET_KEY: dGhpcy1pcy1hLXNlY3JldC1rZXktZm9yLWRlbW8 depends_on: - mysql - redis ports: - 8080:8080 frontend: build: ./frontend depends_on: - backend ports: - 80:80 volumes: mysql-data: redis-data:注意CIPHER_SECRET_KEY這個(gè)環(huán)境變量生產(chǎn)環(huán)境一定要用專門的密鑰管理服務(wù)如 Vault來管理不能像 demo 環(huán)境這樣硬編碼。6.2 部署中遇到的經(jīng)典問題問題一SSE 流式響應(yīng)被 Nginx 緩沖前端調(diào)用流式接口時(shí)頁面一直等不到數(shù)據(jù)幾十秒后才一次性吐出全部?jī)?nèi)容。排查后發(fā)現(xiàn)是 Nginx 默認(rèn)開啟了 proxy_buffering把 SSE 流緩沖了。解決方法是在 Nginx 配置中關(guān)閉緩沖location /v1/ { proxy_pass http://backend:8080; proxy_buffering off; proxy_cache off; proxy_set_header Connection ; proxy_http_version 1.1; chunked_transfer_encoding on; proxy_read_timeout 300s; }問題二調(diào)用上游時(shí)連接池耗盡壓測(cè)時(shí)發(fā)現(xiàn) QPS 一高很多請(qǐng)求卡在獲取連接上。原因是我直接用了 RestTemplate 默認(rèn)連接池最大連接數(shù)只有 200。換成 OkHttp 連接池并調(diào)大配置后問題解決Bean public OkHttpClient okHttpClient() { Dispatcher dispatcher new Dispatcher(); dispatcher.setMaxRequests(500); dispatcher.setMaxRequestsPerHost(200); ConnectionPool pool new ConnectionPool(50, 30, TimeUnit.SECONDS); return new OkHttpClient.Builder() .dispatcher(dispatcher) .connectionPool(pool) .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(120, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .build(); }這個(gè) readTimeout 一定要設(shè)置得足夠大因?yàn)榇竽Ｐ土魇巾憫?yīng)可能會(huì)持續(xù)幾十秒甚至幾分鐘。問題三上游返回connection lost mid-response類錯(cuò)誤我們調(diào)一些不穩(wěn)定的上游接口時(shí)會(huì)出現(xiàn)響應(yīng)已經(jīng)發(fā)了一半突然斷連的情況。這個(gè)問題的根因往往是上游的負(fù)載均衡超時(shí)配置太短或者上游在處理長請(qǐng)求時(shí)主動(dòng)斷開了連接。我在適配器層做了針對(duì)性的處理如果響應(yīng)頭已經(jīng)寫入但還沒有完成捕獲 IOException 后記錄一條特殊的“半包日志”方便追查是哪家供應(yīng)商在哪一段網(wǎng)絡(luò)鏈路出的問題。6.3 壓測(cè)數(shù)據(jù)與性能調(diào)優(yōu)我拿了 4C8G 的單機(jī)部署做壓測(cè)開啟 200 并發(fā)壓了 30 分鐘結(jié)果如下指標(biāo)數(shù)值峰值 QPS2100平均響應(yīng)時(shí)間38msP99 響應(yīng)時(shí)間92ms錯(cuò)誤率0.02%CPU 平均值45%這個(gè)性能對(duì)于大部分中小型團(tuán)隊(duì)已經(jīng)完全夠用。性能瓶頸主要在于上游 API 的網(wǎng)絡(luò)延遲網(wǎng)關(guān)自身轉(zhuǎn)發(fā)的開銷占比很小。7. 從源碼到畢業(yè)論文的整理思路這套系統(tǒng)如果是用來做畢業(yè)設(shè)計(jì)的源碼和論文的配套整理很關(guān)鍵。我建議論文按照“需求分析、系統(tǒng)設(shè)計(jì)、系統(tǒng)實(shí)現(xiàn)、系統(tǒng)測(cè)試”這四個(gè)大塊組織跟源碼模塊一一對(duì)應(yīng)評(píng)審老師讀起來會(huì)很順。7.1 論文整體架構(gòu)建議我整理了論文技術(shù)部分的參考結(jié)構(gòu)第一章 緒論寫研究背景、國內(nèi)外 API 網(wǎng)關(guān)和大模型應(yīng)用的現(xiàn)狀點(diǎn)出當(dāng)前大模型 API 管理缺乏統(tǒng)一方案的痛點(diǎn)第二章 相關(guān)技術(shù)介紹介紹 LLM 基礎(chǔ)概念、Spring Boot、Redis、Vue.js、適配器模式、令牌桶算法等讓評(píng)委確認(rèn)你技術(shù)選型有依據(jù)第三章 系統(tǒng)需求分析把功能性需求協(xié)議轉(zhuǎn)換、密鑰管理、計(jì)量計(jì)費(fèi)、監(jiān)控告警和非功能性需求性能、安全性、可用性分開描述第四章 系統(tǒng)設(shè)計(jì)給出架構(gòu)圖、功能模塊圖、數(shù)據(jù)庫 ER 圖、關(guān)鍵接口設(shè)計(jì)并用文字說明每個(gè)模塊為什么這么設(shè)計(jì)第五章 系統(tǒng)實(shí)現(xiàn)按模塊逐個(gè)展示關(guān)鍵代碼片段配合截圖展示實(shí)際運(yùn)行效果第六章 系統(tǒng)測(cè)試包含功能測(cè)試用例設(shè)計(jì)、性能壓測(cè)報(bào)告、結(jié)果分析7.2 從代碼中提煉論文素材的技巧很多同學(xué)寫完代碼寫論文的時(shí)候反而沒素材。我的做法是每實(shí)現(xiàn)完一個(gè)功能模塊就順手寫一篇開發(fā)筆記記錄這個(gè)模塊解決了什么問題、核心設(shè)計(jì)思想是什么、用了什么設(shè)計(jì)模式、測(cè)試數(shù)據(jù)如何。這樣論文里的每一個(gè)實(shí)現(xiàn)章節(jié)都有真實(shí)內(nèi)容和數(shù)據(jù)支撐而不是靠拼湊。比如協(xié)議適配這一章我就寫了“為什么要用適配器模式而不是 if-else 判斷”這個(gè)在論文答辯時(shí)也是很好的加分亮點(diǎn)。8. 系統(tǒng)測(cè)試與穩(wěn)定性驗(yàn)證測(cè)試階段我不僅寫了單元測(cè)試還寫了集成測(cè)試和端到端聯(lián)調(diào)用例。這里說幾個(gè)比較重要的測(cè)試方案。單元測(cè)試主要是對(duì)限流器、熔斷器、加密工具類進(jìn)行測(cè)試。熔斷器狀態(tài)流轉(zhuǎn)的測(cè)試用例非常重要因?yàn)闋顟B(tài)機(jī)邏輯很容易在邊界情況出錯(cuò)Test void testCircuitBreakerOpenAndHalfOpen() { CircuitBreaker cb new CircuitBreaker(20, 0.5, 30000); // 模擬 20 個(gè)請(qǐng)求中 15 個(gè)失敗 for (int i 0; i 20; i) { boolean success i 5; cb.recordResult(success); } assertTrue(cb.isOpen()); // 等待 30 秒進(jìn)入半開狀態(tài) Thread.sleep(30000); assertTrue(cb.isHalfOpen()); // 連續(xù) 5 個(gè)探測(cè)請(qǐng)求成功熔斷器關(guān)閉 for (int i 0; i 5; i) { cb.recordResult(true); } assertFalse(cb.isOpen()); }集成測(cè)試則是用 Testcontainers 起一個(gè)真實(shí)的 MySQL 和 Redis 容器驗(yàn)證整個(gè)請(qǐng)求鏈路是否通。這種方式比 Mock 更加真實(shí)能抓出很多環(huán)境依賴的坑。端到端聯(lián)調(diào)時(shí)我在測(cè)試環(huán)境配了 3 家真實(shí)的大模型供應(yīng)商把每個(gè)供應(yīng)商的流式和非流式調(diào)用都跑了一遍。這個(gè)環(huán)節(jié)讓我發(fā)現(xiàn)了很多只在真實(shí)網(wǎng)絡(luò)環(huán)境下才會(huì)出現(xiàn)的問題比如某些供應(yīng)商對(duì)stream_options參數(shù)的支持差異、不同供應(yīng)商的 timeout 行為等。這套測(cè)試流程完整走下來系統(tǒng)的穩(wěn)定性已經(jīng)比較有保障。9. 改進(jìn)方向與后續(xù)計(jì)劃目前這套系統(tǒng)已經(jīng)在我這邊穩(wěn)定運(yùn)行了一段時(shí)間但離想象中的“完美”還有不少距離。我心里有幾個(gè)后續(xù)改進(jìn)的方向也分享給大家參考。一是引入語義緩存。對(duì)于相同或相似的請(qǐng)求可以復(fù)用之前的響應(yīng)這個(gè)在典型的多輪客服場(chǎng)景里能省不少 token 費(fèi)用。難點(diǎn)是緩存鍵的設(shè)計(jì)和相似度計(jì)算需要權(quán)衡命中率和內(nèi)存消耗。二是增加A/B 測(cè)試和灰度發(fā)布capability。當(dāng)上游廠商發(fā)布新模型時(shí)先讓 5% 的流量走新模型觀察效果后再全量切換。這樣能在網(wǎng)關(guān)層實(shí)現(xiàn)模型迭代的平滑升級(jí)。三是引入動(dòng)態(tài)路由策略。目前是根據(jù)模型名做靜態(tài)路由未來可以做成基于價(jià)格、延遲、可用性的動(dòng)態(tài)評(píng)分路由比如某廠商 API 延遲飆升時(shí)自動(dòng)把流量切到其他廠商。四是完善多租戶配額管理。給每個(gè)業(yè)務(wù)方設(shè)置獨(dú)立的預(yù)算上限當(dāng)消費(fèi)金額超過閾值時(shí)自動(dòng)告警甚至熔斷防止預(yù)算超支。這些都還是設(shè)計(jì)思考階段但方向已經(jīng)比較明確。如果你也在做類似項(xiàng)目歡迎一起交流可以互相參考少走一些彎路。本文還有配套的精品資源點(diǎn)擊獲取