Reliability and Routing2026年7月3日Big Y

AI API 超时策略：连接、读取、流式传输和队列预算

在事故造成昂贵损失之前，为生产环境的 AI API 设置连接、读取、流式传输、队列、重试、回退和可观测性的超时预算。

超时不是一个单一的数字。一个生产环境的 AI API 超时策略需要为连接、读取响应、流式传输令牌事件、在队列中等待、安全重试以及决定何时停止回退分别设置预算。如果这些预算混合在一起，那么缓慢的提供商、阻塞的连接池或半开的流可能看起来像是同一个事件。

AI API 超时策略的目标是使故障有界且可观察。面向用户的聊天请求可能需要快速的第一个令牌和硬停止。后台研究任务可能需要队列截止时间和轮询。模式提取作业在回退之前可能需要在同一路由上重试一次。每个工作流都需要自己的预算，并且每次超时都必须为工程、财务和产品负责人留下证据。

Flatkey 适合这项可靠性工作，因为当模型访问、路由、计费、使用分析和操作控制都通过一个网关处理时，超时策略更容易审查。使用下面的清单作为应用程序策略，然后在发送生产流量之前验证当前的 Flatkey 模型行、端点族、使用证据和路由行为。

AI API 超时策略一览表

首先为每个超时层分配一个所有者和一个停止条件。

超时层	保护对象	初始预算	重试规则	回退规则	要记录的证据
连接	DNS、TLS、网关可达性和套接字设置	短，通常低于请求预算	仅在未接受任何请求体时重试	仅在端点族等效时使用备用路由	`connect_ms`、路由、主机、错误类别
池或队列获取	等待本地工作线程、连接或速率限制槽位	对于交互式工作非常短	不要盲目重试；首先降低并发性	在更改模型之前排队或减载	队列年龄、池等待时间、并发性、所有者
请求/读取	发送请求后等待响应体	与用户体验或作业截止时间相关	对瞬时故障进行一到两次有界重试	仅回退到保留输出契约的路由	请求 ID、状态、读取超时、使用情况（如果存在）
流式传输第一个事件	等待第一个 SSE 或令牌事件	低于总流式传输截止时间	在用户可见的输出开始前重试	仅在部分输出提交前回退	首事件延迟、请求的模型、服务的模型
流式传输空闲	输出开始后流式数据块之间的间隙	基于正常的事件间间隙	仅在 API 支持时恢复；否则干净地停止	避免在回答中途切换模型	最后序列、空闲间隙、部分输出标记
后台队列	用户请求之外的长时间运行工作	明确的截止时间和轮询间隔	轮询直到达到最终状态或截止时间	在重复工作前升级或取消	响应/作业 ID、状态、队列年龄、取消原因
回退停止	防止重试导致成本失控	硬性尝试和支出上限	预算用尽后停止	对高风险工作流变更进行人工审查	尝试次数、回退原因、成本、所有者

此表是 AI API 超时策略的核心。确切的数字应来自真实流量，但这种分离应在第一次生产事件发生之前就存在。

根据工作流意图构建预算

不要将一个超时值复制到每个 AI 功能中。对于后台评估来说感觉很宽裕的超时，在支持聊天中可能是不可接受的。对于文本答案来说合适的超时，对于长上下文工具工作流可能太短。围绕工作流意图编写 AI API 超时策略：

交互式聊天需要首事件预算、总响应预算，以及在预算用尽时向用户显示优雅的消息。
流式用户体验需要首事件和空闲预算，因为一个已连接但停止产生事件的流与一个缓慢的完整响应是不同的。
结构化提取需要一个模式有效性重试预算，而不是通用的重试循环。
代理或重工具工作需要队列截止时间、工具调用上限、取消路径和轮询记录。
财务、采购或合规审查需要保守的回退策略，因为更改模型可能会改变风险、成本、证据或批准状态。

官方 SDK 的 OpenAI 当前的超时指南指出，默认请求在 10 分钟后超时，并且 Python 和 JavaScript SDK 都公开了一个 timeout 选项。了解这个默认值很有用，但它不应成为应用程序的策略。生产团队仍然需要为用户体验、成本和事件响应制定更严格的工作流预算。

