1. 为什么需要一个独立的LLM API Gateway层1.1 项目诞生的背景从一次“Key风暴”说起先讲讲我做这个项目的源头。去年中旬我们团队在开发一个AI Agent平台前后端加起来要对接OpenAI、Anthropic、智谱、通义、DeepSeek五家模型服务商。一开始是直接在业务代码里用各家SDK写请求很快就失控了——每个服务的鉴权方式不一样、接口字段有差异、限流策略也不同最要命的是某个服务商一旦故障或限流整个Agent流程就瘫痪。业务方又来催功能我只能在代码里到处打补丁那段时间几乎是哪家能用调哪家的混沌状态。后来我意识到这个问题和微服务时代的API Gateway解决的是同一类问题——前端服务不应该直接跟多个上游服务耦合中间必须加一层统一的网关。于是就有了llm-proxy-tk这个开源项目一个轻量的LLM API Gateway把所有大模型服务商收敛到统一的OpenAI兼容接口后面负责请求转发、密钥托管、模型路由、缓存、限流和故障降级。这个项目适合谁如果你正在做AI应用、Agent系统或者企业内部在统一管理多个模型服务商的调用再或者你希望在不改动业务代码的前提下切换模型供应商那么这篇拆解会很有参考价值。我不会只讲架构图会把每个关键点的选型逻辑、实现细节和踩坑记录都掰开来讲。1.2 网关到底帮我们解决了哪几类问题我在设计llm-proxy-tk之前先把痛点清单列了一遍最终归纳为四类问题这也成了项目的四个核心模块接口统一问题业务方只需要对接一个端点和一个鉴权方式不需要关心上游是哪家服务商模型名称怎么映射请求参数有什么差异。密钥安全与管理问题不能把各家服务商的Key分散在各个业务服务里需要中心化的Key托管和子Key发放能力。稳定性与倍率控制问题服务商可能限流、可能宕机、可能临时调整价格网关层要做路由容灾、失败重试和成本配额控制。可观测性问题每一次请求消耗了多少Token、花了多少钱、调了哪家的模型必须有完整的日志和度量数据才能做成本分析。这些不是锦上添花的功能而是AI应用规模化之后必须面对的基础设施问题。llm-proxy-tk设计时就以这四个能力为核心后面每个模块的具体实现都对应着其中一类问题。2. 整体架构设计与技术选型2.1 架构总览与核心模块llm-proxy-tk的整体架构可以概括为一个控制平面加一个数据平面。控制平面负责配置管理、密钥管理、模型路由策略的定义数据平面负责接收业务请求、做前置校验、路由转发、结果缓存、流式透传和计费日志。两者之间通过数据库和内存缓存协同工作保证配置变更能快速生效又不会让每次请求都打到数据库上。从代码层面看我把它拆成了七个模块controllerHTTP接口层统一暴露/v1/chat/completions和/v1/models等OpenAI兼容端点。auth鉴权模块负责校验调用方传入的API Key判断Key对应的权限和配额。router路由模块根据模型名、调用方身份、上游健康状态选择实际目标服务商。transformer请求/响应的格式转换层把统一的中间格式翻译成各家服务商的实际格式。cache缓存模块支持精确缓存和语义缓存两种模式。circuit_breaker熔断与降级模块连续失败超过阈值就自动摘除该上游。observer日志、指标、计费数据的采集模块用结构化JSON输出到本地或推送到Prometheus等监控系统。这个模块划分的思路来源于我在实践中反复调整得出的结论。一开始我把路由和转换耦合在一起后来发现当上游数量增加、各家接口差异越来越复杂的时候两者必须分开否则每加一个新服务商都要改路由逻辑风险太高。2.2 为什么选Python/FastAPI而不是其他技术栈技术选型上我最终选择了Python 3.11 FastAPI。这个选择要考虑的东西其实不少。首先是团队的维护成本——Python是AI生态中使用最广泛的语言后续要让更多人参与开源贡献门槛最低。其次是异步性能FastAPI基于ASGI配合httpx的异步客户端可以在单进程内同时处理大量IO密集型请求而LLM请求的核心特性恰恰就是高延迟、IO密集。比较过Node.js和Go的方案。Node.js的异步模型和流式处理也很适合但生态里处理SSE流的库质量参差不齐Go的性能很好适合做纯转发网关但要实现灵活的模板化请求转换代码量会明显增加开发节奏会变慢。所以我最终确定了Python路线在保证性能够用的前提下把开发效率和可维护性放在首位。关于性能要说一句公道话LLM网关的瓶颈几乎永远在上游模型的响应时间上一次推理动辄几百毫秒到几十秒网关本身的转发开销只有几十毫秒甚至更低所以Python这里完全不是短板。数据平面加个简单的内存限流器单机跑几百QPS的纯转发任务没有任何压力。2.3 数据存储与缓存方案的选择存储层的设计我遵循够用就好原则没有一上来就上重型中间件。llm-proxy-tk默认使用SQLite存储配置、密钥和计费记录因为单机部署场景下SQLite完全够用而且零运维成本。如果后续要横向扩展数据层预留了一个简单ORM协议可以无缝切到PostgreSQL。缓存层使用了Redis 本地内存双级缓存。因为启动时需要用Redis存语义缓存和分布式限流计数运行时还要把热点请求的响应缓存在本地减少网络开销。我推荐有条件的用户在部署时至少配一个Redis实例没有Redis网关也能单机跑但很多高可用特性、分布式限流能力和多副本一致性就用不了。为什么缓存对LLM网关极其重要因为Token就是金钱。同一个请总结这份文档的请求如果短时间内被多个用户触发精确缓存可以直接复用第一次调用返回的完整结果节省的可能是几万Token的开销。这在企业内部工具或者自动化流程里效果立竿见影。3. 核心功能实现与关键技术点解析3.1 统一请求模型的实现一个翻译层的自我修养兼容多服务商的第一难点不是鉴权而是请求格式的差异。谁都知道OpenAI的ChatCompletion长什么样messages数组加上model、temperature、max_tokens这些参数。但换成Anthropic就变了它的Messages API要求system单独传max_tokens是必填的工具调用格式也和OpenAI不完全一样。再换到国内的几家服务商有的兼容OpenAI格式有的又有自己特殊的字段。llm-proxy-tk的处理方式是内部定义一套网关统一模型这个模型是OpenAI格式的超集支持OpenAI的所有标准参数同时对各家特有的参数做了扩展字段。上游适配器负责在统一模型和各厂商模型之间做转换。我举个例子说明这个设计的关键。OpenAI的response_format只支持json_object但智谱的GLM-4支持json_schema方式可以指定输出的JSON结构。如果我们把网关模型直接限定成OpenAI格式就无法把后者的特性暴露给调用方。所以统一模型的扩展字段设计很重要调用方可以在请求里加extra_body字段网关会把extra_body的内容合并进上游请求体实现了支持OpenAI标准但不被OpenAI标准束缚。为了实现这个转换我在transformer模块里定义了每个上游的适配器类统一接口就是to_provider_request(unified_request, provider_config)和to_unified_response(provider_response, request_id)这两个方法。模块化的好处是新接入一家服务商时不需要改动路由和鉴权逻辑只需新增一个适配器文件。3.2 流式响应的透传与兼容处理LLM网关和普通API网关最不一样的地方在于流式响应SSE。一次非流式的请求返回一个完整的JSON但流式请求会返回一串以data:开头的分片每个分片对应一个token或者一段增量内容。如果网关只是简单地把上游的SSE流原样转发给客户端很多场景下会出问题一是上游厂商的SSE分片格式有差异有些会带[DONE]标记有些不会二是中间要插入计费信息时原样转发就没地方写了。llm-proxy-tk对流式响应的处理方式是逐块转发模式。上游每推来一个SSE事件网关立即把这个事件转发给客户端保证首字延迟极低。在这条链路上我用到的是FastAPI的StreamingResponse底层是一个异步generator。每个事件被读取后先做可选到的格式规整比如把某些厂商的fields映射成OpenAI风格再写入客户端的响应流。这里有一个性能关键点不要等整个流结束再返回给客户端也不要对每个分片做太重的处理。LLM流式响应的首字延迟就是用户体验的生命线一个在翻译层上磨蹭了300毫秒才转发出第一块的网关用户感知上就是模型变蠢又变慢了。在做格式统一的时候我另外做了一个折中设计如果调用方在请求里设置了stream_options: {include_usage: true}网关会在流转结束前的最后一个SSE事件里附加Token用量数据。如果上游本身不返回usage网关会上游请求结束后用tiktoken估算并写入。这个功能对网关的计费模块特别重要也是我做观测数据闭环的关键一环。3.3 多上游的路由、熔断与降级策略路由模块可能是这个项目里最值钱的部分。路由策略我支持三种模式直通模式模型名严格匹配用户要求哪个模型就转发到对应上游。故障转移模式同一模型配置了多个上游主上游失败或超时时自动切换到备用的。权重流量分配支持按百分比把请求分发到多个上游方便做金丝雀发布、双跑比对和成本优化测试。故障转移的判断逻辑不是简单的报错就切。我把失败分为三类限流类错误HTTP 429、服务端错误HTTP 5xx、网络错误连接超时、连接重置等。只有服务端错误和网络错误会触发自动切换限流类错误直接返回给调用方并附带Retry-After头因为这时候切换上游并不能解决问题反而可能把所有上游都打满。熔断器的实现采用了经典的滑动窗口错误率阈值模型。比如在5秒窗口内如果某上游的错误率超过50%且请求数超过10次就熔断开路5秒。熔断期间所有指向该上游的请求直接走降级路径等到时间窗口结束后进入半开状态放一个探测请求验证上游是否恢复。在降级策略上我还引入了一个很有意思的机制模型语义降级。比如主上游的gpt-4o不可用网关自动改调本配置里标注的等价模型如claude-sonnet-4-5如果还没配就返回一个明确的降级响应告诉调用方当前可用的替代模型是哪些避免调用方一头雾水。3.4 密钥托管与子Key权限体系密钥管理模块解决的痛点非常直接你不能在业务服务里写死外部大模型的Key也不能让所有业务方共享一个主Key否则没法审计、没法定价、没法限制用量。llm-proxy-tk对密钥的管理分两层。物理层面对接各上游的真实密钥提供配置界面录入逻辑层面为每个调用方或应用生成独立的子Key。一个子Key可以绑定一个或多个模型并配置每日或每月的Token限额、费用上限、熔断期。这样每个业务团队申请自己的Key出问题可以独立吊销不会影响其他业务。鉴权流程上请求进入网关后先从请求头取Authorization: Bearer xxx在Redis里查该Key的元信息缓存提升性能如果Redis没有就回源数据库并设置了5分钟的内存缓存。校验通过后key的元信息会附加到请求上下文中路由模块在转发时用它替换为真实的物理上游Key业务层永远不会看到物理Key。运维提示上线初期务必在config.yaml里开启redact_sensitive_log这样observer模块在记录日志时会自动把请求体内的所有API Key字段脱敏。真踩过这个坑——日志一旦进到ELK或SentryKey想清理干净几乎是要翻底层存储的。4. 实操过程与核心代码实现4.1 快速部署从克隆到第一次转发请求我先展示一个最简部署路径你可以在这个基础上按自己的业务场景做扩展。# 1. 克隆项目 git clone https://github.com/yourname/llm-proxy-tk.git cd llm-proxy-tk # 2. 安装依赖建议用虚拟环境 python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 3. 编辑配置 cp config.example.yaml config.yaml vim config.yaml配置文件的upstreams段是最核心的配置项我给出一个双上游故障转移的示例upstreams: - name: openai-primary provider: openai base_url: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY models: - * # 接受所有模型名 priority: 1 - name: deepseek-fallback provider: openai base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - * priority: 2 route: strategy: failover # 故障转移模式 failover_threshold: 2 # 连续失败2次后自动切换然后启动服务python -m llm_proxy_tk.server --config config.yaml默认监听8000端口。用curl实测一下curl http://localhost:8000/v1/chat/completions \ -H Authorization: Bearer your-sub-key-or-master-key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好}], stream: false }网关会检查模型名gpt-4o-mini路由到openai-primary如果它连续故障自动切到deepseek-fallback并在响应头的X-GW-Upstream字段标明实际命中的上游名称。这个响应头字段虽然不标准但对排查问题帮助特别大。4.2 核心路由转发代码拆解这里的路由模块是整项目里最核心的一段逻辑。我不把完整源码贴出来但把关键处理流程用代码的思路讲清楚async def route_request(self, request: UnifiedRequest): # 1. 根据请求中的model名找到所有候选上游 candidates self.find_candidates(request.model) # 2. 按priority排序并过滤掉熔断的 healthy_candidates [ up for up in candidates if not self.breaker.is_open(up.name) ] # 3. 按策略选择 for up in sorted(healthy_candidates, keylambda u: u.priority): try: response await self.forward(up, request) return response except UpstreamUnavailableError as e: # 记录连续失败次数给熔断器 self.breaker.record_failure(up.name) continue raise NoHealthyUpstreamError(...)这个实现的核心思想是顺序尝试所有健康上游。每轮请求在选择上游时都会实时检查熔断状态所以配置变更和熔断状态能快速生效不需要重启进程。4.3 流式处理的实现示例流式处理是一个generator加上自动化的格式转换。核心示意如下async def stream_forward(upstream, unified_request, client_request): async with httpx.AsyncClient(timeoutNone) as client: async with client.stream(POST, upstream.url, jsonpayload) as resp: async for line in resp.aiter_lines(): if not line.startswith(data: ): continue data line[6:] if data.strip() [DONE]: yield data: [DONE]\n\n break # 可在这里做统一格式转换 unified_event transform_stream_event(data) yield fdata: {unified_event}\n\n注意timeoutNone是必须的模型推理时间没法预知普通HTTP客户端默认的超时时间会导致长回复直接被切断。这个问题我在常见问题部分会专门展开。4.4 计费统计与观测落地LLM网关如果少了计费统计就不算一个合格的统一入口。llm-proxy-tk的observer模块会在每次请求完成后异步写入一条计费记录包含以下核心字段request_id全局唯一请求ID链路追踪的锚点。api_key_hash子Key的哈希值用于区分调用方。providermodel实际命中的上游和模型名。prompt_tokens、completion_tokens、total_tokensToken用量。cost_usd估算费用根据上游报价表和Token用量相乘。latency_ms从请求进入到响应完成的耗时。streamed是否为流式请求。status_codeerror_type成功或失败类型。这些数据实际使用中会让我对系统运行状态一目了然。比如某天突然发现某个子Key的cost_usd是在飙升立刻能回溯是哪个应用在大量消耗模型额度。如果配合Prometheus还能做一个简单的监控面板按上游、按模型、按调用方三个维度看每分钟的请求量和错误率。4.5 与开源生态的对接OpenAI SDK直接用网关提供的是OpenAI兼容接口所以官方SDK可以直接切换base_url使用无需改业务代码。用OpenAI Python SDK举例from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keysk-your-sub-key, ) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}], )这里子Key用了sk-前缀是为了兼容SDK的校验逻辑。虽然网关内部不检查前缀但加上能避免某些SDK在本地就拦截请求这个小坑值得留意。值得注意的是如果你的调用方是Codex CLI或各种Agent框架它们的自定义base_url配置方式大多也兼容这种做法这就能让整个团队的AI工具链都收敛到统一网关上做到全局治理和成本审计。5. 常见问题与排查技巧实录5.1 “provider rejected the request schema or tool payload”真相热词里有一条很眼熟error: llm request failed: provider rejected the request schema or tool payload。这个报错我在开发阶段见过几百次基本都是同一个原因请求里的tools参数格式不兼容目标上游。OpenAI的functions格式和Anthropic的tool格式在参数名和结构上都不一致如果网关原样透传Anthropic的API就会直接reject。排查这类问题我建议先做最小化对比将请求里的tools字段删掉看能否正常访问。如果能正常通过说明问题就在工具定义上需要对自己的适配器增加一次递归字段转换而不只是简单替换名字。例如OpenAI的function.parameters是JSON SchemaAnthropic的input_schema也是JSON Schema两者结构基本等同但OpenAI的parameters字段名就要改成input_schema。顺带提一句另一个高频报错是llm request timed out...这几乎都是没有正确设置超时时间导致的。我在llm-proxy-tk里默认给非流式请求设置了60秒的超时流式请求完全不设置超时timeoutNone因为模型确实可能思考很久。如果你在业务侧遇到超时先分清是网关向上游请求超时还是SDK向网关请求超时再针对性修改不同层的timeout配置。5.2 熔断器的参数怎么调才不误伤熔断器参数设置不当会带来两个相反的问题阈值太小上游偶发抖动就直接熔断用户开始抱怨怎么模型经常不可用阈值太大上游真的挂了还继续往里灌请求降级等于没做。我经过较长周期调参后给出一组相对稳妥的初始值参数建议值说明滑动窗口大小30秒过小容易误判过大反应迟钝最小请求数5次请求太少时不做熔断判断避免样本不足错误率阈值60%低于60%时只是降级告警不切上游熔断恢复时间10秒半开探测的时间间隔这组参数的逻辑是对于一个被多个业务方共享的网关宁可让部分请求多等一次重试也不要轻易把整个上游摘掉。毕竟上游恢复后的抖动期比完全故障期更长过早熔断会导致来回切换的抖动。5.3 缓存命中后丢失工具调用结果怎么办我早期实现缓存逻辑时踩过一个大坑开启了缓存之后有些Agent场景下工具调用突然失效了。排查发现问题出在缓存Key的维度太粗糙——我只缓存了model messages的哈希但请求里如果带有tools参数会话状态和上下文是完全不同的。一个带工具的请求和一个纯文本请求即使messages前缀一样结果也不该复用。修复方案很简单缓存Key必须包含model、messages、以及所有会影响生成结果的参数tools、response_format、temperature等。更保险的做法是含tools参数的请求默认不走精确缓存最多走语义缓存语义缓存本身也要求输入编码向量和输出结果匹配到足够高的相似度才返回。这个经验其实带着一个更通用的启示在网关做缓存千万不要偷懒只用messages拼Key。宁可多付出一点计算缓存Key的成本也不要将错误的结果短路返回。5.4 日志记录中的安全边界最后聊一个很低调但非常重要的模块日志。llm-proxy-tk里我专门加了一个配置文件选项redact_sensitive_log它做的事情就是日志脱敏。默认情况下网关不会把完整请求体打到业务日志里只记原始请求的部分元数据——request_id、api_key_hash、model、prompt_tokens。这个选择的意义在于LLM请求的内容往往非常敏感可能包含业务机密、客户信息、代码片段。一旦网关的日志系统被攻破或者日志被同步到第三方分析平台泄露的就是完整对话内容。对合规要求高的公司来说这是一个致命的红线。我在实际部署时还会在网关前面再加一层标准API网关比如APISIX或Kong做基础的TLS终止和DDoS防护llm-proxy-tk专注处理LLM相关的业务逻辑。这种分层思路也是LLM API Gateway - as - infrastructure的正确打开方式。写在最后几个让我坚持开源这个项目的小感悟做到这里llm-proxy-tk已经能帮我解决绝大多数多模型接入场景的问题了。但我必须坦白它距离一个完美的基础设施还有距离目前还缺少WebSocket形态的AI应用代理能力语义缓存的embedding模型也需要用户自带多租户的精细化配额策略还在迭代。这些问题我都列在项目的Roadmap里也欢迎更多人来提Issue、提交PR。开源这个项目后我收到最多的留言不是你的代码写得有多好而是原来我这个乱七八糟的多模型接入问题真的有人遇到过。这正是我把它开源出来的初衷——应用开发者不该被上游模型的碎片化细节反复摩擦网关层把这些复杂性收拢大家才能有更多时间做真正有价值的业务逻辑。如果你正在搭建自己的AI应用我建议动手前认真想想要不要自己维护一堆直接对接各家SDK的胶水代码还是花一天部署一个网关层我的答案已经写在项目里了。最后补一条小经验无论用不用llm-proxy-tk我都建议你在项目初期就规划好模型调用的三件套——统一接口、密钥托管、成本监控。这三点在一开始就做好后面随着业务体量增长会省下巨量的返工成本。真等团队到几十人、每天几十万次模型调用时再补这些基础设施改动成本和风险完全是另一个量级。