1. 企业大模型网关到底解决什么问题1.1 从一个真实的翻车现场说起去年帮一家做 SaaS 的团队做架构评审他们内部已经有 6 个业务线在调用大模型能力结果我一看账单和日志头皮发麻。市场部用 A 家的接口做文案生成客服团队用 B 家的接口做意图识别研发自己又搭了一套 C 家的调用封装三套密钥散落在不同的配置文件里有的甚至硬编码在前端。更离谱的是某条业务线因为没做限流一次批量任务把当月预算烧掉了四成等到财务对账才发现。这不是个例。任何一家把大模型真正用起来的公司走到一定阶段都会撞上同一堵墙调用入口太散、密钥管理失控、成本不可见、模型切换成本高、合规审计无从下手。企业大模型网关就是在这个背景下被推上台面的东西。说白了网关就是所有大模型调用的统一收口层。业务方不再直接对接 OpenAI、Anthropic 或者国内各家厂商的 API而是统一打到网关由网关负责鉴权、路由、限流、计费、日志、缓存、降级。它跟你熟悉的 API Gateway 在思路上是一脉相承的只不过处理的是 token 流、模型路由和 prompt 治理这些新问题。1.2 网关的核心能力清单我把一个合格的企业级大模型网关应该具备的能力拆成下面几块你可以拿这个清单去对照市面上的方案能力模块具体职责不做会怎样统一接入屏蔽各家 API 差异对外暴露 OpenAI 兼容协议每接一家模型就要改一次业务代码密钥托管上游密钥集中管理业务方拿的是网关签发的虚拟 key密钥泄露、离职带走、无法追溯路由调度按模型、成本、延迟、可用性动态选路单点故障一家挂了全线崩限流配额按团队/项目/用户维度做 QPS 和 token 配额预算失控被单个业务拖垮可观测全链路日志、token 统计、成本归因出问题查不到账单说不清缓存与降级相同请求命中缓存上游故障时切备用模型重复烧钱故障时无兜底内容治理敏感词过滤、prompt 审计、输出合规检查合规风险审计过不了这张表里统一接入和密钥托管是地基路由调度和限流配额是省钱和保命的关键可观测是后面一切优化的前提。很多团队一上来就想做智能路由、做语义缓存结果连基础的日志都没打通纯属空中楼阁。1.3 为什么是现在为什么必须做有人会问我业务量不大直接调官方 API 不香吗短期确实香但你要想清楚两件事。第一模型迭代速度已经超过了业务代码的迭代速度。今天 GPT 系列性价比高明天可能某个开源模型在特定任务上更划算后天某家厂商降价一半。如果你的业务代码里到处是openai.ChatCompletion.create每次换模型都是一次伤筋动骨的改造。网关把这层变化隔离掉了业务方只认网关的虚拟模型名背后换谁用户无感。第二成本必须被度量才能被优化。我见过太多团队问他们一个月大模型花了多少钱答不上来问哪个功能最烧钱也答不上来。网关的 token 统计和成本归因能力是精细化运营的起点。没有度量所有的降本都是拍脑袋。所以我的判断是只要你的公司有超过 2 个业务线在用大模型或者月调用量超过百万 token就该认真考虑网关这件事了。再晚技术债会以你想象不到的速度累积。2. 网关架构设计与技术选型拆解2.1 整体分层架构我推荐的分层是这样的从上到下依次是接入层、治理层、适配层、上游层接入层负责协议转换和鉴权。对外统一暴露 OpenAI 兼容的/v1/chat/completions、/v1/embeddings这些端点业务方用任何 OpenAI SDK 都能直接对接迁移成本几乎为零。鉴权用网关自己签发的虚拟 key格式可以设计成sk-gw-前缀方便识别和审计。治理层是网关的大脑包含路由、限流、缓存、计费、审计这些模块。这一层是纯业务逻辑跟具体哪家模型无关所以可以做得非常通用。适配层负责把统一的内部请求格式翻译成各家上游的格式。OpenAI 的格式基本成了事实标准所以适配层主要是处理那些不完全兼容的厂商比如某些厂商的 function calling 参数名不一样或者流式返回的 chunk 结构有差异。上游层就是各家模型服务包括公有云 API、私有化部署的推理服务、以及自建的模型集群。这个分层的好处是每一层可以独立演进。接入层要支持新的鉴权方式不影响治理逻辑治理层要加一个新的路由策略不用动适配代码上游要接一家新厂商只写一个 adapter 就行。2.2 技术栈选型别一上来就上重型框架选型这块我踩过坑说点实在的。市面上有 Portkey、LiteLLM、One API 这些现成方案也有团队选择自研。我的建议是分阶段第一阶段验证期直接用 LiteLLM 或者 One API 这类开源方案快速搭起来。它们已经覆盖了 100 模型的适配OpenAI 兼容协议也做得不错一周内就能跑通。这个阶段的目标是先让调用收口别追求完美。第二阶段成长期业务量上来了开源方案开始不够用比如你需要自定义的路由策略、需要对接内部计费系统、需要特殊的审计规则。这时候可以在开源方案外面包一层自己的治理服务或者基于它的插件机制做扩展。第三阶段成熟期如果调用量到了亿级 token/月性能和安全要求都很高可以考虑用 Go 或 Rust 重写核心链路。我见过用 Rust 写的网关单机 QPS 能到几万P99 延迟控制在个位数毫秒这个量级用 Python 是很难达到的。提示不要为了技术先进性而自研。网关这东西稳定性和生态适配比性能重要得多。开源方案能覆盖 80% 的需求剩下 20% 再自己补性价比最高。2.3 路由策略的设计逻辑路由是网关最有技术含量的部分我把它拆成几个维度按成本路由给每个模型维护一个每千 token 的价格表请求进来时根据 prompt 长度和预期输出长度估算成本优先选便宜的。这个策略适合对延迟不敏感、对成本敏感的批处理任务。按延迟路由维护每个上游的实时延迟指标P50/P95优先选快的。适合交互式场景比如客服对话。按能力路由有些任务需要 function calling有些需要长上下文有些需要多模态。给模型打上能力标签请求里声明需要的能力路由到匹配的模型。按可用性路由实时监控各上游的健康状态某个上游错误率超过阈值就自动摘除流量切到备用。这是保命策略必须有。实际生产里通常是多策略加权。比如先按能力过滤出候选集再在候选集里按成本和延迟加权打分选最高分的。权重可以配置不同业务线用不同的权重。2.4 缓存策略省钱的隐藏大招大模型调用里有相当比例的请求是重复或高度相似的。比如同一个 FAQ 被不同用户问了几十遍或者系统 prompt 完全一样只是用户输入略有差异。精确缓存最简单把请求的 hash 作为 key命中直接返回。适合完全相同的请求命中率不高但实现简单。语义缓存更高级把 prompt 做 embedding在向量库里找相似度超过阈值的缓存结果。这个能显著提升命中率但要注意阈值调优太低会返回不相关的答案太高又命中不了。我一般从 0.95 开始试根据业务反馈调整。Prompt 前缀缓存是另一条路。很多厂商比如 OpenAI对相同前缀的请求有折扣网关可以把系统 prompt 统一管理确保前缀一致享受这个折扣。这个不需要额外存储纯配置就能省一笔。3. 自动化编程与 Agent 的落地实践3.1 Agent 到底是什么跟传统脚本有什么区别热词里 agent 出现频率极高但很多人对它的理解还停留在会调工具的 ChatGPT。我用一句话说清楚Agent 是一个能自主决定下一步做什么、并且能根据执行结果调整后续动作的程序。传统脚本是你把步骤写死A 完了 BB 完了 C。Agent 是你给它一个目标它自己规划步骤执行一步看结果再决定下一步。这个看结果再决定的循环就是 Agent 的核心。跟 Agent 容易混淆的是harness。Harness 是脚手架指的是给模型提供工具、上下文、执行环境的这套框架。Agent 是跑在 harness 上的那个决策逻辑。打个比方harness 是厨房和厨具Agent 是厨师。同一个厨房不同的厨师能做出不同的菜。3.2 CLI 类 Agent 工具的使用要点最近 codex cli、zcode cli 这类命令行 Agent 工具很火它们的价值在于把 Agent 能力直接嵌进开发者的终端工作流。你不用切到网页在终端里就能让 Agent 帮你改代码、跑测试、查文档。以 codex cli 为例安装通常是通过 npmnpm install -g openai/codex装完之后配置 API key一般是通过环境变量export OPENAI_API_KEYsk-...然后就能在项目目录里直接唤起。常用的几个命令我列一下命令作用使用场景/model切换当前使用的模型简单任务用便宜模型复杂任务切强模型/compact压缩对话历史上下文快满了压缩一下继续聊/resume恢复之前的会话昨天没干完的活今天接着干这里有个坑要提醒安装时如果报missing optional dependency openai/codex-win32-x64这类错误通常是平台相关的二进制包没装上。解决办法是先卸载再重装或者手动指定平台包。Windows 上尤其容易遇到因为 npm 的可选依赖机制在某些网络环境下会静默失败。注意CLI Agent 会读取你当前目录的文件也会执行命令。在敏感项目里用之前务必确认它的权限边界最好在独立的沙盒目录里跑。3.3 用网关给 Agent 做统一出口Agent 场景对网关的需求比普通调用更强烈原因有三个第一Agent 的调用量不可预测。一个复杂任务可能触发几十次模型调用如果每个 Agent 实例都直连上游很容易触发限流。网关可以做全局配额把 Agent 的突发流量平滑掉。第二Agent 需要多模型协作。规划用强模型执行用便宜模型判断用快模型。网关的路由能力让 Agent 可以按角色请求不同的虚拟模型名背后自动映射到最合适的实际模型。第三Agent 的成本必须可控。一个失控的 Agent 循环能在几分钟内烧掉几十美元。网关的限流和熔断能在检测到异常调用模式时自动切断这是保命机制。我一般的做法是给每个 Agent 项目分配一个独立的虚拟 key设置日配额和单次会话的 token 上限。超过就拒绝让 Agent 自己处理这个错误。这样即使 Agent 逻辑有 bug损失也是可控的。3.4 Agent 并发扛不住的排查思路AI Agent 怎么扛并发是高频问题我分享一套排查方法。先看瓶颈在哪一层。模型调用层的瓶颈通常是上游的 rate limit这个只能靠多 key 轮询或者多上游分流解决。Agent 逻辑层的瓶颈往往是同步阻塞比如 Agent 在等一个工具返回时把整个线程占住了这时候要改成异步。存储层的瓶颈常见于对话历史每次都全量读写数据库量一大就崩要改成增量存储加缓存。我实测下来一个设计良好的 Agent 服务单实例扛几百并发是没问题的前提是模型调用必须异步、工具调用必须有超时、对话历史必须分页。这三点做到了剩下的就是水平扩容的事。4. 从零搭建的完整实操流程4.1 环境准备与依赖安装假设我们用 LiteLLM 作为网关底座先搭一个最小可用版本。环境要求 Python 3.9 以上建议用虚拟环境隔离python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install litellm[proxy]装完之后核心是一个配置文件config.yaml定义模型列表和路由规则model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY router_settings: routing_strategy: usage-based-routing num_retries: 3 timeout: 30启动命令litellm --config config.yaml --port 4000启动后业务方就可以用 OpenAI SDK 打到http://localhost:4000模型名填gpt-4o或gpt-4o-mini网关会自动路由。4.2 虚拟 Key 与配额配置生产环境必须给每个业务方发独立的虚拟 key。在配置里加上general_settings: master_key: sk-master-xxx database_url: postgresql://... key_management: - key: sk-team-marketing models: [gpt-4o-mini] max_budget: 100 budget_duration: 30d rpm_limit: 500这段配置的意思是市场部只能用gpt-4o-mini30 天预算 100 美元每分钟最多 500 次请求。超了直接拒绝不会影响其他团队。提示master_key是管理密钥权限最大绝对不能下发给业务方。业务方只拿sk-team-开头的虚拟 key。4.3 接入自动化编程工具把 CLI Agent 指向网关只需要改环境变量export OPENAI_BASE_URLhttp://gateway.internal:4000 export OPENAI_API_KEYsk-team-dev这样 Agent 的所有调用都走网关配额、日志、成本统计全部自动生效。我实测下来codex cli 这类工具对 base_url 的支持都很好改一个环境变量就行不用改任何代码。如果 Agent 需要多模型协作可以在网关里定义几个虚拟模型名比如planner、executor、judge分别映射到不同的实际模型。Agent 代码里按角色请求对应的虚拟名路由策略在网关侧统一管理业务代码完全不用关心背后是谁。4.4 可观测性配置日志和指标是网关的眼睛。LiteLLM 支持把日志推到多种后端我一般用 Postgres 存结构化日志用 Prometheus 暴露指标litellm_settings: success_callback: [postgres] failure_callback: [postgres] cache: true cache_params: type: redis host: redis.internal port: 6379关键指标要盯这几个每模型的请求量、token 消耗、P95 延迟、错误率、缓存命中率。这几个指标一上监控大盘很多问题会自己浮出来。比如某个模型的错误率突然飙升多半是上游出问题了缓存命中率突然下降可能是 prompt 变了导致缓存失效。5. 常见问题与排查技巧实录5.1 高频问题速查表现象可能原因排查方向调用返回 401虚拟 key 无效或过期检查 key 是否被禁用、预算是否耗尽调用返回 429触发限流看是网关限流还是上游限流前者调配额后者加 key延迟突然变高上游抖动或路由到了慢模型看各上游的延迟指标检查路由策略成本异常增长缓存失效或 Agent 死循环看缓存命中率看单 key 的调用量曲线流式返回中断网络问题或上游超时检查网关到上游的网络调大 timeoutAgent 卡住不动工具调用没设超时给所有工具调用加超时和重试5.2 几个我踩过的坑坑一缓存把不该缓存的请求缓存了。有些请求带随机数或者时间戳本来就不该命中缓存结果因为 key 设计不当反而污染了缓存。解决办法是在缓存 key 里排除这些字段或者对这类请求直接跳过缓存。坑二重试放大了故障。上游抖动时网关自动重试结果重试的流量把上游压得更死。后来我把重试策略改成指数退避加熔断连续失败到阈值就停止重试直接返回降级结果。坑三日志把敏感信息记下来了。用户的 prompt 里可能有手机号、身份证号直接落库是合规风险。后来在网关里加了一层脱敏正则匹配敏感字段做掩码才敢开全量日志。坑四虚拟 key 没有轮换机制。有个团队的虚拟 key 泄露了因为从来没轮换过被人薅了半个月才发现。现在我的做法是虚拟 key 强制 90 天轮换快到期时自动通知业务方更新。5.3 性能调优的几个实操技巧连接池要调大。网关到上游是 HTTP 长连接默认连接池往往不够用高并发时会排队。我一般把连接池调到 200 以上具体看并发量。异步要彻底。Python 网关如果用同步框架并发上不去。用 FastAPI 这类异步框架配合 httpx 的异步客户端单机能扛的并发能翻好几倍。缓存要分层。本地内存缓存挡第一层Redis 挡第二层数据库兜底。本地缓存命中时延迟几乎为零能挡掉大量重复请求。批量请求要合并。有些场景是短时间内大量小请求可以攒一批一起发减少往返次数。这个对 embedding 场景特别有效。6. 安全与合规的底线6.1 Agent 安全的三条红线Agent 能执行命令、能读写文件安全边界必须划清楚。我的三条红线是第一最小权限。Agent 能访问的目录、能调用的工具都要显式声明默认拒绝。不要给它整个文件系统的读写权限。第二操作审计。Agent 的每一次工具调用都要记录包括调了什么、参数是什么、结果是什么。出问题能追溯。第三危险操作二次确认。删除文件、执行 shell 命令、访问网络这些操作要么禁止要么需要人工确认。我见过 Agent 误删生产数据库的案例血的教训。6.2 数据合规的注意事项大模型调用涉及数据出境、隐私保护这些合规问题网关是天然的管控点。我的做法是数据分级把请求按敏感程度分级高敏感数据只允许走私有化部署的模型不允许出境。脱敏前置在网关入口做脱敏敏感字段掩码后再发给上游。审计留痕所有请求的元数据谁、什么时候、调了什么模型、多少 token必须留存保留期按合规要求设置。供应商评估接入任何上游之前确认它的数据处理条款符合你的合规要求。这些不是技术问题是流程问题但必须在网关设计阶段就考虑进去事后补很痛苦。7. 我个人的一些实践体会搭网关这件事我最大的体会是别追求一步到位。我见过太多团队一开始就想做一个大而全的平台结果半年过去了还在设计阶段业务方等不及又各自直连了最后网关成了摆设。正确的节奏是先用开源方案一周内把调用收口让业务方感受到统一入口的便利然后逐步加限流、加日志、加缓存每加一个能力都让业务方看到实实在在的好处比如账单降了、故障少了最后再考虑智能路由、语义缓存这些高级能力。还有一个体会是网关的运维比开发更重要。网关是所有调用的必经之路它挂了全线都挂。所以高可用、监控告警、灰度发布这些运维能力要在设计阶段就当成一等公民而不是上线后再补。最后分享一个小技巧给网关加一个影子模式。新路由策略上线前先让流量同时走新旧两条路对比结果和成本确认没问题再切。这个能避免很多线上事故我每次改路由策略都会用。这套东西后续还能往几个方向扩展一是接入更多类型的模型比如语音、图像、视频二是把 Agent 的编排能力也收进网关做成统一的 Agent 运行时三是和内部的成本中心打通做到实时的成本归因和预算预警。每一步都不难难的是坚持把基础打牢。 
长河君 · 2026/10/5 12:04:00 · 阅读 1.2k 企业大模型网关架构设计与Agent落地实践指南
1. 企业大模型网关到底解决什么问题1.1 从一个真实的翻车现场说起去年帮一家做 SaaS 的团队做架构评审他们内部已经有 6 个业务线在调用大模型能力结果我一看账单和日志头皮发麻。市场部用 A 家的接口做文案生成客服团队用 B 家的接口做意图识别研发自己又搭了一套 C 家的调用封装三套密钥散落在不同的配置文件里有的甚至硬编码在前端。更离谱的是某条业务线因为没做限流一次批量任务把当月预算烧掉了四成等到财务对账才发现。这不是个例。任何一家把大模型真正用起来的公司走到一定阶段都会撞上同一堵墙调用入口太散、密钥管理失控、成本不可见、模型切换成本高、合规审计无从下手。企业大模型网关就是在这个背景下被推上台面的东西。说白了网关就是所有大模型调用的统一收口层。业务方不再直接对接 OpenAI、Anthropic 或者国内各家厂商的 API而是统一打到网关由网关负责鉴权、路由、限流、计费、日志、缓存、降级。它跟你熟悉的 API Gateway 在思路上是一脉相承的只不过处理的是 token 流、模型路由和 prompt 治理这些新问题。1.2 网关的核心能力清单我把一个合格的企业级大模型网关应该具备的能力拆成下面几块你可以拿这个清单去对照市面上的方案能力模块具体职责不做会怎样统一接入屏蔽各家 API 差异对外暴露 OpenAI 兼容协议每接一家模型就要改一次业务代码密钥托管上游密钥集中管理业务方拿的是网关签发的虚拟 key密钥泄露、离职带走、无法追溯路由调度按模型、成本、延迟、可用性动态选路单点故障一家挂了全线崩限流配额按团队/项目/用户维度做 QPS 和 token 配额预算失控被单个业务拖垮可观测全链路日志、token 统计、成本归因出问题查不到账单说不清缓存与降级相同请求命中缓存上游故障时切备用模型重复烧钱故障时无兜底内容治理敏感词过滤、prompt 审计、输出合规检查合规风险审计过不了这张表里统一接入和密钥托管是地基路由调度和限流配额是省钱和保命的关键可观测是后面一切优化的前提。很多团队一上来就想做智能路由、做语义缓存结果连基础的日志都没打通纯属空中楼阁。1.3 为什么是现在为什么必须做有人会问我业务量不大直接调官方 API 不香吗短期确实香但你要想清楚两件事。第一模型迭代速度已经超过了业务代码的迭代速度。今天 GPT 系列性价比高明天可能某个开源模型在特定任务上更划算后天某家厂商降价一半。如果你的业务代码里到处是openai.ChatCompletion.create每次换模型都是一次伤筋动骨的改造。网关把这层变化隔离掉了业务方只认网关的虚拟模型名背后换谁用户无感。第二成本必须被度量才能被优化。我见过太多团队问他们一个月大模型花了多少钱答不上来问哪个功能最烧钱也答不上来。网关的 token 统计和成本归因能力是精细化运营的起点。没有度量所有的降本都是拍脑袋。所以我的判断是只要你的公司有超过 2 个业务线在用大模型或者月调用量超过百万 token就该认真考虑网关这件事了。再晚技术债会以你想象不到的速度累积。2. 网关架构设计与技术选型拆解2.1 整体分层架构我推荐的分层是这样的从上到下依次是接入层、治理层、适配层、上游层接入层负责协议转换和鉴权。对外统一暴露 OpenAI 兼容的/v1/chat/completions、/v1/embeddings这些端点业务方用任何 OpenAI SDK 都能直接对接迁移成本几乎为零。鉴权用网关自己签发的虚拟 key格式可以设计成sk-gw-前缀方便识别和审计。治理层是网关的大脑包含路由、限流、缓存、计费、审计这些模块。这一层是纯业务逻辑跟具体哪家模型无关所以可以做得非常通用。适配层负责把统一的内部请求格式翻译成各家上游的格式。OpenAI 的格式基本成了事实标准所以适配层主要是处理那些不完全兼容的厂商比如某些厂商的 function calling 参数名不一样或者流式返回的 chunk 结构有差异。上游层就是各家模型服务包括公有云 API、私有化部署的推理服务、以及自建的模型集群。这个分层的好处是每一层可以独立演进。接入层要支持新的鉴权方式不影响治理逻辑治理层要加一个新的路由策略不用动适配代码上游要接一家新厂商只写一个 adapter 就行。2.2 技术栈选型别一上来就上重型框架选型这块我踩过坑说点实在的。市面上有 Portkey、LiteLLM、One API 这些现成方案也有团队选择自研。我的建议是分阶段第一阶段验证期直接用 LiteLLM 或者 One API 这类开源方案快速搭起来。它们已经覆盖了 100 模型的适配OpenAI 兼容协议也做得不错一周内就能跑通。这个阶段的目标是先让调用收口别追求完美。第二阶段成长期业务量上来了开源方案开始不够用比如你需要自定义的路由策略、需要对接内部计费系统、需要特殊的审计规则。这时候可以在开源方案外面包一层自己的治理服务或者基于它的插件机制做扩展。第三阶段成熟期如果调用量到了亿级 token/月性能和安全要求都很高可以考虑用 Go 或 Rust 重写核心链路。我见过用 Rust 写的网关单机 QPS 能到几万P99 延迟控制在个位数毫秒这个量级用 Python 是很难达到的。提示不要为了技术先进性而自研。网关这东西稳定性和生态适配比性能重要得多。开源方案能覆盖 80% 的需求剩下 20% 再自己补性价比最高。2.3 路由策略的设计逻辑路由是网关最有技术含量的部分我把它拆成几个维度按成本路由给每个模型维护一个每千 token 的价格表请求进来时根据 prompt 长度和预期输出长度估算成本优先选便宜的。这个策略适合对延迟不敏感、对成本敏感的批处理任务。按延迟路由维护每个上游的实时延迟指标P50/P95优先选快的。适合交互式场景比如客服对话。按能力路由有些任务需要 function calling有些需要长上下文有些需要多模态。给模型打上能力标签请求里声明需要的能力路由到匹配的模型。按可用性路由实时监控各上游的健康状态某个上游错误率超过阈值就自动摘除流量切到备用。这是保命策略必须有。实际生产里通常是多策略加权。比如先按能力过滤出候选集再在候选集里按成本和延迟加权打分选最高分的。权重可以配置不同业务线用不同的权重。2.4 缓存策略省钱的隐藏大招大模型调用里有相当比例的请求是重复或高度相似的。比如同一个 FAQ 被不同用户问了几十遍或者系统 prompt 完全一样只是用户输入略有差异。精确缓存最简单把请求的 hash 作为 key命中直接返回。适合完全相同的请求命中率不高但实现简单。语义缓存更高级把 prompt 做 embedding在向量库里找相似度超过阈值的缓存结果。这个能显著提升命中率但要注意阈值调优太低会返回不相关的答案太高又命中不了。我一般从 0.95 开始试根据业务反馈调整。Prompt 前缀缓存是另一条路。很多厂商比如 OpenAI对相同前缀的请求有折扣网关可以把系统 prompt 统一管理确保前缀一致享受这个折扣。这个不需要额外存储纯配置就能省一笔。3. 自动化编程与 Agent 的落地实践3.1 Agent 到底是什么跟传统脚本有什么区别热词里 agent 出现频率极高但很多人对它的理解还停留在会调工具的 ChatGPT。我用一句话说清楚Agent 是一个能自主决定下一步做什么、并且能根据执行结果调整后续动作的程序。传统脚本是你把步骤写死A 完了 BB 完了 C。Agent 是你给它一个目标它自己规划步骤执行一步看结果再决定下一步。这个看结果再决定的循环就是 Agent 的核心。跟 Agent 容易混淆的是harness。Harness 是脚手架指的是给模型提供工具、上下文、执行环境的这套框架。Agent 是跑在 harness 上的那个决策逻辑。打个比方harness 是厨房和厨具Agent 是厨师。同一个厨房不同的厨师能做出不同的菜。3.2 CLI 类 Agent 工具的使用要点最近 codex cli、zcode cli 这类命令行 Agent 工具很火它们的价值在于把 Agent 能力直接嵌进开发者的终端工作流。你不用切到网页在终端里就能让 Agent 帮你改代码、跑测试、查文档。以 codex cli 为例安装通常是通过 npmnpm install -g openai/codex装完之后配置 API key一般是通过环境变量export OPENAI_API_KEYsk-...然后就能在项目目录里直接唤起。常用的几个命令我列一下命令作用使用场景/model切换当前使用的模型简单任务用便宜模型复杂任务切强模型/compact压缩对话历史上下文快满了压缩一下继续聊/resume恢复之前的会话昨天没干完的活今天接着干这里有个坑要提醒安装时如果报missing optional dependency openai/codex-win32-x64这类错误通常是平台相关的二进制包没装上。解决办法是先卸载再重装或者手动指定平台包。Windows 上尤其容易遇到因为 npm 的可选依赖机制在某些网络环境下会静默失败。注意CLI Agent 会读取你当前目录的文件也会执行命令。在敏感项目里用之前务必确认它的权限边界最好在独立的沙盒目录里跑。3.3 用网关给 Agent 做统一出口Agent 场景对网关的需求比普通调用更强烈原因有三个第一Agent 的调用量不可预测。一个复杂任务可能触发几十次模型调用如果每个 Agent 实例都直连上游很容易触发限流。网关可以做全局配额把 Agent 的突发流量平滑掉。第二Agent 需要多模型协作。规划用强模型执行用便宜模型判断用快模型。网关的路由能力让 Agent 可以按角色请求不同的虚拟模型名背后自动映射到最合适的实际模型。第三Agent 的成本必须可控。一个失控的 Agent 循环能在几分钟内烧掉几十美元。网关的限流和熔断能在检测到异常调用模式时自动切断这是保命机制。我一般的做法是给每个 Agent 项目分配一个独立的虚拟 key设置日配额和单次会话的 token 上限。超过就拒绝让 Agent 自己处理这个错误。这样即使 Agent 逻辑有 bug损失也是可控的。3.4 Agent 并发扛不住的排查思路AI Agent 怎么扛并发是高频问题我分享一套排查方法。先看瓶颈在哪一层。模型调用层的瓶颈通常是上游的 rate limit这个只能靠多 key 轮询或者多上游分流解决。Agent 逻辑层的瓶颈往往是同步阻塞比如 Agent 在等一个工具返回时把整个线程占住了这时候要改成异步。存储层的瓶颈常见于对话历史每次都全量读写数据库量一大就崩要改成增量存储加缓存。我实测下来一个设计良好的 Agent 服务单实例扛几百并发是没问题的前提是模型调用必须异步、工具调用必须有超时、对话历史必须分页。这三点做到了剩下的就是水平扩容的事。4. 从零搭建的完整实操流程4.1 环境准备与依赖安装假设我们用 LiteLLM 作为网关底座先搭一个最小可用版本。环境要求 Python 3.9 以上建议用虚拟环境隔离python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install litellm[proxy]装完之后核心是一个配置文件config.yaml定义模型列表和路由规则model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY router_settings: routing_strategy: usage-based-routing num_retries: 3 timeout: 30启动命令litellm --config config.yaml --port 4000启动后业务方就可以用 OpenAI SDK 打到http://localhost:4000模型名填gpt-4o或gpt-4o-mini网关会自动路由。4.2 虚拟 Key 与配额配置生产环境必须给每个业务方发独立的虚拟 key。在配置里加上general_settings: master_key: sk-master-xxx database_url: postgresql://... key_management: - key: sk-team-marketing models: [gpt-4o-mini] max_budget: 100 budget_duration: 30d rpm_limit: 500这段配置的意思是市场部只能用gpt-4o-mini30 天预算 100 美元每分钟最多 500 次请求。超了直接拒绝不会影响其他团队。提示master_key是管理密钥权限最大绝对不能下发给业务方。业务方只拿sk-team-开头的虚拟 key。4.3 接入自动化编程工具把 CLI Agent 指向网关只需要改环境变量export OPENAI_BASE_URLhttp://gateway.internal:4000 export OPENAI_API_KEYsk-team-dev这样 Agent 的所有调用都走网关配额、日志、成本统计全部自动生效。我实测下来codex cli 这类工具对 base_url 的支持都很好改一个环境变量就行不用改任何代码。如果 Agent 需要多模型协作可以在网关里定义几个虚拟模型名比如planner、executor、judge分别映射到不同的实际模型。Agent 代码里按角色请求对应的虚拟名路由策略在网关侧统一管理业务代码完全不用关心背后是谁。4.4 可观测性配置日志和指标是网关的眼睛。LiteLLM 支持把日志推到多种后端我一般用 Postgres 存结构化日志用 Prometheus 暴露指标litellm_settings: success_callback: [postgres] failure_callback: [postgres] cache: true cache_params: type: redis host: redis.internal port: 6379关键指标要盯这几个每模型的请求量、token 消耗、P95 延迟、错误率、缓存命中率。这几个指标一上监控大盘很多问题会自己浮出来。比如某个模型的错误率突然飙升多半是上游出问题了缓存命中率突然下降可能是 prompt 变了导致缓存失效。5. 常见问题与排查技巧实录5.1 高频问题速查表现象可能原因排查方向调用返回 401虚拟 key 无效或过期检查 key 是否被禁用、预算是否耗尽调用返回 429触发限流看是网关限流还是上游限流前者调配额后者加 key延迟突然变高上游抖动或路由到了慢模型看各上游的延迟指标检查路由策略成本异常增长缓存失效或 Agent 死循环看缓存命中率看单 key 的调用量曲线流式返回中断网络问题或上游超时检查网关到上游的网络调大 timeoutAgent 卡住不动工具调用没设超时给所有工具调用加超时和重试5.2 几个我踩过的坑坑一缓存把不该缓存的请求缓存了。有些请求带随机数或者时间戳本来就不该命中缓存结果因为 key 设计不当反而污染了缓存。解决办法是在缓存 key 里排除这些字段或者对这类请求直接跳过缓存。坑二重试放大了故障。上游抖动时网关自动重试结果重试的流量把上游压得更死。后来我把重试策略改成指数退避加熔断连续失败到阈值就停止重试直接返回降级结果。坑三日志把敏感信息记下来了。用户的 prompt 里可能有手机号、身份证号直接落库是合规风险。后来在网关里加了一层脱敏正则匹配敏感字段做掩码才敢开全量日志。坑四虚拟 key 没有轮换机制。有个团队的虚拟 key 泄露了因为从来没轮换过被人薅了半个月才发现。现在我的做法是虚拟 key 强制 90 天轮换快到期时自动通知业务方更新。5.3 性能调优的几个实操技巧连接池要调大。网关到上游是 HTTP 长连接默认连接池往往不够用高并发时会排队。我一般把连接池调到 200 以上具体看并发量。异步要彻底。Python 网关如果用同步框架并发上不去。用 FastAPI 这类异步框架配合 httpx 的异步客户端单机能扛的并发能翻好几倍。缓存要分层。本地内存缓存挡第一层Redis 挡第二层数据库兜底。本地缓存命中时延迟几乎为零能挡掉大量重复请求。批量请求要合并。有些场景是短时间内大量小请求可以攒一批一起发减少往返次数。这个对 embedding 场景特别有效。6. 安全与合规的底线6.1 Agent 安全的三条红线Agent 能执行命令、能读写文件安全边界必须划清楚。我的三条红线是第一最小权限。Agent 能访问的目录、能调用的工具都要显式声明默认拒绝。不要给它整个文件系统的读写权限。第二操作审计。Agent 的每一次工具调用都要记录包括调了什么、参数是什么、结果是什么。出问题能追溯。第三危险操作二次确认。删除文件、执行 shell 命令、访问网络这些操作要么禁止要么需要人工确认。我见过 Agent 误删生产数据库的案例血的教训。6.2 数据合规的注意事项大模型调用涉及数据出境、隐私保护这些合规问题网关是天然的管控点。我的做法是数据分级把请求按敏感程度分级高敏感数据只允许走私有化部署的模型不允许出境。脱敏前置在网关入口做脱敏敏感字段掩码后再发给上游。审计留痕所有请求的元数据谁、什么时候、调了什么模型、多少 token必须留存保留期按合规要求设置。供应商评估接入任何上游之前确认它的数据处理条款符合你的合规要求。这些不是技术问题是流程问题但必须在网关设计阶段就考虑进去事后补很痛苦。7. 我个人的一些实践体会搭网关这件事我最大的体会是别追求一步到位。我见过太多团队一开始就想做一个大而全的平台结果半年过去了还在设计阶段业务方等不及又各自直连了最后网关成了摆设。正确的节奏是先用开源方案一周内把调用收口让业务方感受到统一入口的便利然后逐步加限流、加日志、加缓存每加一个能力都让业务方看到实实在在的好处比如账单降了、故障少了最后再考虑智能路由、语义缓存这些高级能力。还有一个体会是网关的运维比开发更重要。网关是所有调用的必经之路它挂了全线都挂。所以高可用、监控告警、灰度发布这些运维能力要在设计阶段就当成一等公民而不是上线后再补。最后分享一个小技巧给网关加一个影子模式。新路由策略上线前先让流量同时走新旧两条路对比结果和成本确认没问题再切。这个能避免很多线上事故我每次改路由策略都会用。这套东西后续还能往几个方向扩展一是接入更多类型的模型比如语音、图像、视频二是把 Agent 的编排能力也收进网关做成统一的 Agent 运行时三是和内部的成本中心打通做到实时的成本归因和预算预警。每一步都不难难的是坚持把基础打牢。