连接和池预算应快速失败

连接预算回答一个狭窄的问题：客户端能否足够快地到达网关或提供商端点以启动请求？它通常应该比读取预算短得多。如果连接设置失败，没有任何模型生成任何内容，因此重试决策的风险低于在部分响应后重试。

使用 HTTPX 的 Python 团队可以清晰地表达这一点，因为 HTTPX 分离了连接、读取、写入和池超时。OpenAI Python SDK 也接受一个 httpx.Timeout 对象，因此应用程序可以将连接和读取预算分开：

import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
    timeout=httpx.Timeout(
        timeout=20.0,
        connect=2.0,
        read=10.0,
        write=10.0,
        pool=1.0,
    ),
    max_retries=1,
)

重要的不是示例值。重要的是，AI API 超时策略不会花费 20 秒才发现套接字无法打开或本地连接池已饱和。

对于 Node.js，OpenAI JavaScript SDK 公开了一个以毫秒为单位的 timeout 选项，Node 也为接受中止信号的 API 提供了 AbortSignal.timeout(delay)。使用这种模式可以使应用程序的截止时间明确，而不是依赖于无限制的调用者。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
  timeout: 20_000,
  maxRetries: 1,
});

将连接超时视为基础设施信号。如果连接超时激增，请在更改模型之前检查 DNS、TLS、网关可达性、池限制、本地工作线程饱和度和出口策略。

读取预算保护成本和用户体验

读取预算是应用程序在请求被接受后等待响应的最长时间。这是 AI 工作负载与普通 JSON API 的不同之处：模型可能合理地慢，输出可能很长，或者提示可能触发工具工作。因此，读取超时应根据工作流的截止时间设置，而不是根据库的默认值。

使用以下规则：

工作流	读取预算规则	超时后该做什么
聊天或支持	根据用户耐心和服务 SLO 设定预算	显示优雅的超时状态，记录请求，仅在用户可见输出前重试
批量提取	根据作业截止时间和队列容量设定预算	同一路由重试一次，然后标记记录以供审查
代码或推理	根据任务复杂度和工具上限设定预算	如果任务自然运行时间较长，考虑使用后台模式
财务或采购	根据审查 SLA 设定预算	停止并排队，而不是静默更改路由
内部自动化	根据下游依赖项的截止时间设定预算	尽早失败，以便调用者可以进行补偿

AI API 超时策略还应限制输出大小、工具调用和回退尝试。如果重试层创建了重复的工作，仅靠读取超时无法控制成本。

流式传输预算需要两个时钟

提高请求超时并不能解决流式传输的问题。流式 AI 响应至少有两个时钟：

首个事件超时：用户在收到第一个流事件或令牌之前等待多长时间。
空闲超时：应用程序在流式传输开始后容忍静默多长时间。

OpenAI API 参考将启用 stream 时的流式传输描述为服务器发送事件 (server-sent events)。对于后台响应，OpenAI 还记录了带序列号的流式传输，以便客户端可以在支持时跟踪位置并重新连接。这种区别很重要：如果 API 可以从光标恢复流，AI API 超时策略的恢复方式将不同于没有恢复契约的普通流。

除非产品为此设计，否则不要在部分用户可见输出后切换模型。从前一个答案中间开始的回退答案通常比清晰的失败消息更糟糕。对于流式聊天，请记录：

字段	重要性
`time_to_first_event_ms`	将模型启动延迟与总完成时间分开
`last_event_at`	显示流在何处变为空闲
`sequence_number` 或光标	在 API 支持时启用安全恢复
`partial_output_committed`	防止在可见输出后进行不安全的重试
`requested_model` 和 `served_model`	显示路由或回退是否改变了行为
`finish_reason` 或终止事件	区分成功和被放弃的流

当主要故障模式是 SSE 形态、客户端断开连接或部分输出处理时，请将此页面与 Flatkey 关于流式 AI API 可靠性的指南结合使用。

队列预算应置于用户请求之外

