一LLM網(wǎng)關(guān)：一個(gè)Key接入所有免費(fèi)模型)
先說(shuō)一個(gè)挺常見(jiàn)的場(chǎng)景你同時(shí)想用多個(gè)平臺(tái)的免費(fèi)模型做應(yīng)用于是注冊(cè)賬號(hào)、申請(qǐng) API Key、看文檔、配 SDK、寫代理代碼……一個(gè)接一個(gè)折騰下來(lái)代碼里躺著十幾把 Key每把 Key 對(duì)應(yīng)的請(qǐng)求地址還不一樣。更難受的是等模型版本更新或者某個(gè)平臺(tái)臨時(shí)調(diào)整模型名你還要逐個(gè)修改調(diào)用代碼。這篇文章要解決的就是“免費(fèi)模型很多、Key 也一堆”的碎片化問(wèn)題。我會(huì)從統(tǒng)一 API 網(wǎng)關(guān)的原理講起用 FastAPI 寫一個(gè)最小可用的網(wǎng)關(guān)把多個(gè)免費(fèi)模型服務(wù)統(tǒng)一到一個(gè) Key 后面再給出 OpenAI SDK、LangChain、ChatBox 等常見(jiàn)客戶端的接入方法最后整理一份高頻報(bào)錯(cuò)排查清單。整套代碼都是直白可復(fù)制的適合學(xué)生、個(gè)人開(kāi)發(fā)者和正在做 AI 應(yīng)用原型的團(tuán)隊(duì)參考。1. 為什么需要“一個(gè) Key 接入所有免費(fèi)模型”先解釋標(biāo)題里的“Free LLM API”。它并不是指某一個(gè)具體的模型而是指一種能力通過(guò)一個(gè)統(tǒng)一的 API 入口訪問(wèn)多個(gè)提供免費(fèi)額度或免費(fèi)檔模型的服務(wù)商。目前各家大模型服務(wù)商幾乎都會(huì)提供 OpenAI 兼容接口但它們各自有獨(dú)立的 Base URL、獨(dú)立的鑒權(quán)方式、獨(dú)立的免費(fèi)額度和模型列表。你在項(xiàng)目里每接入一家就要管理一整套配置想換一個(gè)模型又得重新適配一次。統(tǒng)一網(wǎng)關(guān)解決的就是這個(gè)多對(duì)多問(wèn)題。從工程角度看它至少帶來(lái)四個(gè)明確收益。第一接入成本下降?？蛻舳酥恍枰獙?shí)現(xiàn)一套 OpenAI 兼容調(diào)用以后新增模型只是在網(wǎng)管配置里加一行模型名和對(duì)應(yīng)服務(wù)商業(yè)務(wù)代碼完全不用改。第二Key 不再混亂。無(wú)論客戶端跑在本地、測(cè)試服務(wù)器還是 CI 環(huán)境都只需要配置同一個(gè)網(wǎng)關(guān)主 Key省去多個(gè)環(huán)境維護(hù)多套密鑰的煩惱。第三可以做統(tǒng)一容災(zāi)。免費(fèi)模型經(jīng)常遇到“暫時(shí)繁忙”或服務(wù)不穩(wěn)定網(wǎng)關(guān)可以把請(qǐng)求切換到備用模型避免用戶直接看到報(bào)錯(cuò)。第四方便做統(tǒng)一監(jiān)控。不管底層調(diào)用了幾家服務(wù)商日志、請(qǐng)求量、token 消耗都能匯總到同一個(gè)服務(wù)里統(tǒng)計(jì)。市面上確實(shí)有不少“聚合全部免費(fèi)模型”的第三方服務(wù)但與其完全依賴第三方聚合服務(wù)不如先掌握實(shí)現(xiàn)原理再?zèng)Q定是否需要使用現(xiàn)成網(wǎng)關(guān)。自己搭一個(gè)輕量網(wǎng)關(guān)模型列表、密鑰、日志都完全可控后面接新模型也只是改配置的事。2. 統(tǒng)一 LLM API 網(wǎng)關(guān)的核心原理嚴(yán)格來(lái)說(shuō)模型聚合并不需要寫一堆復(fù)雜的 AI 代碼它的本質(zhì)是一個(gè) HTTP 服務(wù)負(fù)責(zé)“把客戶端的請(qǐng)求轉(zhuǎn)給合適的模型服務(wù)商再把結(jié)果轉(zhuǎn)回來(lái)”。要做到一個(gè) Key 管所有模型需要拆成三個(gè)層次來(lái)看。2.1 統(tǒng)一鑒權(quán)層第一層是鑒權(quán)。網(wǎng)關(guān)對(duì)外只暴露一個(gè)主 KeyMaster Key所有客戶端請(qǐng)求都帶這個(gè) Key網(wǎng)關(guān)校驗(yàn)通過(guò)后再用自己的服務(wù)商密鑰去調(diào)用上游。這里的關(guān)鍵點(diǎn)是主 Key 和上游密鑰完全隔離?？蛻舳擞肋h(yuǎn)不應(yīng)該看到 DeepSeek、OpenRouter 或者其他服務(wù)商的實(shí)際密鑰否則就等于把這把鑰匙交出去了。在 FastAPI 里實(shí)現(xiàn)這個(gè)層非常簡(jiǎn)單只需要寫一個(gè)依賴函數(shù)讀請(qǐng)求頭Authorization里的 Bearer Token和配置里的master_key對(duì)比。如果校驗(yàn)失敗直接返回 401。框架代碼后面會(huì)給出。2.2 模型路由與別名映射第二層是路由?？蛻舳藗鬟^(guò)來(lái)的model字段決定請(qǐng)求最終發(fā)給哪家服務(wù)商。最樸素的做法是“模型名映射”網(wǎng)關(guān)維護(hù)一張表每個(gè)模型名對(duì)應(yīng)一個(gè) provider 和它自己的上游模型名。比如內(nèi)部配置了deepseek-chat就轉(zhuǎn)發(fā)到 DeepSeek配置了llama-3.3-70b-instruct:free就轉(zhuǎn)發(fā)到 OpenRouter。這里有一個(gè)容易踩坑的點(diǎn)不同服務(wù)商可能存在同名模型或者同一個(gè)模型在各家的名字不一樣。為了避免路由錯(cuò)亂網(wǎng)關(guān)里的模型名必須全局唯一。如果出現(xiàn)重名建議加前綴命名比如deepseek/deepseek-chat、openrouter/deepseek-chat這樣。但在大多數(shù)個(gè)人場(chǎng)景里直接用模型名作為全局 Key 已經(jīng)足夠了不必過(guò)度設(shè)計(jì)。2.3 協(xié)議兼容層OpenAI 兼容格式第三層是協(xié)議。為什么客戶端只需要寫一套代碼就能調(diào)用所有模型因?yàn)榻^大多數(shù) LLM API 服務(wù)商都提供了 OpenAI 兼容的 HTTP 接口即請(qǐng)求路徑通常是POST /v1/chat/completions請(qǐng)求體包含model、messages、temperature等字段鑒權(quán)通常是Authorization: Bearer key返回結(jié)構(gòu)也是統(tǒng)一的choicesusage格式。網(wǎng)關(guān)要做的事情就是把自己收到的請(qǐng)求盡量原樣轉(zhuǎn)發(fā)給上游。它本身不負(fù)責(zé)理解聊天內(nèi)容只負(fù)責(zé)協(xié)議搬運(yùn)和模型路由。這也是為什么網(wǎng)關(guān)代碼可以做到很短以后回過(guò)來(lái)維護(hù)也不會(huì)覺(jué)得吃力。只要協(xié)議兼容網(wǎng)關(guān)就很容易替換、增加或下線某個(gè)模型服務(wù)。3. 環(huán)境準(zhǔn)備與項(xiàng)目結(jié)構(gòu)寫代碼之前先把環(huán)境準(zhǔn)備好。本文的示例以 Python 3.10 為例使用的核心依賴是 FastAPI、Uvicorn、httpx、pydantic、PyYAML 和 python-dotenv。版本不需要和我完全一樣以你本機(jī)能夠正常安裝為準(zhǔn)關(guān)鍵接口在常見(jiàn)版本里是兼容的。3.1 安裝依賴建議先創(chuàng)建一個(gè)虛擬環(huán)境避免依賴污染系統(tǒng) Pythonpython3 -m venv .venv source .venv/bin/activate # Windows 下為 .venv\Scripts\activate pip install -U pip然后安裝依賴。為了方便復(fù)制我直接給一份 requirements.txtfastapi0.110.0 uvicorn[standard]0.29.0 httpx0.27.0 pydantic2.6.0 pyyaml6.0.1 python-dotenv1.0.13.2 項(xiàng)目目錄結(jié)構(gòu)為了讓教程容易上手我把核心邏輯放在單文件app.py里配置放在config.yaml密鑰放在.env。實(shí)際項(xiàng)目如果變得復(fù)雜可以進(jìn)一步拆分成多個(gè)模塊但單文件版本更適合理解核心邏輯。llm-gateway/ ├── requirements.txt ├── .env # 保存各家真實(shí) API Key不要提交到 Git ├── config.yaml # 網(wǎng)關(guān)主 Key 和上游模型路由配置 └── app.py # 統(tǒng)一網(wǎng)關(guān)主程序4. 完整實(shí)戰(zhàn)用 FastAPI 實(shí)現(xiàn)一個(gè)免費(fèi) LLM 統(tǒng)一網(wǎng)關(guān)從這一節(jié)開(kāi)始我們進(jìn)入到可以運(yùn)行的代碼階段。目標(biāo)很簡(jiǎn)單本地啟動(dòng)一個(gè) HTTP 服務(wù)監(jiān)聽(tīng) 8000 端口對(duì)外提供/v1/chat/completions接口客戶端無(wú)論請(qǐng)求哪個(gè)免費(fèi)模型都只帶同一把主 Key。4.1 編寫配置文件首先創(chuàng)建配置文件config.yaml。它主要描述兩件事網(wǎng)關(guān)自己的主 Key以及上游服務(wù)商的連接信息。注意上游服務(wù)商的實(shí)際 API Key不要寫在這個(gè)文件里而是通過(guò)環(huán)境變量注入后面會(huì)用.env管理。# config.yaml gateway: master_key: sk-gateway-2024 host: 0.0.0.0 port: 8000 providers: - name: deepseek base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY timeout: 120 models: - deepseek-chat - deepseek-reasoner - name: openrouter base_url: https://openrouter.ai/api/v1 api_key_env: OPENROUTER_API_KEY timeout: 120 models: - meta-llama/llama-3.3-70b-instruct:free - mistralai/mistral-7b-instruct:free這里幾個(gè)字段的含義分別是gateway.master_key客戶端訪問(wèn)網(wǎng)關(guān)時(shí)使用的唯一主 Key。實(shí)際項(xiàng)目中應(yīng)該用足夠長(zhǎng)的隨機(jī)字符串。providers[].name服務(wù)商別名只用于日志和排查內(nèi)部不做邏輯判斷。providers[].base_url上游服務(wù)商的 OpenAI 兼容地址必須是服務(wù)商文檔里明確提供的地址。providers[].api_key_env上游 API Key 對(duì)應(yīng)的環(huán)境變量名避免把真實(shí) Key 寫進(jìn)配置文件。providers[].timeout等待上游響應(yīng)的時(shí)間單位是秒免費(fèi)模型響應(yīng)慢時(shí)建議設(shè)置大一點(diǎn)。providers[].models該服務(wù)商下面可以被客戶端調(diào)用的模型列表。再創(chuàng)建一個(gè).env文件用來(lái)保存上游的真實(shí)密鑰# .env DEEPSEEK_API_KEYsk-your-deepseek-key OPENROUTER_API_KEYsk-your-openrouter-key記得把.env加入.gitignore避免 Key 被提交到 Git 倉(cāng)庫(kù)。4.2 編寫統(tǒng)一網(wǎng)關(guān)主程序 app.py接下來(lái)是這篇文章的核心代碼。我會(huì)把鑒權(quán)、路由、轉(zhuǎn)發(fā)邏輯全部放在app.py中注釋對(duì)應(yīng)關(guān)鍵步驟。# app.py import os import yaml from dotenv import load_dotenv from fastapi import FastAPI, Header, HTTPException from fastapi.responses import StreamingResponse from pydantic import BaseModel, ConfigDict import httpx load_dotenv() with open(config.yaml, r, encodingutf-8) as f: cfg yaml.safe_load(f) MASTER_KEY cfg[gateway][master_key] PROVIDERS cfg[providers] app FastAPI(titleFree LLM Gateway) class ChatRequest(BaseModel): OpenAI 兼容請(qǐng)求體。 除了 model/messages/stream 三個(gè)字段外客戶端還可能傳 temperature、 top_p、max_tokens 等參數(shù)所以開(kāi)啟 extraallow 并原樣轉(zhuǎn)發(fā)。 model: str messages: list stream: bool False model_config ConfigDict(extraallow) def check_master_key(authorization: str): 統(tǒng)一鑒權(quán)所有客戶端請(qǐng)求只檢查主 Key。 if not authorization: raise HTTPException(status_code401, detailMissing Authorization header) token authorization.removeprefix(Bearer ).strip() if token ! MASTER_KEY: raise HTTPException(status_code401, detailInvalid API key) def find_provider(model: str): 模型路由根據(jù) model 字段找到對(duì)應(yīng)的上游服務(wù)商配置。 for provider in PROVIDERS: if model in provider[models]: return provider raise HTTPException(status_code404, detailfModel {model} not found) def build_upstream_headers(provider: dict) - dict: 從環(huán)境變量讀取上游真實(shí) Key構(gòu)造上游請(qǐng)求頭。 api_key os.getenv(provider[api_key_env]) if not api_key: raise HTTPException( status_code502, detailfEnv {provider[api_key_env]} is not set, ) return { Authorization: fBearer {api_key}, Content-Type: application/json, } app.post(/v1/chat/completions) async def chat_completions( req: ChatRequest, authorization: str Header(default), ): check_master_key(authorization) if not req.model.strip(): raise HTTPException(status_code400, detailmodel is required) provider find_provider(req.model) url provider[base_url].rstrip(/) /chat/completions payload req.model_dump(exclude_noneTrue) headers build_upstream_headers(provider) if not req.stream: # 非流式把上游返回的 JSON 原樣透?jìng)鹘o客戶端 async with httpx.AsyncClient(timeoutprovider[timeout]) as client: resp await client.post(url, jsonpayload, headersheaders) if resp.status_code ! 200: raise HTTPException(status_coderesp.status_code, detailresp.text) return resp.json() # 流式直接轉(zhuǎn)發(fā)上游的 SSE 事件流 async def event_stream(): async with httpx.AsyncClient(timeoutprovider[timeout]) as client: async with client.stream( POST, url, jsonpayload, headersheaders ) as upstream: async for line in upstream.aiter_lines(): yield line \n return StreamingResponse(event_stream(), media_typetext/event-stream)核心邏輯其實(shí)非常短check_master_key完成統(tǒng)一鑒權(quán)。find_provider根據(jù)model字段定位上游服務(wù)商。build_upstream_headers從環(huán)境變量讀取真實(shí)服務(wù)商 Key。最后使用httpx.AsyncClient異步轉(zhuǎn)發(fā)請(qǐng)求。代碼里最容易被忽略但又很重要的是ChatRequest的extraallow配置。如果不允許額外字段客戶端傳進(jìn)來(lái)的temperature、max_tokens等參數(shù)就會(huì)被 Pydantic 丟棄上游拿不到這些參數(shù)行為就會(huì)和直接調(diào)用官方 API 不一致。打開(kāi)這個(gè)配置并用model_dump()轉(zhuǎn)發(fā)相當(dāng)于把協(xié)議兼容性交給上游判斷網(wǎng)關(guān)不做多余加工。另外流式和非流式走了兩條分支。非流式直接返回 JSON流式則用StreamingResponse把上游 SSE 事件逐行轉(zhuǎn)發(fā)。這樣做的好處是客戶端可以一邊接收一邊渲染體驗(yàn)更接近官方 API。4.3 運(yùn)行網(wǎng)關(guān)啟動(dòng)前先確認(rèn).env里的環(huán)境變量已經(jīng)加載。如果你的終端支持set -a source .env set a可以這樣加載常見(jiàn) IDE 的 run 配置也支持設(shè)置環(huán)境變量文件。pip install -r requirements.txt set -a source .env set a # Linux/macOS 加載 .env uvicorn app:app --host 0.0.0.0 --port 8000運(yùn)行成功后終端會(huì)輸出類似下面的日志INFO: Uvicorn running on http://0.0.0.0:8000 INFO: Application startup complete.4.4 用 curl 驗(yàn)證網(wǎng)關(guān)打開(kāi)一個(gè)新終端用 curl 直接驗(yàn)證非流式接口curl http://localhost:8000/v1/chat/completions \ -H Authorization: Bearer sk-gateway-2024 \ -H Content-Type: application/json \ -d {model: deepseek-chat, messages: [{role: user, content: 你好請(qǐng)用一句話介紹自己}]}如果配置和密鑰都正確返回結(jié)果會(huì)和 OpenAI 官方接口非常相似包含id、choices、usage等字段。再測(cè)試流式接口curl -N http://localhost:8000/v1/chat/completions \ -H Authorization: Bearer sk-gateway-2024 \ -H Content-Type: application/json \ -d {model: deepseek-chat, messages: [{role: user, content: 給我講一個(gè)冷笑話}], stream: true}如果看到一行行data: {...}增量輸出說(shuō)明流式轉(zhuǎn)發(fā)已經(jīng)正常工作。到這一步網(wǎng)關(guān)本身已經(jīng)跑通了剩下的問(wèn)題就是如何讓各種客戶端工具接入。5. 使用統(tǒng)一網(wǎng)關(guān)接入各類 LLM 客戶端網(wǎng)關(guān)對(duì)外暴露的是 OpenAI 兼容接口所以凡是支持自定義 API 地址的客戶端都可以通過(guò)修改 Base URL 和 API Key 接入。下面列舉三種最常見(jiàn)的接入方式。5.1 使用 OpenAI SDK 直連安裝官方 OpenAI SDK 后只需要把base_url改成網(wǎng)關(guān)地址把a(bǔ)pi_key換成網(wǎng)關(guān)主 Keypip install openaifrom openai import OpenAI client OpenAI( api_keysk-gateway-2024, base_urlhttp://localhost:8000/v1, ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 介紹一下你自己}], ) print(resp.choices[0].message.content)這里最關(guān)鍵的認(rèn)知是SDK 本身并不知道你連的是哪家服務(wù)商它只負(fù)責(zé)按照 OpenAI 協(xié)議發(fā)送請(qǐng)求。網(wǎng)關(guān)收到請(qǐng)求后會(huì)根據(jù)model字段找到真實(shí)的上游模型再把結(jié)果返回給 SDK。所以后續(xù)不管你切換成哪個(gè)免費(fèi)模型客戶端代碼都不需要改。5.2 在 LangChain 中接入如果你在用 LangChain 做 Agent 或者 RAG接入方式也很直接。以下是ChatOpenAI的配置示例from langchain_openai import ChatOpenAI llm ChatOpenAI( modeldeepseek-chat, api_keysk-gateway-2024, base_urlhttp://localhost:8000/v1, ) resp llm.invoke(用一句話解釋什么是大語(yǔ)言模型) print(resp.content)在 RAG 場(chǎng)景里同樣可以通過(guò)LLMChain、RetrievalQA等組件把llm實(shí)例傳進(jìn)去。只要統(tǒng)一網(wǎng)關(guān)里的模型路由表配置到位業(yè)務(wù)流程完全不需要關(guān)心底層到底用的是哪個(gè)服務(wù)商。5.3 在 ChatBox 等桌面客戶端中配置很多非開(kāi)發(fā)者也想用圖形界面體驗(yàn)多模型切換。以常見(jiàn) AI 桌面客戶端為例設(shè)置頁(yè)里都會(huì)有“API 地址 / Base URL”和“API Key”兩個(gè)輸入框你只需要把地址填成http://localhost:8000/v1把 Key 填成網(wǎng)關(guān)主 Key 即可。也有一類工具使用config.toml保存模型服務(wù)配置。舉個(gè)例子[model_provider] name llm-gateway base_url http://localhost:8000/v1 api_key sk-gateway-2024 model deepseek-chat如果你的客戶端提示類似“無(wú)法加載 config.toml”或者“model 字段不合法”優(yōu)先檢查model的值是否在網(wǎng)關(guān)的config.yaml的models列表里。客戶端只會(huì)原樣把字符串傳給網(wǎng)關(guān)真正判斷模型是否存在的是網(wǎng)關(guān)本身。還有一類較新的 CLI 編碼工具可能會(huì)優(yōu)先調(diào)用/v1/responses端點(diǎn)而不是/v1/chat/completions。如果工具連接網(wǎng)關(guān)后提示某個(gè) endpoint 不支持可以在網(wǎng)關(guān)里額外增加一個(gè)/v1/responses轉(zhuǎn)發(fā)接口整體思路和chat/completions基本一致只是請(qǐng)求路徑和字段略有不同。遇到這類問(wèn)題時(shí)不要先懷疑 Key 配錯(cuò)了先確認(rèn)工具請(qǐng)求的到底是哪個(gè)端點(diǎn)。6. 常見(jiàn)問(wèn)題與排查思路統(tǒng)一網(wǎng)關(guān)本身不復(fù)雜但接入不同服務(wù)商時(shí)報(bào)錯(cuò)類型會(huì)五花八門。下面整理了一份高頻問(wèn)題對(duì)照表幫助你在第一時(shí)間定位方向。問(wèn)題現(xiàn)象常見(jiàn)原因解決思路401 Invalid API key網(wǎng)關(guān)主 Key 不正確檢查 Authorization 請(qǐng)求頭是否帶了正確的 Bearer Token404 Model not found模型名不在網(wǎng)關(guān)配置里檢查 config.yaml 的 models 列表并確認(rèn)客戶端傳入的 model 值502 Env xxx is not set上游服務(wù)商 Key 未加載檢查 .env 文件和進(jìn)程環(huán)境變量400 maximum context length上下文 token 超長(zhǎng)精簡(jiǎn) messages、分塊、或切換更大上下文模型selected model is at capacity免費(fèi)模型暫時(shí)繁忙等待重試或切換到備用模型上游 400 reasoning_content must be passed back推理模型多輪要求回傳思考字段客戶端完整保留上一輪返回并原樣回傳流式接口無(wú)輸出客戶端沒(méi)有處理 SSE 增量數(shù)據(jù)檢查是否使用 -N / 流式解析邏輯下面挑幾個(gè)最典型的報(bào)錯(cuò)展開(kāi)說(shuō)明。上下文超長(zhǎng)問(wèn)題。當(dāng)你把整份長(zhǎng)文檔直接塞進(jìn) messages 時(shí)上游會(huì)提示類似this models maximum context length is 1048576 tokens, however your prompt has ... tokens。這說(shuō)明輸入長(zhǎng)度超過(guò)了模型的上下文窗口。解決辦法不外乎三個(gè)方向精簡(jiǎn)歷史消息、啟用文檔分塊后再檢索、或者把模型切換成支持更長(zhǎng)上下文的版本。網(wǎng)關(guān)在這個(gè)環(huán)節(jié)能做的只是把上游錯(cuò)誤原樣暴露出來(lái)方便客戶端定位不要在網(wǎng)關(guān)層靜默吞掉錯(cuò)誤。免費(fèi)模型繁忙問(wèn)題。免費(fèi)檔模型的并發(fā)能力通常很有限高峰期很容易返回selected model is at capacity之類的提示。個(gè)人項(xiàng)目的處理思路是增加一層異常重試檢測(cè)到容量錯(cuò)誤時(shí)等待幾秒后換一個(gè)備用模型重試也可以把同一個(gè)模型名映射到兩個(gè)不同服務(wù)商用輪詢策略分發(fā)。需要提醒的是免費(fèi)額度都有服務(wù)商的限流規(guī)則重試時(shí)要遵守退避策略不要寫成無(wú)限快速循環(huán)。推理模型的 thinking 字段回傳問(wèn)題。這是一個(gè)比較隱蔽的坑。當(dāng)上游是帶思考模式的推理模型時(shí)多輪對(duì)話可能會(huì)返回額外的reasoning_content字段表示模型思考過(guò)程的內(nèi)容。部分服務(wù)商要求你把這個(gè)字段原樣保存并在下一輪請(qǐng)求時(shí)一起回傳否則會(huì)直接拒絕請(qǐng)求。網(wǎng)關(guān)如果自作聰明地過(guò)濾掉未知字段反而會(huì)導(dǎo)致上游報(bào)錯(cuò)。所以前面代碼里才特意給ChatRequest開(kāi)了extraallow并用model_dump()把全部字段都轉(zhuǎn)發(fā)出去。遇到類似 400 報(bào)錯(cuò)時(shí)不要急著改網(wǎng)關(guān)先在客戶端檢查上一輪返回內(nèi)容是否被完整保留。模型名不一致問(wèn)題。有些客戶端的模型列表是定時(shí)拉取網(wǎng)關(guān)目錄的如果它請(qǐng)求時(shí)傳入的模型名不在config.yaml的 models 列表里網(wǎng)關(guān)會(huì)返回 404 Model not found。這類報(bào)錯(cuò)通常不是網(wǎng)絡(luò)問(wèn)題而是配置不一致問(wèn)題。先檢查客戶端那邊配置的 model 值再看網(wǎng)關(guān)配置文件里的 models 列表。需要提醒的是不同服務(wù)商對(duì)模型名的大小寫、連字符、版本后綴都很敏感不要憑印象寫。7. 最佳實(shí)踐與工程建議跑通 demo 之后如果要把這套網(wǎng)關(guān)用于真實(shí)項(xiàng)目還需要在密鑰管理、限流、日志和數(shù)據(jù)安全幾個(gè)方向做完善。7.1 密鑰管理與安全邊界網(wǎng)關(guān)的主 Key 和上游服務(wù)商 Key 必須分離。客戶端只應(yīng)該拿到網(wǎng)關(guān)主 Key上游 Key 通過(guò)環(huán)境變量或?qū)ｉT的密鑰管理服務(wù)注入不要寫進(jìn)配置文件也不要通過(guò)任何接口返回給客戶端。主 Key 建議使用較長(zhǎng)的隨機(jī)字符串例如sk-gw-前綴加 32 位以上隨機(jī)內(nèi)容萬(wàn)一泄露直接在 config.yaml 中替換并重啟服務(wù)即可不需要通知客戶端修改。因?yàn)樗锌蛻舳硕贾徽J(rèn)這一個(gè) Key更新成本非常低。另一個(gè)安全邊界是不要從客戶端請(qǐng)求中動(dòng)態(tài)拼接base_url。所有上游地址只能來(lái)自 config.yaml 白名單否則網(wǎng)關(guān)會(huì)被濫用成任意 HTTP 轉(zhuǎn)發(fā)代理帶來(lái)不可控的安全風(fēng)險(xiǎn)。代碼里傳model字段去做路由映射而不是傳 URL 參數(shù)。7.2 限流與配額控制免費(fèi)模型的免費(fèi)額度是稀缺資源網(wǎng)關(guān)最好在入口層加上限流防止某個(gè)調(diào)用方把額度全部打滿。最簡(jiǎn)單的做法是維護(hù)一個(gè)內(nèi)存計(jì)數(shù)器限制每個(gè) Api Key 每分鐘的最大請(qǐng)求數(shù)團(tuán)隊(duì)使用場(chǎng)景建議引入 Redis 做滑動(dòng)窗口限流再把限流規(guī)則做成可配置項(xiàng)。注意不要只做網(wǎng)關(guān)入口的限流還要觀察上游返回的 429 狀態(tài)碼把上游限流信息記錄到日志里。7.3 日志、追蹤與成本統(tǒng)計(jì)每一條請(qǐng)求都建議記錄以下信息請(qǐng)求時(shí)間、模型名、路由到的服務(wù)商、耗時(shí)、token 用量、返回狀態(tài)碼。特別是 token 用量免費(fèi)額度是有上限的統(tǒng)計(jì)后你才能知道哪個(gè)模型消耗最多、哪個(gè)模型總是失敗。日志格式建議直接用 JSON方便后續(xù)接入日志平臺(tái)做檢索和分析。如果同時(shí)跑多個(gè)實(shí)例還要為每個(gè)請(qǐng)求生成一個(gè)trace_id這樣從客戶端到網(wǎng)關(guān)再到上游的完整鏈路才能串起來(lái)。7.4 兼容性與維護(hù)策略ChatRequest開(kāi)啟extraallow是保證協(xié)議兼容性的關(guān)鍵。大模型 API 的參數(shù)一直在演進(jìn)比如新增的工具調(diào)用、結(jié)構(gòu)化輸出字段網(wǎng)關(guān)如果定義了一長(zhǎng)串固定參數(shù)很快就會(huì)過(guò)時(shí)讓未知字段原樣透?jìng)鞣炊軠p少維護(hù)成本。每次新增模型時(shí)先在測(cè)試環(huán)境驗(yàn)證一次非流式和流式調(diào)用再更新生產(chǎn)配置不要直接在線上改配置實(shí)驗(yàn)。7.5 合規(guī)與數(shù)據(jù)安全調(diào)用免費(fèi) LLM API 之前要確認(rèn)服務(wù)商的開(kāi)發(fā)者協(xié)議特別是免費(fèi)額度的使用條件和商用限制。公司項(xiàng)目如果涉及敏感數(shù)據(jù)還要評(píng)估模型服務(wù)商的數(shù)據(jù)留存策略判斷是否允許把業(yè)務(wù)數(shù)據(jù)發(fā)送到對(duì)應(yīng)的模型服務(wù)。必要時(shí)在網(wǎng)關(guān)層增加內(nèi)容脫敏、敏感詞過(guò)濾或?qū)徟鞒瘫苊鈹?shù)據(jù)違規(guī)。這里的基本原則是先看條款再上生產(chǎn)。8. 總結(jié)與學(xué)習(xí)路線看到這里你已經(jīng)完成了一個(gè)最小可用的 LLM API 統(tǒng)一網(wǎng)關(guān)它有一個(gè)統(tǒng)一鑒權(quán)層、一張模型路由表、一層 OpenAI 兼容協(xié)議轉(zhuǎn)發(fā)能夠把多個(gè)免費(fèi)模型服務(wù)收斂到同一把 Key 后面。這個(gè)架構(gòu)雖然很小但它把“多模型接入”“統(tǒng)一鑒權(quán)”“協(xié)議兼容”三個(gè)關(guān)鍵問(wèn)題都覆蓋到了。接下來(lái)如果你想繼續(xù)深入建議按下面順序去研究OpenAI 官方 API 文檔里的參數(shù)細(xì)節(jié)例如temperature、top_p、tool call、response_format是如何參與請(qǐng)求轉(zhuǎn)發(fā)的。SSE 協(xié)議以及如何把流式響應(yīng)包裝成客戶端更容易消費(fèi)的事件流格式。給網(wǎng)關(guān)增加 Redis 緩存、語(yǔ)義緩存讓相同問(wèn)題不再重復(fù)消費(fèi) token。把模型路由從靜態(tài)配置升級(jí)成動(dòng)態(tài)策略例如按成本、按延遲、按成功率自動(dòng)選擇上游。如果這篇文章對(duì)你有幫助可以收藏備用下次接入新模型或排查 API 報(bào)錯(cuò)時(shí)直接對(duì)照配置和清單來(lái)檢查能省不少時(shí)間。有問(wèn)題也可以在評(píng)論區(qū)交流我看到后會(huì)繼續(xù)補(bǔ)充完善。 用FastAPI搭建統(tǒng)一LLM網(wǎng)關(guān)：一個(gè)Key接入所有免費(fèi)模型
先說(shuō)一個(gè)挺常見(jiàn)的場(chǎng)景你同時(shí)想用多個(gè)平臺(tái)的免費(fèi)模型做應(yīng)用于是注冊(cè)賬號(hào)、申請(qǐng) API Key、看文檔、配 SDK、寫代理代碼……一個(gè)接一個(gè)折騰下來(lái)代碼里躺著十幾把 Key每把 Key 對(duì)應(yīng)的請(qǐng)求地址還不一樣。更難受的是等模型版本更新或者某個(gè)平臺(tái)臨時(shí)調(diào)整模型名你還要逐個(gè)修改調(diào)用代碼。這篇文章要解決的就是“免費(fèi)模型很多、Key 也一堆”的碎片化問(wèn)題。我會(huì)從統(tǒng)一 API 網(wǎng)關(guān)的原理講起用 FastAPI 寫一個(gè)最小可用的網(wǎng)關(guān)把多個(gè)免費(fèi)模型服務(wù)統(tǒng)一到一個(gè) Key 后面再給出 OpenAI SDK、LangChain、ChatBox 等常見(jiàn)客戶端的接入方法最后整理一份高頻報(bào)錯(cuò)排查清單。整套代碼都是直白可復(fù)制的適合學(xué)生、個(gè)人開(kāi)發(fā)者和正在做 AI 應(yīng)用原型的團(tuán)隊(duì)參考。1. 為什么需要“一個(gè) Key 接入所有免費(fèi)模型”先解釋標(biāo)題里的“Free LLM API”。它并不是指某一個(gè)具體的模型而是指一種能力通過(guò)一個(gè)統(tǒng)一的 API 入口訪問(wèn)多個(gè)提供免費(fèi)額度或免費(fèi)檔模型的服務(wù)商。目前各家大模型服務(wù)商幾乎都會(huì)提供 OpenAI 兼容接口但它們各自有獨(dú)立的 Base URL、獨(dú)立的鑒權(quán)方式、獨(dú)立的免費(fèi)額度和模型列表。你在項(xiàng)目里每接入一家就要管理一整套配置想換一個(gè)模型又得重新適配一次。統(tǒng)一網(wǎng)關(guān)解決的就是這個(gè)多對(duì)多問(wèn)題。從工程角度看它至少帶來(lái)四個(gè)明確收益。第一接入成本下降?？蛻舳酥恍枰獙?shí)現(xiàn)一套 OpenAI 兼容調(diào)用以后新增模型只是在網(wǎng)管配置里加一行模型名和對(duì)應(yīng)服務(wù)商業(yè)務(wù)代碼完全不用改。第二Key 不再混亂。無(wú)論客戶端跑在本地、測(cè)試服務(wù)器還是 CI 環(huán)境都只需要配置同一個(gè)網(wǎng)關(guān)主 Key省去多個(gè)環(huán)境維護(hù)多套密鑰的煩惱。第三可以做統(tǒng)一容災(zāi)。免費(fèi)模型經(jīng)常遇到“暫時(shí)繁忙”或服務(wù)不穩(wěn)定網(wǎng)關(guān)可以把請(qǐng)求切換到備用模型避免用戶直接看到報(bào)錯(cuò)。第四方便做統(tǒng)一監(jiān)控。不管底層調(diào)用了幾家服務(wù)商日志、請(qǐng)求量、token 消耗都能匯總到同一個(gè)服務(wù)里統(tǒng)計(jì)。市面上確實(shí)有不少“聚合全部免費(fèi)模型”的第三方服務(wù)但與其完全依賴第三方聚合服務(wù)不如先掌握實(shí)現(xiàn)原理再?zèng)Q定是否需要使用現(xiàn)成網(wǎng)關(guān)。自己搭一個(gè)輕量網(wǎng)關(guān)模型列表、密鑰、日志都完全可控后面接新模型也只是改配置的事。2. 統(tǒng)一 LLM API 網(wǎng)關(guān)的核心原理嚴(yán)格來(lái)說(shuō)模型聚合并不需要寫一堆復(fù)雜的 AI 代碼它的本質(zhì)是一個(gè) HTTP 服務(wù)負(fù)責(zé)“把客戶端的請(qǐng)求轉(zhuǎn)給合適的模型服務(wù)商再把結(jié)果轉(zhuǎn)回來(lái)”。要做到一個(gè) Key 管所有模型需要拆成三個(gè)層次來(lái)看。2.1 統(tǒng)一鑒權(quán)層第一層是鑒權(quán)。網(wǎng)關(guān)對(duì)外只暴露一個(gè)主 KeyMaster Key所有客戶端請(qǐng)求都帶這個(gè) Key網(wǎng)關(guān)校驗(yàn)通過(guò)后再用自己的服務(wù)商密鑰去調(diào)用上游。這里的關(guān)鍵點(diǎn)是主 Key 和上游密鑰完全隔離?？蛻舳擞肋h(yuǎn)不應(yīng)該看到 DeepSeek、OpenRouter 或者其他服務(wù)商的實(shí)際密鑰否則就等于把這把鑰匙交出去了。在 FastAPI 里實(shí)現(xiàn)這個(gè)層非常簡(jiǎn)單只需要寫一個(gè)依賴函數(shù)讀請(qǐng)求頭Authorization里的 Bearer Token和配置里的master_key對(duì)比。如果校驗(yàn)失敗直接返回 401。框架代碼后面會(huì)給出。2.2 模型路由與別名映射第二層是路由?？蛻舳藗鬟^(guò)來(lái)的model字段決定請(qǐng)求最終發(fā)給哪家服務(wù)商。最樸素的做法是“模型名映射”網(wǎng)關(guān)維護(hù)一張表每個(gè)模型名對(duì)應(yīng)一個(gè) provider 和它自己的上游模型名。比如內(nèi)部配置了deepseek-chat就轉(zhuǎn)發(fā)到 DeepSeek配置了llama-3.3-70b-instruct:free就轉(zhuǎn)發(fā)到 OpenRouter。這里有一個(gè)容易踩坑的點(diǎn)不同服務(wù)商可能存在同名模型或者同一個(gè)模型在各家的名字不一樣。為了避免路由錯(cuò)亂網(wǎng)關(guān)里的模型名必須全局唯一。如果出現(xiàn)重名建議加前綴命名比如deepseek/deepseek-chat、openrouter/deepseek-chat這樣。但在大多數(shù)個(gè)人場(chǎng)景里直接用模型名作為全局 Key 已經(jīng)足夠了不必過(guò)度設(shè)計(jì)。2.3 協(xié)議兼容層OpenAI 兼容格式第三層是協(xié)議。為什么客戶端只需要寫一套代碼就能調(diào)用所有模型因?yàn)榻^大多數(shù) LLM API 服務(wù)商都提供了 OpenAI 兼容的 HTTP 接口即請(qǐng)求路徑通常是POST /v1/chat/completions請(qǐng)求體包含model、messages、temperature等字段鑒權(quán)通常是Authorization: Bearer key返回結(jié)構(gòu)也是統(tǒng)一的choicesusage格式。網(wǎng)關(guān)要做的事情就是把自己收到的請(qǐng)求盡量原樣轉(zhuǎn)發(fā)給上游。它本身不負(fù)責(zé)理解聊天內(nèi)容只負(fù)責(zé)協(xié)議搬運(yùn)和模型路由。這也是為什么網(wǎng)關(guān)代碼可以做到很短以后回過(guò)來(lái)維護(hù)也不會(huì)覺(jué)得吃力。只要協(xié)議兼容網(wǎng)關(guān)就很容易替換、增加或下線某個(gè)模型服務(wù)。3. 環(huán)境準(zhǔn)備與項(xiàng)目結(jié)構(gòu)寫代碼之前先把環(huán)境準(zhǔn)備好。本文的示例以 Python 3.10 為例使用的核心依賴是 FastAPI、Uvicorn、httpx、pydantic、PyYAML 和 python-dotenv。版本不需要和我完全一樣以你本機(jī)能夠正常安裝為準(zhǔn)關(guān)鍵接口在常見(jiàn)版本里是兼容的。3.1 安裝依賴建議先創(chuàng)建一個(gè)虛擬環(huán)境避免依賴污染系統(tǒng) Pythonpython3 -m venv .venv source .venv/bin/activate # Windows 下為 .venv\Scripts\activate pip install -U pip然后安裝依賴。為了方便復(fù)制我直接給一份 requirements.txtfastapi0.110.0 uvicorn[standard]0.29.0 httpx0.27.0 pydantic2.6.0 pyyaml6.0.1 python-dotenv1.0.13.2 項(xiàng)目目錄結(jié)構(gòu)為了讓教程容易上手我把核心邏輯放在單文件app.py里配置放在config.yaml密鑰放在.env。實(shí)際項(xiàng)目如果變得復(fù)雜可以進(jìn)一步拆分成多個(gè)模塊但單文件版本更適合理解核心邏輯。llm-gateway/ ├── requirements.txt ├── .env # 保存各家真實(shí) API Key不要提交到 Git ├── config.yaml # 網(wǎng)關(guān)主 Key 和上游模型路由配置 └── app.py # 統(tǒng)一網(wǎng)關(guān)主程序4. 完整實(shí)戰(zhàn)用 FastAPI 實(shí)現(xiàn)一個(gè)免費(fèi) LLM 統(tǒng)一網(wǎng)關(guān)從這一節(jié)開(kāi)始我們進(jìn)入到可以運(yùn)行的代碼階段。目標(biāo)很簡(jiǎn)單本地啟動(dòng)一個(gè) HTTP 服務(wù)監(jiān)聽(tīng) 8000 端口對(duì)外提供/v1/chat/completions接口客戶端無(wú)論請(qǐng)求哪個(gè)免費(fèi)模型都只帶同一把主 Key。4.1 編寫配置文件首先創(chuàng)建配置文件config.yaml。它主要描述兩件事網(wǎng)關(guān)自己的主 Key以及上游服務(wù)商的連接信息。注意上游服務(wù)商的實(shí)際 API Key不要寫在這個(gè)文件里而是通過(guò)環(huán)境變量注入后面會(huì)用.env管理。# config.yaml gateway: master_key: sk-gateway-2024 host: 0.0.0.0 port: 8000 providers: - name: deepseek base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY timeout: 120 models: - deepseek-chat - deepseek-reasoner - name: openrouter base_url: https://openrouter.ai/api/v1 api_key_env: OPENROUTER_API_KEY timeout: 120 models: - meta-llama/llama-3.3-70b-instruct:free - mistralai/mistral-7b-instruct:free這里幾個(gè)字段的含義分別是gateway.master_key客戶端訪問(wèn)網(wǎng)關(guān)時(shí)使用的唯一主 Key。實(shí)際項(xiàng)目中應(yīng)該用足夠長(zhǎng)的隨機(jī)字符串。providers[].name服務(wù)商別名只用于日志和排查內(nèi)部不做邏輯判斷。providers[].base_url上游服務(wù)商的 OpenAI 兼容地址必須是服務(wù)商文檔里明確提供的地址。providers[].api_key_env上游 API Key 對(duì)應(yīng)的環(huán)境變量名避免把真實(shí) Key 寫進(jìn)配置文件。providers[].timeout等待上游響應(yīng)的時(shí)間單位是秒免費(fèi)模型響應(yīng)慢時(shí)建議設(shè)置大一點(diǎn)。providers[].models該服務(wù)商下面可以被客戶端調(diào)用的模型列表。再創(chuàng)建一個(gè).env文件用來(lái)保存上游的真實(shí)密鑰# .env DEEPSEEK_API_KEYsk-your-deepseek-key OPENROUTER_API_KEYsk-your-openrouter-key記得把.env加入.gitignore避免 Key 被提交到 Git 倉(cāng)庫(kù)。4.2 編寫統(tǒng)一網(wǎng)關(guān)主程序 app.py接下來(lái)是這篇文章的核心代碼。我會(huì)把鑒權(quán)、路由、轉(zhuǎn)發(fā)邏輯全部放在app.py中注釋對(duì)應(yīng)關(guān)鍵步驟。# app.py import os import yaml from dotenv import load_dotenv from fastapi import FastAPI, Header, HTTPException from fastapi.responses import StreamingResponse from pydantic import BaseModel, ConfigDict import httpx load_dotenv() with open(config.yaml, r, encodingutf-8) as f: cfg yaml.safe_load(f) MASTER_KEY cfg[gateway][master_key] PROVIDERS cfg[providers] app FastAPI(titleFree LLM Gateway) class ChatRequest(BaseModel): OpenAI 兼容請(qǐng)求體。 除了 model/messages/stream 三個(gè)字段外客戶端還可能傳 temperature、 top_p、max_tokens 等參數(shù)所以開(kāi)啟 extraallow 并原樣轉(zhuǎn)發(fā)。 model: str messages: list stream: bool False model_config ConfigDict(extraallow) def check_master_key(authorization: str): 統(tǒng)一鑒權(quán)所有客戶端請(qǐng)求只檢查主 Key。 if not authorization: raise HTTPException(status_code401, detailMissing Authorization header) token authorization.removeprefix(Bearer ).strip() if token ! MASTER_KEY: raise HTTPException(status_code401, detailInvalid API key) def find_provider(model: str): 模型路由根據(jù) model 字段找到對(duì)應(yīng)的上游服務(wù)商配置。 for provider in PROVIDERS: if model in provider[models]: return provider raise HTTPException(status_code404, detailfModel {model} not found) def build_upstream_headers(provider: dict) - dict: 從環(huán)境變量讀取上游真實(shí) Key構(gòu)造上游請(qǐng)求頭。 api_key os.getenv(provider[api_key_env]) if not api_key: raise HTTPException( status_code502, detailfEnv {provider[api_key_env]} is not set, ) return { Authorization: fBearer {api_key}, Content-Type: application/json, } app.post(/v1/chat/completions) async def chat_completions( req: ChatRequest, authorization: str Header(default), ): check_master_key(authorization) if not req.model.strip(): raise HTTPException(status_code400, detailmodel is required) provider find_provider(req.model) url provider[base_url].rstrip(/) /chat/completions payload req.model_dump(exclude_noneTrue) headers build_upstream_headers(provider) if not req.stream: # 非流式把上游返回的 JSON 原樣透?jìng)鹘o客戶端 async with httpx.AsyncClient(timeoutprovider[timeout]) as client: resp await client.post(url, jsonpayload, headersheaders) if resp.status_code ! 200: raise HTTPException(status_coderesp.status_code, detailresp.text) return resp.json() # 流式直接轉(zhuǎn)發(fā)上游的 SSE 事件流 async def event_stream(): async with httpx.AsyncClient(timeoutprovider[timeout]) as client: async with client.stream( POST, url, jsonpayload, headersheaders ) as upstream: async for line in upstream.aiter_lines(): yield line \n return StreamingResponse(event_stream(), media_typetext/event-stream)核心邏輯其實(shí)非常短check_master_key完成統(tǒng)一鑒權(quán)。find_provider根據(jù)model字段定位上游服務(wù)商。build_upstream_headers從環(huán)境變量讀取真實(shí)服務(wù)商 Key。最后使用httpx.AsyncClient異步轉(zhuǎn)發(fā)請(qǐng)求。代碼里最容易被忽略但又很重要的是ChatRequest的extraallow配置。如果不允許額外字段客戶端傳進(jìn)來(lái)的temperature、max_tokens等參數(shù)就會(huì)被 Pydantic 丟棄上游拿不到這些參數(shù)行為就會(huì)和直接調(diào)用官方 API 不一致。打開(kāi)這個(gè)配置并用model_dump()轉(zhuǎn)發(fā)相當(dāng)于把協(xié)議兼容性交給上游判斷網(wǎng)關(guān)不做多余加工。另外流式和非流式走了兩條分支。非流式直接返回 JSON流式則用StreamingResponse把上游 SSE 事件逐行轉(zhuǎn)發(fā)。這樣做的好處是客戶端可以一邊接收一邊渲染體驗(yàn)更接近官方 API。4.3 運(yùn)行網(wǎng)關(guān)啟動(dòng)前先確認(rèn).env里的環(huán)境變量已經(jīng)加載。如果你的終端支持set -a source .env set a可以這樣加載常見(jiàn) IDE 的 run 配置也支持設(shè)置環(huán)境變量文件。pip install -r requirements.txt set -a source .env set a # Linux/macOS 加載 .env uvicorn app:app --host 0.0.0.0 --port 8000運(yùn)行成功后終端會(huì)輸出類似下面的日志INFO: Uvicorn running on http://0.0.0.0:8000 INFO: Application startup complete.4.4 用 curl 驗(yàn)證網(wǎng)關(guān)打開(kāi)一個(gè)新終端用 curl 直接驗(yàn)證非流式接口curl http://localhost:8000/v1/chat/completions \ -H Authorization: Bearer sk-gateway-2024 \ -H Content-Type: application/json \ -d {model: deepseek-chat, messages: [{role: user, content: 你好請(qǐng)用一句話介紹自己}]}如果配置和密鑰都正確返回結(jié)果會(huì)和 OpenAI 官方接口非常相似包含id、choices、usage等字段。再測(cè)試流式接口curl -N http://localhost:8000/v1/chat/completions \ -H Authorization: Bearer sk-gateway-2024 \ -H Content-Type: application/json \ -d {model: deepseek-chat, messages: [{role: user, content: 給我講一個(gè)冷笑話}], stream: true}如果看到一行行data: {...}增量輸出說(shuō)明流式轉(zhuǎn)發(fā)已經(jīng)正常工作。到這一步網(wǎng)關(guān)本身已經(jīng)跑通了剩下的問(wèn)題就是如何讓各種客戶端工具接入。5. 使用統(tǒng)一網(wǎng)關(guān)接入各類 LLM 客戶端網(wǎng)關(guān)對(duì)外暴露的是 OpenAI 兼容接口所以凡是支持自定義 API 地址的客戶端都可以通過(guò)修改 Base URL 和 API Key 接入。下面列舉三種最常見(jiàn)的接入方式。5.1 使用 OpenAI SDK 直連安裝官方 OpenAI SDK 后只需要把base_url改成網(wǎng)關(guān)地址把a(bǔ)pi_key換成網(wǎng)關(guān)主 Keypip install openaifrom openai import OpenAI client OpenAI( api_keysk-gateway-2024, base_urlhttp://localhost:8000/v1, ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 介紹一下你自己}], ) print(resp.choices[0].message.content)這里最關(guān)鍵的認(rèn)知是SDK 本身并不知道你連的是哪家服務(wù)商它只負(fù)責(zé)按照 OpenAI 協(xié)議發(fā)送請(qǐng)求。網(wǎng)關(guān)收到請(qǐng)求后會(huì)根據(jù)model字段找到真實(shí)的上游模型再把結(jié)果返回給 SDK。所以后續(xù)不管你切換成哪個(gè)免費(fèi)模型客戶端代碼都不需要改。5.2 在 LangChain 中接入如果你在用 LangChain 做 Agent 或者 RAG接入方式也很直接。以下是ChatOpenAI的配置示例from langchain_openai import ChatOpenAI llm ChatOpenAI( modeldeepseek-chat, api_keysk-gateway-2024, base_urlhttp://localhost:8000/v1, ) resp llm.invoke(用一句話解釋什么是大語(yǔ)言模型) print(resp.content)在 RAG 場(chǎng)景里同樣可以通過(guò)LLMChain、RetrievalQA等組件把llm實(shí)例傳進(jìn)去。只要統(tǒng)一網(wǎng)關(guān)里的模型路由表配置到位業(yè)務(wù)流程完全不需要關(guān)心底層到底用的是哪個(gè)服務(wù)商。5.3 在 ChatBox 等桌面客戶端中配置很多非開(kāi)發(fā)者也想用圖形界面體驗(yàn)多模型切換。以常見(jiàn) AI 桌面客戶端為例設(shè)置頁(yè)里都會(huì)有“API 地址 / Base URL”和“API Key”兩個(gè)輸入框你只需要把地址填成http://localhost:8000/v1把 Key 填成網(wǎng)關(guān)主 Key 即可。也有一類工具使用config.toml保存模型服務(wù)配置。舉個(gè)例子[model_provider] name llm-gateway base_url http://localhost:8000/v1 api_key sk-gateway-2024 model deepseek-chat如果你的客戶端提示類似“無(wú)法加載 config.toml”或者“model 字段不合法”優(yōu)先檢查model的值是否在網(wǎng)關(guān)的config.yaml的models列表里。客戶端只會(huì)原樣把字符串傳給網(wǎng)關(guān)真正判斷模型是否存在的是網(wǎng)關(guān)本身。還有一類較新的 CLI 編碼工具可能會(huì)優(yōu)先調(diào)用/v1/responses端點(diǎn)而不是/v1/chat/completions。如果工具連接網(wǎng)關(guān)后提示某個(gè) endpoint 不支持可以在網(wǎng)關(guān)里額外增加一個(gè)/v1/responses轉(zhuǎn)發(fā)接口整體思路和chat/completions基本一致只是請(qǐng)求路徑和字段略有不同。遇到這類問(wèn)題時(shí)不要先懷疑 Key 配錯(cuò)了先確認(rèn)工具請(qǐng)求的到底是哪個(gè)端點(diǎn)。6. 常見(jiàn)問(wèn)題與排查思路統(tǒng)一網(wǎng)關(guān)本身不復(fù)雜但接入不同服務(wù)商時(shí)報(bào)錯(cuò)類型會(huì)五花八門。下面整理了一份高頻問(wèn)題對(duì)照表幫助你在第一時(shí)間定位方向。問(wèn)題現(xiàn)象常見(jiàn)原因解決思路401 Invalid API key網(wǎng)關(guān)主 Key 不正確檢查 Authorization 請(qǐng)求頭是否帶了正確的 Bearer Token404 Model not found模型名不在網(wǎng)關(guān)配置里檢查 config.yaml 的 models 列表并確認(rèn)客戶端傳入的 model 值502 Env xxx is not set上游服務(wù)商 Key 未加載檢查 .env 文件和進(jìn)程環(huán)境變量400 maximum context length上下文 token 超長(zhǎng)精簡(jiǎn) messages、分塊、或切換更大上下文模型selected model is at capacity免費(fèi)模型暫時(shí)繁忙等待重試或切換到備用模型上游 400 reasoning_content must be passed back推理模型多輪要求回傳思考字段客戶端完整保留上一輪返回并原樣回傳流式接口無(wú)輸出客戶端沒(méi)有處理 SSE 增量數(shù)據(jù)檢查是否使用 -N / 流式解析邏輯下面挑幾個(gè)最典型的報(bào)錯(cuò)展開(kāi)說(shuō)明。上下文超長(zhǎng)問(wèn)題。當(dāng)你把整份長(zhǎng)文檔直接塞進(jìn) messages 時(shí)上游會(huì)提示類似this models maximum context length is 1048576 tokens, however your prompt has ... tokens。這說(shuō)明輸入長(zhǎng)度超過(guò)了模型的上下文窗口。解決辦法不外乎三個(gè)方向精簡(jiǎn)歷史消息、啟用文檔分塊后再檢索、或者把模型切換成支持更長(zhǎng)上下文的版本。網(wǎng)關(guān)在這個(gè)環(huán)節(jié)能做的只是把上游錯(cuò)誤原樣暴露出來(lái)方便客戶端定位不要在網(wǎng)關(guān)層靜默吞掉錯(cuò)誤。免費(fèi)模型繁忙問(wèn)題。免費(fèi)檔模型的并發(fā)能力通常很有限高峰期很容易返回selected model is at capacity之類的提示。個(gè)人項(xiàng)目的處理思路是增加一層異常重試檢測(cè)到容量錯(cuò)誤時(shí)等待幾秒后換一個(gè)備用模型重試也可以把同一個(gè)模型名映射到兩個(gè)不同服務(wù)商用輪詢策略分發(fā)。需要提醒的是免費(fèi)額度都有服務(wù)商的限流規(guī)則重試時(shí)要遵守退避策略不要寫成無(wú)限快速循環(huán)。推理模型的 thinking 字段回傳問(wèn)題。這是一個(gè)比較隱蔽的坑。當(dāng)上游是帶思考模式的推理模型時(shí)多輪對(duì)話可能會(huì)返回額外的reasoning_content字段表示模型思考過(guò)程的內(nèi)容。部分服務(wù)商要求你把這個(gè)字段原樣保存并在下一輪請(qǐng)求時(shí)一起回傳否則會(huì)直接拒絕請(qǐng)求。網(wǎng)關(guān)如果自作聰明地過(guò)濾掉未知字段反而會(huì)導(dǎo)致上游報(bào)錯(cuò)。所以前面代碼里才特意給ChatRequest開(kāi)了extraallow并用model_dump()把全部字段都轉(zhuǎn)發(fā)出去。遇到類似 400 報(bào)錯(cuò)時(shí)不要急著改網(wǎng)關(guān)先在客戶端檢查上一輪返回內(nèi)容是否被完整保留。模型名不一致問(wèn)題。有些客戶端的模型列表是定時(shí)拉取網(wǎng)關(guān)目錄的如果它請(qǐng)求時(shí)傳入的模型名不在config.yaml的 models 列表里網(wǎng)關(guān)會(huì)返回 404 Model not found。這類報(bào)錯(cuò)通常不是網(wǎng)絡(luò)問(wèn)題而是配置不一致問(wèn)題。先檢查客戶端那邊配置的 model 值再看網(wǎng)關(guān)配置文件里的 models 列表。需要提醒的是不同服務(wù)商對(duì)模型名的大小寫、連字符、版本后綴都很敏感不要憑印象寫。7. 最佳實(shí)踐與工程建議跑通 demo 之后如果要把這套網(wǎng)關(guān)用于真實(shí)項(xiàng)目還需要在密鑰管理、限流、日志和數(shù)據(jù)安全幾個(gè)方向做完善。7.1 密鑰管理與安全邊界網(wǎng)關(guān)的主 Key 和上游服務(wù)商 Key 必須分離。客戶端只應(yīng)該拿到網(wǎng)關(guān)主 Key上游 Key 通過(guò)環(huán)境變量或?qū)ｉT的密鑰管理服務(wù)注入不要寫進(jìn)配置文件也不要通過(guò)任何接口返回給客戶端。主 Key 建議使用較長(zhǎng)的隨機(jī)字符串例如sk-gw-前綴加 32 位以上隨機(jī)內(nèi)容萬(wàn)一泄露直接在 config.yaml 中替換并重啟服務(wù)即可不需要通知客戶端修改。因?yàn)樗锌蛻舳硕贾徽J(rèn)這一個(gè) Key更新成本非常低。另一個(gè)安全邊界是不要從客戶端請(qǐng)求中動(dòng)態(tài)拼接base_url。所有上游地址只能來(lái)自 config.yaml 白名單否則網(wǎng)關(guān)會(huì)被濫用成任意 HTTP 轉(zhuǎn)發(fā)代理帶來(lái)不可控的安全風(fēng)險(xiǎn)。代碼里傳model字段去做路由映射而不是傳 URL 參數(shù)。7.2 限流與配額控制免費(fèi)模型的免費(fèi)額度是稀缺資源網(wǎng)關(guān)最好在入口層加上限流防止某個(gè)調(diào)用方把額度全部打滿。最簡(jiǎn)單的做法是維護(hù)一個(gè)內(nèi)存計(jì)數(shù)器限制每個(gè) Api Key 每分鐘的最大請(qǐng)求數(shù)團(tuán)隊(duì)使用場(chǎng)景建議引入 Redis 做滑動(dòng)窗口限流再把限流規(guī)則做成可配置項(xiàng)。注意不要只做網(wǎng)關(guān)入口的限流還要觀察上游返回的 429 狀態(tài)碼把上游限流信息記錄到日志里。7.3 日志、追蹤與成本統(tǒng)計(jì)每一條請(qǐng)求都建議記錄以下信息請(qǐng)求時(shí)間、模型名、路由到的服務(wù)商、耗時(shí)、token 用量、返回狀態(tài)碼。特別是 token 用量免費(fèi)額度是有上限的統(tǒng)計(jì)后你才能知道哪個(gè)模型消耗最多、哪個(gè)模型總是失敗。日志格式建議直接用 JSON方便后續(xù)接入日志平臺(tái)做檢索和分析。如果同時(shí)跑多個(gè)實(shí)例還要為每個(gè)請(qǐng)求生成一個(gè)trace_id這樣從客戶端到網(wǎng)關(guān)再到上游的完整鏈路才能串起來(lái)。7.4 兼容性與維護(hù)策略ChatRequest開(kāi)啟extraallow是保證協(xié)議兼容性的關(guān)鍵。大模型 API 的參數(shù)一直在演進(jìn)比如新增的工具調(diào)用、結(jié)構(gòu)化輸出字段網(wǎng)關(guān)如果定義了一長(zhǎng)串固定參數(shù)很快就會(huì)過(guò)時(shí)讓未知字段原樣透?jìng)鞣炊軠p少維護(hù)成本。每次新增模型時(shí)先在測(cè)試環(huán)境驗(yàn)證一次非流式和流式調(diào)用再更新生產(chǎn)配置不要直接在線上改配置實(shí)驗(yàn)。7.5 合規(guī)與數(shù)據(jù)安全調(diào)用免費(fèi) LLM API 之前要確認(rèn)服務(wù)商的開(kāi)發(fā)者協(xié)議特別是免費(fèi)額度的使用條件和商用限制。公司項(xiàng)目如果涉及敏感數(shù)據(jù)還要評(píng)估模型服務(wù)商的數(shù)據(jù)留存策略判斷是否允許把業(yè)務(wù)數(shù)據(jù)發(fā)送到對(duì)應(yīng)的模型服務(wù)。必要時(shí)在網(wǎng)關(guān)層增加內(nèi)容脫敏、敏感詞過(guò)濾或?qū)徟鞒瘫苊鈹?shù)據(jù)違規(guī)。這里的基本原則是先看條款再上生產(chǎn)。8. 總結(jié)與學(xué)習(xí)路線看到這里你已經(jīng)完成了一個(gè)最小可用的 LLM API 統(tǒng)一網(wǎng)關(guān)它有一個(gè)統(tǒng)一鑒權(quán)層、一張模型路由表、一層 OpenAI 兼容協(xié)議轉(zhuǎn)發(fā)能夠把多個(gè)免費(fèi)模型服務(wù)收斂到同一把 Key 后面。這個(gè)架構(gòu)雖然很小但它把“多模型接入”“統(tǒng)一鑒權(quán)”“協(xié)議兼容”三個(gè)關(guān)鍵問(wèn)題都覆蓋到了。接下來(lái)如果你想繼續(xù)深入建議按下面順序去研究OpenAI 官方 API 文檔里的參數(shù)細(xì)節(jié)例如temperature、top_p、tool call、response_format是如何參與請(qǐng)求轉(zhuǎn)發(fā)的。SSE 協(xié)議以及如何把流式響應(yīng)包裝成客戶端更容易消費(fèi)的事件流格式。給網(wǎng)關(guān)增加 Redis 緩存、語(yǔ)義緩存讓相同問(wèn)題不再重復(fù)消費(fèi) token。把模型路由從靜態(tài)配置升級(jí)成動(dòng)態(tài)策略例如按成本、按延遲、按成功率自動(dòng)選擇上游。如果這篇文章對(duì)你有幫助可以收藏備用下次接入新模型或排查 API 報(bào)錯(cuò)時(shí)直接對(duì)照配置和清單來(lái)檢查能省不少時(shí)間。有問(wèn)題也可以在評(píng)論區(qū)交流我看到后會(huì)繼續(xù)補(bǔ)充完善。