企业里做大模型落地最容易被低估的一环不是模型选型而是网关。我见过太多团队一开始直接让业务代码裸调各家 API等到要换模型、要限流、要审计、要计费的时候才发现改一处牵动全身。这篇就围绕大模型网关和自动化编程这两条线把从基础搭建到真正落地的完整路径讲清楚包括 Agent、CLI、API 这几个关键词背后的实际工程含义。不管你是刚接触这块的开发者还是已经在做企业内部 AI 平台的负责人都能从里面找到可以直接抄作业的部分。1. 为什么企业一定要有大模型网关这层1.1 裸调 API 的三个致命问题先说清楚网关到底解决什么问题。很多团队初期为了快业务代码里直接写openai.ChatCompletion.create(...)或者requests.post(https://api.xxx.com/v1/chat/completions, ...)跑起来确实没问题。但只要规模稍微上来三个问题必然暴露。第一个是密钥扩散。每个调用方都持有真实 API Key一旦某个服务被入侵或者日志打印了请求头密钥就泄露了。企业里几十个服务共用一套密钥出了事根本查不到是谁泄露的。第二个是模型切换成本。今天用 A 家的模型明天老板说 B 家便宜一半要换你得改所有业务代码。不同厂商的请求体格式、鉴权方式、流式返回格式都不一样改起来是灾难。第三个是可观测性缺失。谁在调、调了多少次、花了多少钱、响应多慢、有没有报错这些数据散落在各个服务里根本没法统一统计。等到财务问这个月 AI 花了多少钱你只能干瞪眼。网关这层就是把这些横切关注点全部收拢到一个统一入口。业务方只需要知道网关地址和一个内部 token剩下的鉴权、路由、限流、计费、日志全在网关内部完成。1.2 网关的核心能力清单一个能上生产的大模型网关至少要具备下面这些能力我按优先级排一下能力优先级说明统一鉴权P0内部 token 换真实密钥密钥不出网关多模型路由P0按模型名/策略转发到不同厂商流式转发P0SSE 透传不能破坏流式体验限流限速P1按用户/应用/模型维度限流用量计费P1token 统计、成本核算日志审计P1请求响应留痕可追溯失败重试与降级P2主模型挂了自动切备用缓存P2相同请求命中缓存省钱这里要特别强调流式转发。大模型的响应是 SSEServer-Sent Events流式返回的网关如果处理不当比如先把整个响应读完再返回用户就会看到卡半天然后一次性蹦出来体验直接崩掉。正确的做法是边收边转发用流式管道处理。1.3 网关的部署形态选择网关部署形态主要有三种各有适用场景进程内 SDK 模式把网关逻辑做成一个库业务直接引入。优点是零网络开销缺点是每个语言都要实现一遍且升级困难。独立服务模式网关是一个独立部署的服务业务通过 HTTP 调用。这是最主流的做法语言无关升级方便。Sidecar 模式每个业务 Pod 旁边挂一个网关容器。适合 K8s 环境隔离性好但资源开销大。对绝大多数企业我推荐独立服务模式。用 Go 或 Rust 写性能足够单机扛几千 QPS 没问题。下面给一个用 Go 写的极简网关核心逻辑示意func handleChatCompletion(w http.ResponseWriter, r *http.Request) { // 1. 校验内部 token internalToken : r.Header.Get(X-Internal-Token) app, err : auth.Verify(internalToken) if err ! nil { http.Error(w, unauthorized, 401) return } // 2. 解析请求确定目标模型 var req ChatRequest json.NewDecoder(r.Body).Decode(req) provider : router.Select(req.Model) // 3. 限流检查 if !limiter.Allow(app.ID, req.Model) { http.Error(w, rate limited, 429) return } // 4. 替换为真实密钥转发请求 upstreamReq : buildUpstreamRequest(req, provider.APIKey) resp, err : httpClient.Do(upstreamReq) if err ! nil { // 5. 失败降级到备用模型 resp, err fallback(req, provider) } // 6. 流式透传响应 streamCopy(w, resp.Body) }这段代码看着简单但每一步都有坑。比如第 6 步的streamCopy必须用http.Flusher强制刷新缓冲区否则 Go 的默认缓冲会让流式变成伪流式。提示网关转发时一定要设置合理的超时。大模型首 token 延迟可能到几秒甚至十几秒超时设太短会误杀正常请求设太长又会拖垮连接池。我的经验是首 token 超时 30s整体超时按模型最大输出长度估算。2. 自动化编程里的 Agent 与 CLI 到底怎么配合2.1 Agent 和 CLI 不是一回事这两个词经常被混着用但它们的定位完全不同。Agent 是决策者CLI 是执行者。Agent 负责理解任务、拆解步骤、决定下一步做什么。它本质上是一个循环观察当前状态 → 思考 → 选择动作 → 执行 → 观察结果 → 继续。而 CLI 是 Agent 可以调用的一个具体工具比如git、npm、docker或者专门为 AI 编程设计的命令行工具。打个比方Agent 像是一个项目经理CLI 像是他手下的各种专业工具。项目经理不会自己去拧螺丝而是决定现在该用螺丝刀了然后调用螺丝刀。现在市面上有不少专门给 AI 用的 CLI 工具比如一些代码生成 CLI、文件操作 CLI。它们的共同特点是输入输出结构化、幂等性好、错误信息清晰。这三点是 Agent 能可靠调用它们的前提。2.2 Agent 调用 CLI 的典型循环一个自动化编程 Agent 的完整工作循环大概是这样接收任务比如给这个项目加上单元测试探索环境调用ls、cat、grep等 CLI 了解项目结构制定计划决定先看哪些文件再写哪些测试执行动作调用文件读写 CLI 创建测试文件验证结果调用测试运行 CLI看是否通过修正迭代如果失败读错误信息回到第 4 步这个循环里第 5 步的验证是灵魂。没有验证的 Agent 就是瞎猜有了验证才能自我纠错。这也是为什么好的 Agent 框架都强调工具返回结果要可解析。下面是一个 Agent 调用 CLI 的伪代码结构def agent_loop(task, max_steps20): context [{role: system, content: SYSTEM_PROMPT}] context.append({role: user, content: task}) for step in range(max_steps): # 让模型决定下一步动作 response llm.chat(context, toolsAVAILABLE_TOOLS) if response.is_final: return response.content # 执行模型选择的工具 tool_name response.tool_call.name tool_args response.tool_call.args result execute_tool(tool_name, tool_args) # 把结果喂回上下文 context.append(response.message) context.append({role: tool, content: result}) return 达到最大步数限制这里有个关键细节上下文会越来越长。每轮工具调用都会往 context 里塞内容几十轮下来 token 消耗惊人。所以生产级 Agent 必须做上下文管理比如只保留最近 N 轮、对历史做摘要、把大文件内容截断等。2.3 工具设计的三条铁律给 Agent 设计 CLI 工具时我总结了三条铁律踩过坑的都懂第一输出要精简且结构化。你让 Agent 跑一个ls -la返回几百行带权限、时间、大小的信息模型要花大量 token 去解析。更好的做法是提供一个list_files工具只返回文件名列表。第二错误信息要能指导下一步。工具失败时返回的不该是Error: failed而应该是文件 xxx.py 第 42 行语法错误缺少冒号。模型看到后者才知道怎么修。第三操作要幂等或可回滚。Agent 可能会重复调用同一个工具如果工具不幂等就会产生副作用。比如创建文件应该是覆盖式的而不是追加式的。注意涉及删除、覆盖、执行系统命令的工具一定要加确认机制或沙箱隔离。我见过 Agent 误删整个目录的案例血的教训。3. 把网关和 Agent 串起来一个完整的落地架构3.1 整体架构分层把前面两块拼起来一个企业级的自动化编程平台大概分四层接入层Web 界面、IDE 插件、CI/CD 钩子用户从这里发起任务编排层Agent 运行时负责任务拆解、工具调度、上下文管理网关层统一的大模型网关处理所有 LLM 调用执行层各种 CLI 工具、代码仓库、测试环境这个分层的好处是职责清晰。编排层不关心用的是哪家模型网关层不关心任务是什么执行层不关心谁在调用。任何一层要替换或升级都不影响其他层。3.2 请求的完整生命周期一个帮我修复这个 bug的请求走完整个链路是这样的用户在 IDE 插件里输入任务插件把当前文件内容和任务发给编排层编排层启动 Agent构造初始上下文Agent 调用网关请求模型生成下一步动作网关鉴权、限流、路由到具体模型返回结果Agent 解析出要调用的工具比如读取 test.py执行层执行工具返回文件内容Agent 把结果加入上下文再次调用网关循环直到 Agent 认为任务完成返回最终结果编排层把结果返回给 IDE 插件这个链路里网关是唯一的模型出口所有 token 消耗、延迟、错误都在这里被记录。这对成本控制和问题排查至关重要。3.3 关键配置示例网关的路由配置我一般用 YAML 管理方便运维改providers: - name: primary base_url: https://api.provider-a.com/v1 api_key: ${PROVIDER_A_KEY} models: [gpt-4-class, gpt-3.5-class] timeout: 60s - name: backup base_url: https://api.provider-b.com/v1 api_key: ${PROVIDER_B_KEY} models: [claude-class] timeout: 60s routes: - match: gpt-4-class primary: primary fallback: backup rate_limit: 100/min - match: claude-class primary: backup rate_limit: 50/min billing: currency: CNY rates: gpt-4-class: { input: 0.03, output: 0.06 } # 每千 token claude-class: { input: 0.02, output: 0.04 }这份配置里fallback字段实现了自动降级rate_limit实现了限流billing实现了计费。运维改配置不用动代码重启网关即可生效。4. 实操中真正会踩的坑4.1 上下文长度超限的处理大模型都有上下文窗口限制Agent 跑久了必然超。报错信息通常是这样的API error: 400 This models maximum context length is 1048576 tokens. However, your messages resulted in 1200000 tokens.处理这个问题的策略有三层第一层预防。在往上下文里塞内容前先估算 token 数。大文件不要整个塞进去只塞相关片段。可以用简单的字符数除以 4 来粗估 token 数英文中文大概除以 1.5。第二层压缩。当上下文接近上限时对历史消息做摘要。把前面十几轮的对话压缩成一段总结保留关键决策和结论。第三层截断。实在不行就丢弃最早的几轮但要保留 system prompt 和最近几轮。丢弃时最好保留工具调用的结果摘要而不是直接删。def manage_context(messages, max_tokens100000): total estimate_tokens(messages) if total max_tokens * 0.8: return messages # 保留 system 最近 5 轮 system messages[0] recent messages[-10:] # 中间部分做摘要 middle messages[1:-10] if middle: summary summarize(middle) return [system, {role: system, content: f历史摘要{summary}}] recent return [system] recent4.2 流式响应的中断与重连流式响应最烦人的是中途断掉。网络抖动、模型服务重启、网关超时都可能导致流中断。用户看到的是回答到一半没了。处理方案是在网关层做流式重试。具体做法是网关记录已经转发给客户端的 token 数如果上游断了用相同的 prompt 重新请求但要求模型跳过已发送的部分。不过这个方案实现复杂且不是所有模型都支持。更实用的方案是客户端侧容错。前端检测到流中断后把已收到的内容作为上下文发起一个继续请求。虽然会多花点 token但实现简单可靠。async function streamWithRetry(messages, maxRetries 3) { for (let i 0; i maxRetries; i) { try { const response await fetch(/api/chat, { method: POST, body: JSON.stringify({ messages, stream: true }) }); return await processStream(response); } catch (e) { if (i maxRetries - 1) throw e; // 把已收到的内容加入上下文继续请求 messages.push({ role: assistant, content: partialContent }); messages.push({ role: user, content: 请继续 }); } } }4.3 密钥与权限的常见错误配置网关时密钥相关的错误特别多。最常见的两类第一类环境变量没生效。报错长这样llm-deepseek: no api key for provider route deepseek-official这通常是配置文件里写了${DEEPSEEK_KEY}但环境变量没导出或者导出在了错误的 shell 里。排查方法是在网关启动脚本里加一行env | grep KEY确认。第二类权限范围不匹配。比如某些 API 需要在控制台声明 scope没声明就会报choosemedia:fail api scope is not declared in the privacy agreement这类问题只能去对应平台的控制台检查应用权限配置代码层面无解。提示所有密钥统一用密钥管理服务如 Vault、KMS管理不要写在配置文件或环境变量里。环境变量在容器里容易被docker inspect看到。4.4 Docker 权限问题网关如果用 Docker 部署经常会遇到permission denied while trying to connect to the docker api这是因为当前用户不在 docker 组里。解决方法是sudo usermod -aG docker $USER然后重新登录。但生产环境更推荐用 rootless Docker 或者把网关跑在 K8s 里避免直接暴露 docker socket。5. 性能与成本的优化空间5.1 缓存能省多少钱大模型调用里有相当比例的请求是重复或高度相似的。比如 Agent 反复读取同一个文件、反复问同样的问题。加一层语义缓存命中率能到 20%-40%。缓存分两种精确缓存请求内容完全一致才命中。实现简单用 Redis 存hash(prompt) - response即可。语义缓存请求语义相似就命中。需要向量化 prompt做相似度检索。命中率更高但实现复杂。对大多数场景精确缓存就够了。注意缓存要设置合理的 TTL模型更新后旧缓存要失效。5.2 模型分级路由不是所有请求都需要最强模型。Agent 的很多步骤比如判断文件类型提取函数名用便宜的小模型完全够用。只有关键推理步骤才需要大模型。网关可以按请求的复杂度做分级路由def select_model(request): # 简单任务用小模型 if request.task_type in [classify, extract, format]: return small-model # 复杂推理用大模型 if request.task_type in [reason, plan, debug]: return large-model return medium-model这个策略实测能省 50% 以上的成本而任务成功率几乎不受影响。5.3 并发与连接池网关作为所有请求的入口并发能力是瓶颈。几个关键点HTTP 客户端要复用连接不要每次请求都新建。Go 的http.Client默认就复用但要注意MaxIdleConnsPerHost要调大。上游连接数要限制避免把模型服务打挂。用信号量或连接池控制。流式请求要单独管理因为流式连接占用时间长不能和普通请求共用连接池。transport : http.Transport{ MaxIdleConns: 1000, MaxIdleConnsPerHost: 200, IdleConnTimeout: 90 * time.Second, // 流式请求需要禁用响应缓冲 DisableCompression: false, } client : http.Client{ Transport: transport, Timeout: 0, // 流式请求不设总超时用 context 控制 }6. 从能跑到好用的几个进阶点6.1 可观测性建设网关跑起来后最重要的就是看得见。至少要采集这几类指标指标类型具体指标用途请求量QPS、按模型/应用分组容量规划延迟P50/P95/P99、首 token 延迟体验监控错误错误率、错误类型分布故障排查成本token 消耗、费用成本控制限流触发次数、被限流应用配额调整这些指标用 Prometheus 采集Grafana 展示。首 token 延迟这个指标特别重要它直接决定用户体感但很多团队只监控总延迟忽略了它。6.2 灰度与回滚模型切换、网关升级都要能灰度。做法是给请求打标签按比例分流到新旧版本。比如 10% 流量走新模型观察指标正常后再逐步放大。回滚要能秒级完成。配置化的路由让回滚变成改一行配置的事这是网关架构相比硬编码的最大优势。6.3 Agent 的安全边界Agent 能执行命令、读写文件安全边界必须划清楚文件系统隔离Agent 只能访问指定目录用容器或 chroot 限制命令白名单只允许执行预定义的安全命令禁止rm -rf、curl外网等网络隔离Agent 执行环境不能访问外网防止数据外泄资源限制CPU、内存、执行时间都要设上限防止死循环这些限制在网关层和编排层都要做不能只靠一层。6.4 多租户隔离企业里多个团队共用一套平台隔离是刚需。隔离维度包括配额隔离每个团队有独立的 token 配额和 QPS 上限数据隔离A 团队的对话历史 B 团队看不到密钥隔离每个团队用自己的密钥便于独立计费模型隔离某些高级模型只对特定团队开放这些都在网关的鉴权环节实现通过内部 token 关联到租户信息后续所有操作都带上租户上下文。7. 一些实战中的零碎经验最后分享几个散落但很实用的点。关于 CLI 工具的选择优先选那些有--json输出选项的。文本输出解析起来太脆弱模型稍微换个格式就崩。JSON 输出配合 schema 校验稳定性高一个数量级。关于 Agent 的步数限制不要设太大。我见过设 100 步的结果 Agent 陷入循环烧了几百万 token 才发现。一般任务 20 步足够复杂任务 50 步封顶超了就报错让人介入。关于网关的日志请求和响应内容要脱敏后再存。用户可能在里面输入了敏感信息直接存明文有合规风险。至少要把身份证、手机号、邮箱这类模式做正则替换。关于模型降级降级不是简单换个模型就行。不同模型的输出格式可能不同Agent 的解析逻辑要能兼容。最好在网关层做输出格式归一化让上层感知不到模型差异。关于测试网关和 Agent 都要有 mock 能力。不能每次测试都真调模型又慢又贵。用录制回放的方式把真实响应录下来测试时回放既快又稳定。关于版本管理prompt 也要版本化。Agent 的 system prompt 改一个字行为可能天差地别。把 prompt 纳入 Git 管理每次改动都有记录出问题能快速定位是哪次改动导致的。这套东西我从零搭过两遍第一遍踩了无数坑第二遍就顺多了。核心体会是网关这层越早建越好Agent 的能力越晚放越好。网关是基础设施早建早省心Agent 的能力边界要慢慢放开每放开一个权限都要配套的监控和回滚机制。急着让 Agent 什么都能干最后往往是收拾烂摊子花的时间比省下来的还多。 
长河君 · 2026/10/7 12:39:14 · 阅读 1.2k 企业大模型落地：网关与Agent自动化编程实战指南
企业里做大模型落地最容易被低估的一环不是模型选型而是网关。我见过太多团队一开始直接让业务代码裸调各家 API等到要换模型、要限流、要审计、要计费的时候才发现改一处牵动全身。这篇就围绕大模型网关和自动化编程这两条线把从基础搭建到真正落地的完整路径讲清楚包括 Agent、CLI、API 这几个关键词背后的实际工程含义。不管你是刚接触这块的开发者还是已经在做企业内部 AI 平台的负责人都能从里面找到可以直接抄作业的部分。1. 为什么企业一定要有大模型网关这层1.1 裸调 API 的三个致命问题先说清楚网关到底解决什么问题。很多团队初期为了快业务代码里直接写openai.ChatCompletion.create(...)或者requests.post(https://api.xxx.com/v1/chat/completions, ...)跑起来确实没问题。但只要规模稍微上来三个问题必然暴露。第一个是密钥扩散。每个调用方都持有真实 API Key一旦某个服务被入侵或者日志打印了请求头密钥就泄露了。企业里几十个服务共用一套密钥出了事根本查不到是谁泄露的。第二个是模型切换成本。今天用 A 家的模型明天老板说 B 家便宜一半要换你得改所有业务代码。不同厂商的请求体格式、鉴权方式、流式返回格式都不一样改起来是灾难。第三个是可观测性缺失。谁在调、调了多少次、花了多少钱、响应多慢、有没有报错这些数据散落在各个服务里根本没法统一统计。等到财务问这个月 AI 花了多少钱你只能干瞪眼。网关这层就是把这些横切关注点全部收拢到一个统一入口。业务方只需要知道网关地址和一个内部 token剩下的鉴权、路由、限流、计费、日志全在网关内部完成。1.2 网关的核心能力清单一个能上生产的大模型网关至少要具备下面这些能力我按优先级排一下能力优先级说明统一鉴权P0内部 token 换真实密钥密钥不出网关多模型路由P0按模型名/策略转发到不同厂商流式转发P0SSE 透传不能破坏流式体验限流限速P1按用户/应用/模型维度限流用量计费P1token 统计、成本核算日志审计P1请求响应留痕可追溯失败重试与降级P2主模型挂了自动切备用缓存P2相同请求命中缓存省钱这里要特别强调流式转发。大模型的响应是 SSEServer-Sent Events流式返回的网关如果处理不当比如先把整个响应读完再返回用户就会看到卡半天然后一次性蹦出来体验直接崩掉。正确的做法是边收边转发用流式管道处理。1.3 网关的部署形态选择网关部署形态主要有三种各有适用场景进程内 SDK 模式把网关逻辑做成一个库业务直接引入。优点是零网络开销缺点是每个语言都要实现一遍且升级困难。独立服务模式网关是一个独立部署的服务业务通过 HTTP 调用。这是最主流的做法语言无关升级方便。Sidecar 模式每个业务 Pod 旁边挂一个网关容器。适合 K8s 环境隔离性好但资源开销大。对绝大多数企业我推荐独立服务模式。用 Go 或 Rust 写性能足够单机扛几千 QPS 没问题。下面给一个用 Go 写的极简网关核心逻辑示意func handleChatCompletion(w http.ResponseWriter, r *http.Request) { // 1. 校验内部 token internalToken : r.Header.Get(X-Internal-Token) app, err : auth.Verify(internalToken) if err ! nil { http.Error(w, unauthorized, 401) return } // 2. 解析请求确定目标模型 var req ChatRequest json.NewDecoder(r.Body).Decode(req) provider : router.Select(req.Model) // 3. 限流检查 if !limiter.Allow(app.ID, req.Model) { http.Error(w, rate limited, 429) return } // 4. 替换为真实密钥转发请求 upstreamReq : buildUpstreamRequest(req, provider.APIKey) resp, err : httpClient.Do(upstreamReq) if err ! nil { // 5. 失败降级到备用模型 resp, err fallback(req, provider) } // 6. 流式透传响应 streamCopy(w, resp.Body) }这段代码看着简单但每一步都有坑。比如第 6 步的streamCopy必须用http.Flusher强制刷新缓冲区否则 Go 的默认缓冲会让流式变成伪流式。提示网关转发时一定要设置合理的超时。大模型首 token 延迟可能到几秒甚至十几秒超时设太短会误杀正常请求设太长又会拖垮连接池。我的经验是首 token 超时 30s整体超时按模型最大输出长度估算。2. 自动化编程里的 Agent 与 CLI 到底怎么配合2.1 Agent 和 CLI 不是一回事这两个词经常被混着用但它们的定位完全不同。Agent 是决策者CLI 是执行者。Agent 负责理解任务、拆解步骤、决定下一步做什么。它本质上是一个循环观察当前状态 → 思考 → 选择动作 → 执行 → 观察结果 → 继续。而 CLI 是 Agent 可以调用的一个具体工具比如git、npm、docker或者专门为 AI 编程设计的命令行工具。打个比方Agent 像是一个项目经理CLI 像是他手下的各种专业工具。项目经理不会自己去拧螺丝而是决定现在该用螺丝刀了然后调用螺丝刀。现在市面上有不少专门给 AI 用的 CLI 工具比如一些代码生成 CLI、文件操作 CLI。它们的共同特点是输入输出结构化、幂等性好、错误信息清晰。这三点是 Agent 能可靠调用它们的前提。2.2 Agent 调用 CLI 的典型循环一个自动化编程 Agent 的完整工作循环大概是这样接收任务比如给这个项目加上单元测试探索环境调用ls、cat、grep等 CLI 了解项目结构制定计划决定先看哪些文件再写哪些测试执行动作调用文件读写 CLI 创建测试文件验证结果调用测试运行 CLI看是否通过修正迭代如果失败读错误信息回到第 4 步这个循环里第 5 步的验证是灵魂。没有验证的 Agent 就是瞎猜有了验证才能自我纠错。这也是为什么好的 Agent 框架都强调工具返回结果要可解析。下面是一个 Agent 调用 CLI 的伪代码结构def agent_loop(task, max_steps20): context [{role: system, content: SYSTEM_PROMPT}] context.append({role: user, content: task}) for step in range(max_steps): # 让模型决定下一步动作 response llm.chat(context, toolsAVAILABLE_TOOLS) if response.is_final: return response.content # 执行模型选择的工具 tool_name response.tool_call.name tool_args response.tool_call.args result execute_tool(tool_name, tool_args) # 把结果喂回上下文 context.append(response.message) context.append({role: tool, content: result}) return 达到最大步数限制这里有个关键细节上下文会越来越长。每轮工具调用都会往 context 里塞内容几十轮下来 token 消耗惊人。所以生产级 Agent 必须做上下文管理比如只保留最近 N 轮、对历史做摘要、把大文件内容截断等。2.3 工具设计的三条铁律给 Agent 设计 CLI 工具时我总结了三条铁律踩过坑的都懂第一输出要精简且结构化。你让 Agent 跑一个ls -la返回几百行带权限、时间、大小的信息模型要花大量 token 去解析。更好的做法是提供一个list_files工具只返回文件名列表。第二错误信息要能指导下一步。工具失败时返回的不该是Error: failed而应该是文件 xxx.py 第 42 行语法错误缺少冒号。模型看到后者才知道怎么修。第三操作要幂等或可回滚。Agent 可能会重复调用同一个工具如果工具不幂等就会产生副作用。比如创建文件应该是覆盖式的而不是追加式的。注意涉及删除、覆盖、执行系统命令的工具一定要加确认机制或沙箱隔离。我见过 Agent 误删整个目录的案例血的教训。3. 把网关和 Agent 串起来一个完整的落地架构3.1 整体架构分层把前面两块拼起来一个企业级的自动化编程平台大概分四层接入层Web 界面、IDE 插件、CI/CD 钩子用户从这里发起任务编排层Agent 运行时负责任务拆解、工具调度、上下文管理网关层统一的大模型网关处理所有 LLM 调用执行层各种 CLI 工具、代码仓库、测试环境这个分层的好处是职责清晰。编排层不关心用的是哪家模型网关层不关心任务是什么执行层不关心谁在调用。任何一层要替换或升级都不影响其他层。3.2 请求的完整生命周期一个帮我修复这个 bug的请求走完整个链路是这样的用户在 IDE 插件里输入任务插件把当前文件内容和任务发给编排层编排层启动 Agent构造初始上下文Agent 调用网关请求模型生成下一步动作网关鉴权、限流、路由到具体模型返回结果Agent 解析出要调用的工具比如读取 test.py执行层执行工具返回文件内容Agent 把结果加入上下文再次调用网关循环直到 Agent 认为任务完成返回最终结果编排层把结果返回给 IDE 插件这个链路里网关是唯一的模型出口所有 token 消耗、延迟、错误都在这里被记录。这对成本控制和问题排查至关重要。3.3 关键配置示例网关的路由配置我一般用 YAML 管理方便运维改providers: - name: primary base_url: https://api.provider-a.com/v1 api_key: ${PROVIDER_A_KEY} models: [gpt-4-class, gpt-3.5-class] timeout: 60s - name: backup base_url: https://api.provider-b.com/v1 api_key: ${PROVIDER_B_KEY} models: [claude-class] timeout: 60s routes: - match: gpt-4-class primary: primary fallback: backup rate_limit: 100/min - match: claude-class primary: backup rate_limit: 50/min billing: currency: CNY rates: gpt-4-class: { input: 0.03, output: 0.06 } # 每千 token claude-class: { input: 0.02, output: 0.04 }这份配置里fallback字段实现了自动降级rate_limit实现了限流billing实现了计费。运维改配置不用动代码重启网关即可生效。4. 实操中真正会踩的坑4.1 上下文长度超限的处理大模型都有上下文窗口限制Agent 跑久了必然超。报错信息通常是这样的API error: 400 This models maximum context length is 1048576 tokens. However, your messages resulted in 1200000 tokens.处理这个问题的策略有三层第一层预防。在往上下文里塞内容前先估算 token 数。大文件不要整个塞进去只塞相关片段。可以用简单的字符数除以 4 来粗估 token 数英文中文大概除以 1.5。第二层压缩。当上下文接近上限时对历史消息做摘要。把前面十几轮的对话压缩成一段总结保留关键决策和结论。第三层截断。实在不行就丢弃最早的几轮但要保留 system prompt 和最近几轮。丢弃时最好保留工具调用的结果摘要而不是直接删。def manage_context(messages, max_tokens100000): total estimate_tokens(messages) if total max_tokens * 0.8: return messages # 保留 system 最近 5 轮 system messages[0] recent messages[-10:] # 中间部分做摘要 middle messages[1:-10] if middle: summary summarize(middle) return [system, {role: system, content: f历史摘要{summary}}] recent return [system] recent4.2 流式响应的中断与重连流式响应最烦人的是中途断掉。网络抖动、模型服务重启、网关超时都可能导致流中断。用户看到的是回答到一半没了。处理方案是在网关层做流式重试。具体做法是网关记录已经转发给客户端的 token 数如果上游断了用相同的 prompt 重新请求但要求模型跳过已发送的部分。不过这个方案实现复杂且不是所有模型都支持。更实用的方案是客户端侧容错。前端检测到流中断后把已收到的内容作为上下文发起一个继续请求。虽然会多花点 token但实现简单可靠。async function streamWithRetry(messages, maxRetries 3) { for (let i 0; i maxRetries; i) { try { const response await fetch(/api/chat, { method: POST, body: JSON.stringify({ messages, stream: true }) }); return await processStream(response); } catch (e) { if (i maxRetries - 1) throw e; // 把已收到的内容加入上下文继续请求 messages.push({ role: assistant, content: partialContent }); messages.push({ role: user, content: 请继续 }); } } }4.3 密钥与权限的常见错误配置网关时密钥相关的错误特别多。最常见的两类第一类环境变量没生效。报错长这样llm-deepseek: no api key for provider route deepseek-official这通常是配置文件里写了${DEEPSEEK_KEY}但环境变量没导出或者导出在了错误的 shell 里。排查方法是在网关启动脚本里加一行env | grep KEY确认。第二类权限范围不匹配。比如某些 API 需要在控制台声明 scope没声明就会报choosemedia:fail api scope is not declared in the privacy agreement这类问题只能去对应平台的控制台检查应用权限配置代码层面无解。提示所有密钥统一用密钥管理服务如 Vault、KMS管理不要写在配置文件或环境变量里。环境变量在容器里容易被docker inspect看到。4.4 Docker 权限问题网关如果用 Docker 部署经常会遇到permission denied while trying to connect to the docker api这是因为当前用户不在 docker 组里。解决方法是sudo usermod -aG docker $USER然后重新登录。但生产环境更推荐用 rootless Docker 或者把网关跑在 K8s 里避免直接暴露 docker socket。5. 性能与成本的优化空间5.1 缓存能省多少钱大模型调用里有相当比例的请求是重复或高度相似的。比如 Agent 反复读取同一个文件、反复问同样的问题。加一层语义缓存命中率能到 20%-40%。缓存分两种精确缓存请求内容完全一致才命中。实现简单用 Redis 存hash(prompt) - response即可。语义缓存请求语义相似就命中。需要向量化 prompt做相似度检索。命中率更高但实现复杂。对大多数场景精确缓存就够了。注意缓存要设置合理的 TTL模型更新后旧缓存要失效。5.2 模型分级路由不是所有请求都需要最强模型。Agent 的很多步骤比如判断文件类型提取函数名用便宜的小模型完全够用。只有关键推理步骤才需要大模型。网关可以按请求的复杂度做分级路由def select_model(request): # 简单任务用小模型 if request.task_type in [classify, extract, format]: return small-model # 复杂推理用大模型 if request.task_type in [reason, plan, debug]: return large-model return medium-model这个策略实测能省 50% 以上的成本而任务成功率几乎不受影响。5.3 并发与连接池网关作为所有请求的入口并发能力是瓶颈。几个关键点HTTP 客户端要复用连接不要每次请求都新建。Go 的http.Client默认就复用但要注意MaxIdleConnsPerHost要调大。上游连接数要限制避免把模型服务打挂。用信号量或连接池控制。流式请求要单独管理因为流式连接占用时间长不能和普通请求共用连接池。transport : http.Transport{ MaxIdleConns: 1000, MaxIdleConnsPerHost: 200, IdleConnTimeout: 90 * time.Second, // 流式请求需要禁用响应缓冲 DisableCompression: false, } client : http.Client{ Transport: transport, Timeout: 0, // 流式请求不设总超时用 context 控制 }6. 从能跑到好用的几个进阶点6.1 可观测性建设网关跑起来后最重要的就是看得见。至少要采集这几类指标指标类型具体指标用途请求量QPS、按模型/应用分组容量规划延迟P50/P95/P99、首 token 延迟体验监控错误错误率、错误类型分布故障排查成本token 消耗、费用成本控制限流触发次数、被限流应用配额调整这些指标用 Prometheus 采集Grafana 展示。首 token 延迟这个指标特别重要它直接决定用户体感但很多团队只监控总延迟忽略了它。6.2 灰度与回滚模型切换、网关升级都要能灰度。做法是给请求打标签按比例分流到新旧版本。比如 10% 流量走新模型观察指标正常后再逐步放大。回滚要能秒级完成。配置化的路由让回滚变成改一行配置的事这是网关架构相比硬编码的最大优势。6.3 Agent 的安全边界Agent 能执行命令、读写文件安全边界必须划清楚文件系统隔离Agent 只能访问指定目录用容器或 chroot 限制命令白名单只允许执行预定义的安全命令禁止rm -rf、curl外网等网络隔离Agent 执行环境不能访问外网防止数据外泄资源限制CPU、内存、执行时间都要设上限防止死循环这些限制在网关层和编排层都要做不能只靠一层。6.4 多租户隔离企业里多个团队共用一套平台隔离是刚需。隔离维度包括配额隔离每个团队有独立的 token 配额和 QPS 上限数据隔离A 团队的对话历史 B 团队看不到密钥隔离每个团队用自己的密钥便于独立计费模型隔离某些高级模型只对特定团队开放这些都在网关的鉴权环节实现通过内部 token 关联到租户信息后续所有操作都带上租户上下文。7. 一些实战中的零碎经验最后分享几个散落但很实用的点。关于 CLI 工具的选择优先选那些有--json输出选项的。文本输出解析起来太脆弱模型稍微换个格式就崩。JSON 输出配合 schema 校验稳定性高一个数量级。关于 Agent 的步数限制不要设太大。我见过设 100 步的结果 Agent 陷入循环烧了几百万 token 才发现。一般任务 20 步足够复杂任务 50 步封顶超了就报错让人介入。关于网关的日志请求和响应内容要脱敏后再存。用户可能在里面输入了敏感信息直接存明文有合规风险。至少要把身份证、手机号、邮箱这类模式做正则替换。关于模型降级降级不是简单换个模型就行。不同模型的输出格式可能不同Agent 的解析逻辑要能兼容。最好在网关层做输出格式归一化让上层感知不到模型差异。关于测试网关和 Agent 都要有 mock 能力。不能每次测试都真调模型又慢又贵。用录制回放的方式把真实响应录下来测试时回放既快又稳定。关于版本管理prompt 也要版本化。Agent 的 system prompt 改一个字行为可能天差地别。把 prompt 纳入 Git 管理每次改动都有记录出问题能快速定位是哪次改动导致的。这套东西我从零搭过两遍第一遍踩了无数坑第二遍就顺多了。核心体会是网关这层越早建越好Agent 的能力越晚放越好。网关是基础设施早建早省心Agent 的能力边界要慢慢放开每放开一个权限都要配套的监控和回滚机制。急着让 Agent 什么都能干最后往往是收拾烂摊子花的时间比省下来的还多。