上个月我把一个做了半年的端云协同 LLM 网关开源了代码放出去之后陆续有人来看但我很清楚一个网关项目真正值不值得用光靠我自己跑 demo 是不够的必须拿到真实业务流量里磨一磨。所以我发了一个招募想找 35 位正在做 LLM 应用、愿意花一周时间做真实测试的开发者一起把这个东西打磨到能放心上生产的程度。这个项目解决的问题简单说就是三件事让 LLM 调用成本降下来、让端侧小模型和云侧大模型能协同工作、给所有模型路由和调用加一个统一的管控入口。适合谁看正在做 RAG 问答、智能客服、Agent 工具调用或者手上有端侧设备想跑 AI 能力的开发者这篇内容应该能给你一些参考。我会把架构思路、核心设计、功能实现、当前测试计划挨个拆开讲也会把我踩过的坑全部翻出来希望对你自己的网关设计或选型有帮助。1. 项目背景LLM应用落地为什么需要“端云协同”这层网关1.1 三个真实痛点成本、延迟、数据边界我接触过不少落地 LLM 的团队大家最初都挺兴奋但一旦进入生产环境第一个被骂的就是账单。大模型 API 按 token 计费一次普通问答几毛钱看着不多一旦日请求量上万成本立刻变成一笔让人肉疼的开支。而这里面有大量请求其实是“杀鸡用牛刀”——意图分类、实体抽取、短文本摘要、客服开场白这些小任务完全可以让端侧小模型完成。这是做端云协同的第一个动机省钱。第二个痛点是延迟。云侧 API 的响应时间受网络、排队和供应商负载影响快的时候 300ms慢的时候能到 5 秒。对于交互型应用来说这种抖动非常致命。端侧模型一旦加载到内存推理速度稳定在几十毫秒到几百毫秒之间这让“能端上跑的绝不轻易上云”变成了一条性价比极高的原则。第三个痛点是数据边界。我合作过的一家企业内部知识库明确要求某些数据不能离开办公网。可他们的问答场景又需要大模型级别的理解和生成能力。这种矛盾靠单一模型没法解决只能靠网关做策略把本地小模型能搞定的内容留在端侧真正需要复杂推理的再脱敏后上云。如果没有网关这层统一路由层这三件事都得在业务代码里东一块西一块地自己写维护成本极高。1.2 网关在 LLM 链路中扮演的角色很多人一听到“网关”两个字第一反应是“不就是个反向代理吗”。如果只是转发请求那确实和 Nginx 没区别。但 LLM 网关要做的事远不止转发我用一个类比来解释它更像一个自动挡变速箱——动力需求小时用低档位省油突然要超车时迅速降档拉转速整个过程驾驶员不需要手动干预。落到 LLM 场景网关的职责主要体现在四个维度协议转换各家模型接口格式不统一统一网关可以把 OpenAI 风格请求转成任何一家供应商的格式业务侧只对接一个 API。请求路由根据意图、复杂度、成本预算、延迟约束等维度决定请求发给端侧小模型还是云侧大模型。质量兜底端侧模型结果质量不够时自动升级到云侧云侧超时或失败时触发降级策略。治理管控统一管理 API Key、租户配额、限流、缓存、日志和审计。端云协同这个思路本质上就是把这些能力揉在一起让路由决策不再是一个“死规则”而是能感知端侧能力和云侧成本动态变化的智能调度。这也是这个项目最核心的设计目标。2. 技术架构拆解端云协同 LLM 网关的核心设计2.1 整体拓扑客户端接入层、路由决策层、模型适配层整个网关从逻辑上分为三层第一层是客户端接入层。我实现了一个轻量 SDK支持 Python 和 TypeScript接口做成了 OpenAI 兼容格式。为什么刻意兼容 OpenAI因为现在市面上主流的 LLM 应用框架比如 LangChain、LlamaIndex、各类 Agent 框架默认都支持 OpenAI 格式。应用侧接入时只需要改一行 base_url 指向网关不需要改业务逻辑。这一层还负责收集请求的上下文信息比如用户身份、会话 ID、请求意图标签。第二层是路由决策层也是整个网关的大脑。它接收请求后会先做意图识别和复杂度预估然后结合配置的策略和实时状态云侧延迟、预算剩余、端侧可用性做出路由决策。我测试过把这一层单独跑在一个只有 2C4G 的边缘节点上单机每秒可以处理超过 800 次路由决策延迟在 2ms 以内不会成为性能瓶颈。第三层是模型适配层。它统一屏蔽了各家大模型 API 和本地推理框架的差异。云侧这边OpenAI、Anthropic、Google 以及国内几家主流的开源模型托管 API 都做了适配端侧这边接入了 Ollama、llama.cpp、ONNX Runtime 等推理框架。这一层还做了流式响应转换不管是云侧还是端侧返回的流式数据到了业务侧都是统一的 chunk 格式。架构上有个关键设计端侧模型并不是由业务设备直接调用而是由网关下发路由指令。也就是说移动端 App 或 PC 客户端发出请求后网关如果判断“这个问题端侧能搞定”会返回一个路由指令让 SDK 直接调用本地加载的小模型如果判断需要上云网关就走云端链路转发。这种“先问网关再执行”的方式比端侧自己做本地判断更可控因为策略集中在服务端调整规则不需要发版 App。2.2 路由策略怎么判断一个请求留在端侧还是上云这是整个网关设计中最难、也最值得细说的部分。路由策略我分了三个层级从简单到复杂第一层规则策略。最适合初始化阶段。网关内置了一个任务类型识别器通过 prompt 分类或关键词匹配把请求打上 intent 标签比如summarize、extract_entity、intent_classify、code_gen、multi_hop_reasoning。然后按照配置文件里的映射关系决定目标模型。例如“短文本摘要走端侧”、“代码生成走云侧”这就是一个白名单加黑名单机制简单直接适合起步。第二层启发式策略。当规则无法覆盖所有场景时就需要启发式判断。核心指标是复杂度预估分析用户输入的 token 长度、是否包含多轮依赖、是否涉及数学计算或逻辑推理给出一个 01 的复杂度分数。同时估值端侧模型的自信度——本地模型跑完推理后我让 SDK 返回一个 logprobs 平均值综合起来形成一个 score。分数超过阈值就走端侧否则就走云侧。第三层动态策略。适合对成本有精细化要求的团队。动态策略引入了成本预算和延迟约束比如“本月云侧消耗预算还剩 40%把上云阈值从 0.7 提高到 0.85”。这个策略模块支持自定义插件开发者可以用 Python 写自己的决策函数。这里我想强调一个很多人在设计路由时容易忽略的点端侧模型的能力并不是一成不变的。同样是 3B 参数的模型Qwen2.5-3B 和 Llama-3.2-3B 在意图识别上的表现差异可能很大同一模型在不同任务类型上的表现也不同。所以我加了路由回退机制端侧返回结果后如果质量评分低于阈值网关会自动发起一次云侧调用作为修正并把这次路由回退事件记录下来。这套机制救了我很多次后面在常见问题里我会展开讲。route: rules: - when: intent: [summarize, intent_classify, extract_entity] estimated_complexity: low target: edge - when: intent: [code_gen, multi_hop_reasoning, math] target: cloud fallback: enable: true confidence_threshold: 0.6 upgrade_target: cloud这套配置的意思是意图分类、实体抽取这类轻任务优先给端侧代码生成、数学推理直接上云一旦端侧置信度低于 0.6自动升级到云端。实际运行中这套规则可以覆盖 70% 以上的请求剩下 30% 靠后续优化。2.3 模型适配与统一接口层统一接口层是一个 LLM 网关绕不开的基础设施。我最早天真地以为各家 API 差异不大写几个适配器就行。实际做完发现光是消息格式就有好几种OpenAI 是纯文本roleAnthropic 是messages数组带content块部分国内平台还保留了特别的 system 字段处理方式。更麻烦的是工具调用Function Calling格式各家差异极大。我最后采取的策略是内部定义一套 Canonical Message 格式各适配器负责双向转换。对外暴露 OpenAI 兼容的/v1/chat/completions和/v1/embeddings两个接口内部再通过 router 分发到不同供应商。这套设计的收益在切换模型时体现得特别明显——业务代码完全不动只要在网关配置里改一行provider: qwen就能从 GPT 切到国产开源模型。端侧模型的适配是另一套逻辑。端侧不是走 HTTP 接口转发而是通过 SDK 调用本地推理引擎。我在 SDK 里封装了统一的ModelHandle接口初始化时指定引擎类型比如ollama或llama.cpp然后暴露chat()和generate()两个方法。网关和 SDK 之间建立了一条长连接控制通道路由指令和模型切换命令都走这个通道下发不走传统的请求-响应模式这样能显著降低端侧冷启动的感知延迟。3. 功能实现与配置参考网关落地时最实用的几个能力3.1 缓存与上下文管理LLM 调用里有一种痛叫“重复请求”。同一个用户反复问同一个问题、多个用户问高度相似的问题直接每次都打大模型烧钱又没必要。我在网管里实现了两层缓存第一层是精确缓存。对请求体计算哈希命中直接返回历史结果。这个实现简单但说实话命中率不高因为用户的自然语言几乎不会一字不差地重复。第二层是语义缓存。这是收益更高也更有技术含量的部分。把输入消息通过 embedding 转成向量用向量相似度检索已有的缓存条目相似度超过阈值就直接复用答案。我用的是一套轻量的向量索引库支持 HNSW 算法在 100 万条级别的缓存条目下查询延迟可以控制在 10ms 以内。语义缓存最适合知识库问答场景——很多用户的问题只是问法不同核心语义是一样的。上下文管理是更头疼的问题。多轮对话中端侧模型处理长上下文的窗口有限云侧模型虽长但 token 成本高。我做了Token 压缩和上下文续接当会话切换路由目标时网关会把之前的对话消息做一个摘要压缩以“历史摘要最近两轮完整消息”的形式传给下一个模型。实测下来这种方案在保持 90% 以上关键信息的前提下能把上云 token 消费降低 35%50%。# 创建带上下文续接的会话 POST /v1/chat/completions { model: auto, conversation_id: conv_8f3a, messages: [ {role: user, content: 帮我总结一下上季度销售数据} ], stream: true }网关会根据conversation_id自动拉取会话上下文完成压缩和组装。业务侧完全不需要维护会话历史这个能力对客户端 App 特别友好。3.2 限流、鉴权与多租户网关一旦成为流量的统一入口安全和治理能力就是刚需。我实现了基于 API Key 的认证体系每个 Key 绑定一个租户租户可以配置独立的模型白名单、配额和告警阈值。限流这块支持四维控制每秒请求数、每分钟 token 消耗、最大并发数、日累计成本上限。我特别想强调“按成本限流”这个设计。很多团队在业务快速增长期最容易出的问题就是成本失控。一个 bug 导致循环调用一晚上账单能多出几万块。我在网关里加了一个硬性保护每个租户可以设定“单日云侧消耗上限”一旦达到阈值后续请求自动降级到端侧模型或者直接返回 429。这个功能救过我一位朋友的团队他们某次线上事故中后端重试逻辑死循环网关在 20 秒内拦截了超过 3 万次重复请求成本损失几乎为零。3.3 可观测性日志、指标、链路追踪一个网关如果不可观测那还不如不用。我给网关内置了三类可观测数据请求日志完整记录每次请求的路由决策、目标模型、输入token数、输出token数、耗时、路由回退事件。业务指标通过 Prometheus 格式暴露包括请求量、端侧请求占比、云侧成本累计、平均首token延迟、缓存命中率、回退率。链路追踪基于 OpenTelemetry 实现支持把一次“端侧判断→云侧升级→流式返回”的完整链路串联起来。坦白讲可观测性这件事一开始我是做得不够的。最早版本只打了日志结果联调时发现端侧模型明明返回了结果但用户端就是没收到。查了半天才发现是 SDK 在长连接断线重连后没有正确恢复状态。要是在日志里加了链路 ID 和事件时间线这个问题 5 分钟就能定位。建议所有做网关或中间件的开发者第一版就把可观测性做进去别欠技术债。4. 真实测试计划我正在找什么样的开发者来一起玩4.1 目标测试者画像我说要找 35 位开发者不是走个过场我是认真想拿到一批真实环境的数据。最希望的测试者大概有这四类做 RAG / 知识库问答应用的开发者这类应用天然适合验证语义缓存和端云路由的效果因为查询重复度高、意图类型集中。做聊天机器人 / Agent 的开发者适合验证多轮上下文的 Token 压缩效果、工具调用的稳定性、流式响应的兼容性。做端侧应用或嵌入式项目的开发者在手机、PC 甚至树莓派上集成 SDK帮我把端侧引擎适配和长连接稳定性打磨得更扎实。做开源中间件 / 内部平台的开发者如果你自己正在维护一套 AI 基础设施可以帮我从架构角度挑毛病。测试的前提是我会把完整的部署文档和示例代码给到参与者包括 Docker 一键启动、K8s Helm 包、本地二进制三种部署方式。4.2 测试流程建议我建议测试者按这样一个节奏来方便最后对比数据场景接入半天基于示例代码把网关接入自己的一个真实业务场景替换掉原来的直连大模型调用。影子模式12天网关提供 shadow 模式请求同时发给网关和新链路但业务仍走旧链路。这个模式可以零风险验证网关的稳定性和路由准确性。切换模式35天确认无重大问题后正式把流量切到网关观察端侧占比、成本变化、延迟分布。反馈输出半天导出网关生成的统计报表加上测试者自己的体验反馈整理成一份测试报告。最后我需要拿到的反馈包括路由决策的准确率、端侧模型回答的质量评分、缓存命中率、降本比例、网关稳定性表现以及测试者在接入过程中遇到的卡点和体验问题。4.3 我最想获得的三个答案说实话这个项目我不缺功能缺的是“真实场景验证”。我最想知道三个问题的答案端云协同是否真的能降本现在内部测试中端侧请求占比大约 40%60%但不同场景差异很大。我想知道在真实业务流量里这个数字落在什么区间降本比例是否能达到 30% 以上。路由回退的质量损失有多大端侧先答、不行再上云的策略和直接上云相比用户感知质量会打几折。如果损失不可接受我宁可把路由策略调得更保守。网关在压力下的稳定性自己压测和真实流量是两回事。真实场景里什么稀奇古怪的请求都有长文本、图片输入、并发高峰、供应商限流网关能不能扛住这是我最关心的。这些结果我会全部公开做成一个测试报告回馈给所有参与者也会被汇总到项目的 README 里。5. 常见问题与避坑实录上线前后最容易翻车的几个地方5.1 端云路由误判导致的结果质量波动这是我踩过最深的一个坑。最早版本的复杂度预估模型主要看 token 长度和关键词。结果发现一些短问题其实很难比如“这段代码的时间复杂度是多少”token 不到 20但端侧 3B 模型回答得乱七八糟。最开始回退机制没加用户直接看到了低质量回答差点被打回原型。后来我把路由决策从“只看文本特征”升级成“文本特征小模型预判置信度回退”三步走。同时把回退阈值调低到了 0.6宁可在端侧多花点推理时间也不让烂结果直接出网。如果你也要做类似的路由我的建议是回退机制一定要比路由决策先上线。端侧小模型的“自信”很多时候是虚假自信没有兜底就是裸奔。5.2 语义缓存的误命中问题语义缓存里有一个微妙的平衡向量相似度阈值设高了缓存命中率低省钱效果不明显阈值设低了经常出现“语义相似但答案不同”的误命中。比如“今天天气怎么样”和“今天适合出行吗”向量相似度可能超过 0.9但它们其实需要完全不同的答案。我的解决办法有两层。第一把缓存 key 从“用户全量输入”改成“意图标签关键实体问题指纹”的组合。第二相似度阈值做成可调并在缓存命中时通过端侧模型做一次快速校验确认两个问题确实等义再复用答案。经过优化后误命中率从最初的 8% 降到了 1% 以内。这块调参的经验是我最想跟测试者分享的部分。5.3 端侧模型的工具调用不稳定如果你的应用重度依赖 Function Calling请务必对端侧模型做充分测试。我的实测结果是7B 以下的端侧模型在工具调用上的表现远不如云侧 GPT-4 级别模型。经常出现的问题有函数名生成错误、参数格式不规范、应该调用工具时直接瞎编一个答案。现在网关里的做法是对端侧模型默认关闭工具调用统一走“云侧工具调用代理”。也就是端侧负责理解用户意图和生成回复一旦判定需要调用工具立即把控制权交给网关由网关用云侧模型完成工具解析和调用。代价是多一次云端请求但换来了稳定性的大幅提升。如果你的 Agent 对工具调用准确性要求很高现阶段不要把端侧工具调用直接暴露给业务方。5.4 网关升级对长连接会话的影响SDK 和网关之间那条长连接控制通道是我早期比较头疼的部分。网关在升级、重启时如果没做连接迁移端侧的模型状态就全丢了用户要重新加载模型体验非常差。现在我在 SDK 里实现了断线重连和状态恢复机制网管升级时会把当前会话状态持久化并在新实例启动后自动恢复。这个机制经过了大概三轮迭代才稳定下来期间出现过一次内存泄漏导致网关 OOM排查了整整两晚上最后发现是长连接心跳包没做超时回收。5.5 网关作为统一入口的安全风险最后想提醒一件事网关既是统一入口也是一个高价值攻击目标。拿到网关的 API Key等于拿到了所有模型供应商的调用权限。所以我把 Key 设计成了两段式管理 Key 和调用 Key 分离调用 Key 不能查看租户账单和配置信息。网关还内置了审计日志所有管理操作和模型调用都会留痕。上线前务必改掉默认密钥并且启用 IP 白名单——你在真实测试中如果发现安全设计上的漏洞欢迎第一时间来骂我。我在实际测试中发现网关这类中间件最大的成本其实不在功能开发而在“环境适配”。不同的端侧设备、不同的推理引擎、不同的网络条件总会带来文档里写不到的各种意外。如果这次能找到 35 位认真的开发者一起测我有信心把这些问题在正式版本发布前全部清干净。对这个项目感兴趣、想拿自己的真实场景来给我上一课的开发者欢迎直接来仓库提 issue我会在 24 小时内回复。