核心要点
- 生产环境中的大语言模型（LLM）流量不能只看 HTTP 状态码和延迟；团队还需要了解 Token 用量、首 Token 延迟、流式模式、工具调用活动和终端用户上下文。
- API7 网关 3.10.1 新增面向大语言模型的 Prometheus 指标和内置变量，可将这些上下文纳入网关日志。
- AI Proxy Multi 新增有边界的故障切换控制，让团队能够决定何时尝试另一个模型实例，避免在慢失败后自动让延迟翻倍。
- 请求大小限制、正确的超时响应和更可靠的健康实例选择，让 AI 流量在故障期间更容易分析。
- 高级限流能力现已直接整合到
limit-count，降低企业配额与流量治理的配置复杂度。 - 开发者门户升级强化了开发者认证、平台管理、审批流程和 API 文档体验。
- 升级到 3.10.1 需要协同检查仪表盘、安全默认配置、流量控制和开发者门户凭证工作流。
一个 AI 功能在传统 API 仪表盘上可能看起来一切正常，但用户实际上已经遇到了糟糕的体验。
请求可能返回 HTTP 200，首个 Token 却迟迟没有出现。总延迟看似可以接受，也可能只是因为较短的响应掩盖了模型本身的缓慢。请求量没有增加，Token 用量却在攀升。一次故障切换最终可能成功，却让用户等待时间翻倍。带工具调用的流量与普通对话补全可能以不同方式失败，但在仪表盘上，它们仍然显示在同一条路由和同一组状态码图表中。
当大语言模型应用进入生产环境后，这些不再是边缘场景。LLM 流量仍然属于 API 流量，但它的成本、延迟特征、流式行为和故障模式都需要额外的运维上下文。
API7 网关 3.10.1 正是围绕这一生产难题构建的重要平台版本。AI 网关仍是此次更新的技术核心：新的 Prometheus 指标展示 Token 与延迟分布，内置 NGINX 变量描述流式请求和工具行为，AI Proxy Multi 为故障切换设置边界，多项可靠性修复则让上游结果更容易解释。
然而，生产 AI 并不会脱离整个 API 体系独立运行。同一批平台团队还要管理配额、保护开发者访问、审批订阅，并向 API 使用者提供易用的文档。因此，API7 网关 3.10.1 不止增强了 LLM 可观测性，还带来了统一的企业级限流能力和功能更完整的开发者门户。这个版本把 AI 流量运维与 API 管理平台更广泛的职责连接起来。
1flowchart LR
2 apps[AI 应用] --> gateway[API7 AI 网关]
3 gateway --> context[LLM 请求上下文]
4 gateway --> metrics[Prometheus 指标]
5 gateway --> policy[有边界的故障切换策略]
6 context --> logs[网关日志]
7 metrics --> dashboards[运维仪表盘]
8 policy --> models[模型实例]
9 logs --> response[故障响应]
10 dashboards --> response对 LLM 而言，仅靠 HTTP 监控还不够
标准 API 可观测性通常从请求速率、错误率和延迟开始。这些信号对 AI 流量仍然必不可少，它们能说明端点是否可用、故障出现的频率，以及完整请求耗时多久。但它们不足以解释一次大语言模型交互究竟发生了什么。
流式响应改变了用户对延迟的感受。一次完整耗时 20 秒的响应，如果首个 Token 很快出现并持续输出，用户可能仍然觉得它反应及时。相同的总延迟，如果用户等待 18 秒后才看到任何内容，就会像系统已经失效。因此，首 Token 延迟（TTFT，Time to First Token）不仅是模型基准指标，也是运维信号。
Token 数量也改变了流量的含义。两个请求的状态码和耗时可能相同，成本却可能相差巨大。提示词 Token、补全 Token、推理 Token，以及从提供商缓存读取或写入的 Token，都会影响支出与容量规划。即使请求数保持不变，Token 分布上升也可能暴露提示词变化或新用例的出现。
工具调用又增加了一个维度。调用工具的 LLM 响应与纯文本响应走的是不同运维路径。团队可能需要先知道请求是否为流式、暴露了多少工具、模型是否生成了工具调用，才能解释延迟和错误。
网关很适合收集这些上下文。它已经能看到规范化后的客户端请求、选定的提供商、上游响应、路由决策和最终 HTTP 结果。在网关层采集 LLM 专属信号，可以避免每个应用团队各自发明一套日志和指标规范。
同时衡量用户体验与模型工作量
API7 网关 3.10.1 新增提示词 Token 和补全 Token 分布的 Prometheus 直方图，同时增加总延迟直方图，并通过 apisix_llm_latency{type="ttft"} 暴露流式响应的 TTFT。直方图桶可以在 Prometheus 插件设置中配置，让团队根据自身应用关注的延迟与 Token 范围调整仪表盘。
这些指标可以支持多种实用视图：
- 流式端点的 TTFT 分位数，反映用户多快开始看到输出；
- 总延迟分位数，展示完整生成过程耗时；
- 提示词 Token 分布，帮助识别输入变长和上下文窗口压力；
- 补全 Token 分布，用于解释输出长度、成本和总生成时间；
- 当网关指标标签支持相应维度时，对比不同提供商、路由或环境。
本次发布也修改了已有 TTFT 指标。独立的 apisix_llm_ttft 被 apisix_llm_latency 上的 ttft 类型取代。升级到 3.10.1 的团队，应同步更新仍然引用旧指标名称的 Prometheus 查询、记录规则、告警和 Grafana 面板。否则，即使底层能力已经增强，升级也可能造成可观测性盲区。
1flowchart TD
2 request[LLM 请求] --> prompt[提示词 Token 分布]
3 request --> first[首 Token 延迟]
4 first --> stream[流式响应]
5 stream --> completion[补全 Token 分布]
6 completion --> total[总延迟]
7 prompt --> dashboard[AI 运维仪表盘]
8 first --> dashboard
9 completion --> dashboard
10 total --> dashboard这些指标需要结合起来解读。提示词大小稳定而 TTFT 上升，可能说明提供商排队或网络延迟增加。总延迟随补全长度一起增长，则可能是符合预期的应用行为。提示词 Token 增多且 TTFT 变慢，可能说明新的提示词模板或更大的检索上下文增加了模型工作量。网关无法替代提供商侧分析，但能为不同应用和模型端点提供一致的观察视角。
把 LLM 上下文写入团队现有日志
指标用于观察趋势，日志则提供排查所需的请求级上下文。API7 网关 3.10.1 为 LLM 请求新增以下内置 NGINX 变量：
$llm_total_tokens$llm_stream$llm_has_tool_calls$llm_tool_count$llm_end_user_id$llm_cache_read_input_tokens$llm_cache_creation_input_tokens$llm_reasoning_tokens
系统已支持从 OpenAI Chat、OpenAI Responses、Anthropic 和 DeepSeek 等格式中提取并映射这些值。平台团队可以把相关变量加入访问日志格式和日志插件，即使应用使用不同提供商，也能形成统一的运维语言。
这在故障响应中很有价值。如果流式请求出现不同的错误模式，$llm_stream 可以把它们与非流式流量区分开。如果启用工具的请求开始变慢，$llm_has_tool_calls 和 $llm_tool_count 可以帮助识别这类交互。缓存 Token 字段可以解释为什么两个看似相似的调用具有不同用量。终端用户身份在可获取且适合采集时，也能支持按用户排查。
不过，把所有变量全部写入日志并不一定正确。团队应选择能够回答已知运维问题的字段，避免在指标中引入高基数维度，并把终端用户标识符视为潜在敏感数据。在把用户上下文写入集中式日志前，应先检查访问控制、脱敏、保留周期和区域隐私要求。
目标是形成一套稳定的日志模式，帮助响应人员把一个缓慢或昂贵的请求与其 LLM 行为关联起来，而不是最大限度记录所有可用属性。
为模型故障切换划定边界，避免延迟成倍增加
只有行为可预测时，提供商故障切换才能真正提升可用性。快速连接失败后尝试另一个模型实例，可能成功挽救请求；但如果提供商已经长时间处理后才失败，再次尝试可能让延迟翻倍、重复昂贵计算，最终仍然只给用户返回错误。
API7 网关 3.10.1 中的 AI Proxy Multi 为故障切换机制新增 max_retries 和 retry_on_failure_within_ms。max_retries 限制失败后最多可以继续尝试多少个实例；retry_on_failure_within_ms 则把故障切换限制在指定时间窗口内，让慢失败直接返回客户端，而不是自动启动另一次耗时很长的尝试。
1sequenceDiagram
2 participant App as AI 应用
3 participant GW as API7 AI 网关
4 participant A as 模型实例 A
5 participant B as 模型实例 B
6
7 App->>GW: LLM 请求
8 GW->>A: 第一次尝试
9 alt 可重试的快速失败
10 A-->>GW: 在重试时间窗口内失败
11 GW->>B: 有边界的故障切换尝试
12 B-->>GW: 模型响应
13 GW-->>App: 成功响应
14 else 慢失败
15 A-->>GW: 超过重试时间窗口后失败
16 GW-->>App: 保留失败结果，不让延迟翻倍
17 end这些控制项把故障切换转化为明确的延迟预算。团队应根据希望保护的应用体验进行设置。交互式助手可能可以容忍一次快速故障切换，却无法接受第二次完整的模型生成。后台摘要任务则可能接受更长的恢复窗口。正确策略取决于工作负载、提供商行为和端到端超时，而不是某个通用重试次数。
此次发布还修复了 AI Proxy Multi 的健康检查行为。为各实例创建健康检查器后，缓存的服务器选择器此前仍可能把部分流量发送到已经标记为不健康的实例。修复后，选择行为会被正确重建，使配置的健康检查和故障切换策略按预期运行。对运维人员而言，这缩小了“仪表盘显示的实例状态”与“请求实际去向”之间的差距。
让应用和运维人员更容易理解故障
可观测性依赖准确的结果。如果网关把提供商超时转换成错误状态码，或删除错误响应体，应用和运维人员都会失去重要信息。
API7 网关 3.10.1 改进了多条 AI Proxy 故障路径。上游大语言模型超时（包括 DNS 解析超时）现在返回 HTTP 504，而不是 HTTP 500。这个区别十分重要：504 Gateway Timeout 表明网关等待上游响应失败，而泛化的 500 更容易让人误以为是网关内部错误。
该版本也修复了透传模式下的请求转发。现在会保留客户端 HTTP 方法和查询字符串，不再强制使用 POST 或丢弃查询参数。这对 Azure OpenAI 等提供商尤其重要，因为 API 版本可能通过查询字符串传递。如果查询参数在转发时消失，请求被拒绝后很容易被误判为提供商或凭证问题。
ai-proxy 和 ai-proxy-multi 现在具有明确的请求体限制，默认值为 64 MiB。超大请求会返回 HTTP 413。大多数部署仍然受到更低的 NGINX client_max_body_size 默认值限制，但有意支持大型提示词或多模态负载的团队，应让两层限制保持一致。明确的边界既能保护内存，也能在负载过大时向客户端返回可识别的响应。
正确的状态码、完整的请求语义、有边界的请求体和可靠的健康实例选择，能够让仪表盘与日志更加可信。当状态和上下文能够准确描述故障域时，响应人员就能更快完成事件分类。
围绕新信号建立运维模型
新版本提供了监控能力，但团队仍需决定如何把它们纳入日常运维。可以按照以下五个步骤推进：
- 先完成指标迁移。 在升级生产网关前，把仪表盘、告警和记录规则中的
apisix_llm_ttft查询替换为apisix_llm_latency{type="ttft"}。 - 选择服务级指标。 分别为交互式流式和非流式工作负载定义 TTFT 与总延迟目标；在 Token 分布有助于解释容量或成本时，将其加入监控。
- 设计最小化的 LLM 日志模式。 只选择响应人员真正会使用的请求级变量，并让安全与隐私负责人检查终端用户标识符和 Token 信息。
- 按工作负载设置故障切换预算。 根据应用延迟预算配置重试次数和允许触发故障切换的时间窗口，测试快速失败、慢失败和不健康实例。
- 测试真实客户端行为。 在预发布环境验证透传方法和查询字符串、大请求拒绝、提供商超时、流式响应和工具调用。
平台团队还应明确每类信号的负责人。网关团队可能负责可用性、提供商路由和故障切换；应用团队可能负责提示词大小和工具定义；FinOps 团队关注 Token 分布；安全团队则治理终端用户日志。只有每条告警都有清晰的处理负责人，共享仪表盘才真正有用。
建立 AI 运维模型后，此次发布的其他能力把同样的原则——集中控制与明确归属——从模型流量扩展到 API 配额和开发者访问。
用统一的 Limit Count 能力简化企业级限流
限流是 API 治理最直观的体现之一。它把服务容量、商业套餐和消费者权益转换为每个请求都会执行的规则。当运维人员必须针对不同环境在标准插件和独立高级版本之间选择时，这项工作就会更加困难。
API7 网关 3.10.1 把此前仅由 limit-count-advanced 提供的能力直接整合到 limit-count。标准插件现在支持 Redis Sentinel、滑动窗口计数、单个配置中的多个独立限制、从 NGINX 变量动态获取 count 和 time_window，以及通过 sync_interval 延迟同步 Redis。
这种统一在运维层面意义很大。平台团队可以动态表达每个消费者的配额，把短时突发保护与更长周期的用量限制组合起来，并使用 Redis Sentinel 构建更具韧性的共享计数器存储，而不必切换到另一套插件模型。多个 rules 还能让相关限制保存在一起，避免把配额逻辑分散到多个配置中。
现有 limit-count-advanced 配置仍然有效，因为该插件会作为轻量封装继续存在，所以 3.10.1 不要求立即迁移配置。真正需要关注的是 Redis 计数器格式：键会加入版本，现有计数器不会迁移，升级时会重置一次，之后仍按原有 TTL 过期。如果这些计数器用于执行合同配额或保护容量，团队应提前考虑这个短暂的重置窗口。
最终结果是在不牺牲策略灵活性的前提下简化 API 流量管理。企业级能力进入主要限流路径后，平台可以更容易地在不同网关组之间标准化、审查和运维配置。
用更强的开发者门户改善 API 产品管理
运维 API 管理平台不只是控制运行时流量。组织还需要把 API 打造成开发者能够发现、理解、申请并在明确访问策略下使用的产品。API7 网关 3.10.1 通过更完整的开发者门户体验，强化了这一产品生命周期。
安全从开发者账号开始。开发者和 API 消费者可以在账号安全设置中配置基于 TOTP 的双因素认证，并在登录时使用六位身份验证器代码。对于可能持有生产凭证或访问合作伙伴专属产品的用户，这为 API 计划提供了更强的账号保护。
平台团队也获得了集中式管理界面。专用管理区域可以列出和搜索用户、修改角色、封禁或解封账号、删除用户，并按成员关系筛选组织。这样，开发者访问就成为一项明确的运维职责，而不再是一组手动数据库操作或支持工单。基于策略的 SSO 路由还可以按照电子邮件域名规则，将用户引导至账号密码登录、邮件链接登录或适合的身份提供商。
对于受控接入，开发者门户新增了开发者注册和 API 产品订阅审批流程。平台管理员可以直接在门户中审查和处理请求，审批决定会与控制台保持同步，并记录执行操作的管理员。对于企业 API 治理，这种共享工作流很重要：团队可以继续监督谁能够加入开发者生态、谁可以使用哪些产品，同时无需把所有决定都转移到线下工单队列。
文档体验也成为产品体验的一部分。开发者门户可以在 /docs 下托管内置 Markdown 文档站点，提供侧边栏导航、目录、代码复制、页面复制、全文搜索和搜索结果高亮。开发者可以在品牌统一的门户中直接从发现 API 进入实现阶段，无需跳转到彼此割裂的文档系统。
更强的认证、集中管理、受治理的审批和集成文档，共同构建了从 API 发布到负责任使用的清晰路径。网关在运行时治理请求，开发者门户则治理人们如何发现和获取这些 API 的访问权限。
升级到 3.10.1 前需要检查什么
API7 网关 3.10.1 会改变可观测性、安全默认配置、流量控制和开发者工作流。按运维负责人对检查项进行分组，可以让升级验证更加清晰。
AI 可观测性迁移
- 在 Prometheus 查询、记录规则、告警和 Grafana 仪表盘中，用
apisix_llm_latency{type="ttft"}替换apisix_llm_ttft。 - 确认直方图桶适合当前提示词大小、Token 分布和延迟目标。
- 检查故障切换重试次数、重试时间和端到端应用超时。
- 判断 LLM 终端用户 ID 或其他新增日志字段是否需要脱敏、访问控制或保留周期调整。
安全变化
- 确认 JWT 消费者已经适配默认验证
exp和nbf声明；此前可能被接受的过期或尚未生效 Token 将返回HTTP 401。 - 如果启用了数据面数据加密，请检查新纳入加密范围的日志、Serverless、AI 内容审核、OpenID Connect 和错误日志字段。
- 协调控制面与数据面的升级顺序，避免旧数据面收到无法解密的密文。
流量管理变化
- 考虑新版计数器格式导致 Redis
limit-count计数器一次性重置的影响。 - 检查 NGINX 以及
hmac-auth、forward-auth、ai-proxy和ai-proxy-multi各层的请求体限制。 - 检查使用
batch-requests的客户端：默认最多包含 1,000 个流水线请求条目，文档未定义的字段会被拒绝，超时值至少为 1 毫秒。
开发者门户变化
- 调整集成逻辑，在创建或重新生成凭证时立即保存 key-auth 密钥和 basic-auth 密码；读取或列表接口不再返回这些敏感值。
- 明确 TOTP 支持、平台管理员权限、注册审批、订阅审批和 SSO 域名规则的运维负责人。
完整升级说明请参阅 API7 网关 3.10.1 发布说明。进入生产环境前，应在预发布环境中使用具有代表性的流式、非流式、工具调用和故障切换流量验证这些变化。
把 AI 与 API 流量作为一个平台统一运维
生产 AI 系统需要一套能够反映大语言模型真实行为的运维模型。HTTP 可用性只是基础，用户体验取决于首 Token 延迟和流式输出，成本与容量取决于 Token 数量，可靠性取决于提供商健康状态、错误语义和故障切换预算，而故障响应则依赖跨提供商、跨应用的一致上下文。
API7 网关 3.10.1 把这些问题进一步收敛到网关层。LLM 指标描述用户体验与工作负载，内置变量为日志增加请求级上下文，有边界的故障切换保护延迟，可靠性修复则让健康实例选择、超时响应和提供商特定转发更加可预测。
更广泛的平台更新把这些 AI 网关能力与企业 API 治理和开发者体验连接起来。统一后的 limit-count 能力更容易标准化复杂配额；开发者门户的安全、管理、审批和文档能力，则帮助团队把 API 作为产品而不只是端点来管理。
API7 网关 3.10.1 帮助组织从“仅仅路由 AI 请求”迈向“以更强的可见性、可预测的可靠性和企业级治理统一运维 AI 与 API 流量”。从实际能力来看，这个版本在同一个 API 管理平台中结合了 AI 网关能力、API 流量可靠性、企业策略控制和更好的开发者体验。阅读 API7 网关 3.10.1 发布说明，了解 API7 AI 网关文档和开发者门户文档，为升级做好准备。