某些 AI 任务不适合作为同步请求。多步研究、长工具工作流、大文档审查和复杂媒体生成等任务的运行时间可能超过一个 Web 请求应保持打开的时间。超时策略应将这些工作负载转移到排队或后台模式，而不是让用户在一个脆弱的连接上等待。

OpenAI 的后台模式文档描述了异步响应，这些响应可以在 queued 或 in_progress 状态时被轮询，在需要时被取消，并且如果以这种方式创建，可以从后台模式流式传输。即使提供商或网关的实现不同，这也是处理长时间 AI 工作的正确心智模型：用户请求创建一个持久的作业，应用程序应用队列截止时间、轮询频率、取消规则和结果保留策略。

队列预算应定义：

队列字段	策略问题
最大队列存在时间	作业在过时之前可以等待多长时间？
轮询间隔	应用应该以多大频率检查状态而不会产生过多负载？
取消规则	谁可以取消，部分完成的工作会怎样处理？
重复防护	如何防止重试两次创建同一个昂贵的作业？
用户通知	用户是否能看到待处理、失败、已取消或已完成的状态？
成本所有者	哪个密钥、团队、客户或工作流拥有该支出？

正是在这里，AI API 超时策略变成了一项运营策略，而不仅仅是一个 SDK 设置。

重试预算优于回退预算

重试和回退是不同的操作。重试是重复相同的契约。回退则会更改路由、模型、提供商、能力、成本或证据层面。

OpenAI 的 Python 和 JavaScript SDK 自述文件指出，默认情况下，连接错误、408 请求超时、409 冲突、429 速率限制和服务器错误会使用短暂的指数退避策略重试两次。这是很有用的 SDK 行为，但对于那些在此基础上添加了自己的网关重试、队列重试和作业重试的团队来说，可能会感到意外。每一层都要计算在内。

使用如下所示的重试预算：

workflow: support_chat_answer
timeouts:
  connect_ms: 2000
  first_event_ms: 5000
  stream_idle_ms: 20000
  total_ms: 30000
retry:
  sdk_max_retries: 1
  gateway_max_retries: 1
  retry_only_before_partial_output: true
fallback:
  allowed_before_first_event:
    - reviewed_support_backup_route
  blocked_after_partial_output: true
  stop_when:
    - schema_contract_changes
    - tool_support_missing
    - cost_cap_exceeded
    - data_boundary_changes
evidence:
  required:
    - workflow
    - owner_key
    - requested_model
    - served_model
    - timeout_layer
    - retry_attempt
    - fallback_reason
    - usage_units

要了解更深入的回退评估路径，请参阅 Flatkey 的模型回退评估指南。要了解特定于重试的行为，请参阅 Flatkey 的AI API 重试策略指南。

可观察性字段决定了超时是否可调试

没有证据的超时只是一句抱怨。AI API 超时策略应要求有足够的字段来回答失败原因、责任方、模型是否生成了任何内容以及尝试的成本。

证据字段	为何它属于超时策略的一部分
工作流名称	将超时与产品层面关联起来
所有者密钥、团队、客户或环境	分配支出和事件所有权
超时层	区分连接、池、读取、流空闲、队列和回退停止
请求的模型和服务的模型	揭示路由更改和回退
端点族	区分聊天、响应、Anthropic、Gemini、图像、视频和其他形态
请求 ID 或响应/作业 ID	实现提供商、网关和应用之间的关联
重试次数和回退原因	防止隐藏的重试放大
使用单位和成本信号	帮助财务部门审查重复或废弃的工作
部分输出标志	保护用户免受重复的流式答案影响

Flatkey 当前的公共网站将产品定位为统一的模型访问、路由、计费、使用分析和运营控制。当前的价格页面是审查模型访问、路由和计费选项的路径，而 2026 年 7 月 3 日的定价 API 快照公开了包括 openai、anthropic、gemini、image-generation、openai-video 和 video 在内的端点族。请将这些视为过时的证据点，而非永久的可用性声明。在生产部署前，务必验证当前目录并运行小规模的路由测试。