什么是 LLM 代理？
模型请求路径上的透明检查点LLM 代理
模型请求检查点
LLM 代理在控制客户端到模型供应商请求的同时保持稳定契约。
速览
代理接收客户端请求并转发到上游模型端点，过程中可能转换请求与响应。
网关通常使用代理位置，但增加身份、配额、策略、预算、护栏、管理与证据。
路由器选择上游模型或供应商；一个生产代理可以同时包含路由与网关功能。
客户端需要稳定契约，但转换、重试、回退、缓存与用量必须在调用链中可见。
LLM 代理数据路径
入站客户端认证并发送规范请求。代理验证身份、标准化 Schema、选择 Provider Adapter 与可选路由、应用超时、重试、Fallback、限额与缓存，再经过错误和用量标准化，把上游响应流式返回。
每项功能都会改变故障域。认证故障可能阻断全部租户；Schema 转换可能悄悄改变工具或采样；路由可能把数据发往不同 Provider 或区域；重试会放大支出；缓冲可能破坏 Token Streaming；缓存可能越过租户或策略边界；用量标准化错误会导致账单无法对齐。因此每个阶段都应作为有明确 Owner 的子系统，而不是透明管道。
有状态 Proxy 还可能管理 Virtual Key、预算、配置、缓存、用量与 Trace，从而产生数据库、一致性与恢复责任。需要定义数据真源、复制与备份策略、配置发布、密钥撤销延迟、预算执行一致性，以及依赖不可用时的降级行为。无状态 Proxy 更简单，但仍依赖外部控制、策略、Secret 与遥测服务，同样要建模这些依赖的故障。
代理职责与风险
| 职责 | 最适合 | 选择前验证 |
|---|---|---|
| 认证 | 提供统一客户端身份边界并保护上游供应商凭证。 | 避免记录密钥；定义租户隔离、轮换、最小权限与冒充控制。 |
| 请求标准化 | 把规范结构定义映射到供应商协议与默认行为。 | 隐藏转换会改变提示词、工具、参数、错误与模型语义。 |
| 路由与回退 | 选择上游并从符合条件的失败恢复。 | 客户端与代理双重重试会放大负载、重复请求并产生未核对费用。 |
| 缓存与限额 | 减少重复工作并保护配额、供应商与预算。 | 规定缓存资格、陈旧度、隔离、用量归因与一致限额行为。 |
| 遥测与错误 | 跨供应商特定行为统一证据与客户端处理。 | 保留原生 ID、原始错误原因与用量，不要抹平事故或计费证据。 |
四种常见代理故障模式
客户端、代理与供应商 SDK 重试在无共享截止时间或尝试预算时叠加。
标准化丢失供应商特定参数、响应字段、流事件、错误或用量。
回退在缺乏清晰资格与证据时改变模型、供应商、区域、策略或价格。
密钥、预算、路由、缓存、用量或调用链依赖缺少备份、一致性或回滚的状态。
把代理作为协议边界测试
只测试成功的非流式文本调用，会漏掉 Proxy 最容易引入的问题。应从生产工作负载契约构建 Conformance Suite，并同时跑直连与代理路径。为请求字段、输出 Schema、流事件顺序、工具参数、Finish Reason、错误、用量、Provider Identity 与延迟预算定义预期不变量。
- 对比直连与代理请求、输出、流、工具、错误、用量、Header 与 Provider ID。
- 强制 DNS 故障、连接拒绝、超时、断连、429、5xx、部分流、无效 Schema、Cache Miss 与 Provider Fallback。
- 验证客户端、Proxy、Adapter 与上游 SDK 共享一个父截止时间和尝试预算，防止嵌套重试成倍增加。
- 测试取消与客户端断连，确认上游工作能够停止或仍可正确归因。
- 对 Proxy 自身的连接池、队列、Buffer、配置存储、Rate Limiter、缓存与遥测背压进行负载测试。
- 核对请求数与账单，并导出配置、Virtual Key 映射、路由、缓存策略与 Trace 供回滚。
把转换与尝试设为一等追踪片段
为认证、请求标准化、路由决策、每次供应商尝试、缓存、流与响应标准化创建显式追踪片段。传播共享截止时间与尝试预算；在不记录敏感请求数据的情况下保存规范与原生字段映射；返回稳定客户端错误，同时在调用链中关联原生供应商原因。
生产规则：代理可以向客户端隐藏供应商复杂性，但绝不能向运营人员隐藏行为。
LLM 代理控制推理流量，而非所有工具
使用 LLM 代理处理模型协议与流量；使用 QVeris 处理智能体外部能力边界：在独立契约、凭证、幂等性与证据下发现、检查并调用 API、工具、服务与实时数据。
FAQ
位于模型请求路径中的服务，转发并通常转换、路由、保护和观测对供应商端点的调用。
代理是转发模式，网关是治理角色；生产产品可以同时是两者。
仅在共享截止时间、有界尝试、合格错误、防重复、流规则与可见证据下重试。