> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexinference.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 截止日期路由

> start_within 字段、flex 竞速以及自动升级到标准层。

`start_within` 是每个 FlexInference 请求的必填字段。它设置了路由器可以等待请求开始的最长时间。当您直接需要某个提供商层级时，请使用 `default`、`priority` 或 `auto`。当您希望 FlexInference 首先尝试在支持 flex 的模型上使用 flex，如果 flex 未能及时启动则升级到标准层时，请使用持续时间。

该字段有四种形式。

## 四种形式

<Tabs>
  <Tab title="default">
    ```json theme={null}
    { "start_within": "default" }
    ```

    路由到提供商的**标准**实时层，采用标准定价：OpenAI 的 `default`、Gemini 的 `standard` 或 Anthropic 的 `standard_only`。适用于任何模型。
  </Tab>

  <Tab title="priority">
    ```json theme={null}
    { "start_within": "priority" }
    ```

    路由到 OpenAI 的 **priority** 层以实现最快启动。将其用于交互式、对延迟敏感的路径。Priority 是最昂贵的层级。适用于任何模型。在 Anthropic 上，这属于**尽力而为**，因为 Claude 没有 priority 层；我们将其映射到 Anthropic 的 `auto`。
  </Tab>

  <Tab title="auto">
    ```json theme={null}
    { "start_within": "auto" }
    ```

    让提供商选择层级。在 OpenAI 上，这是 `service_tier: auto`；在 Anthropic 上，它映射到 Anthropic 的 `auto`。这是提供商的 auto 层，而不是 FlexInference 的自动路由。适用于 **OpenAI 和 Anthropic**。Gemini 没有 auto 层，因此在 Gemini 模型上使用 `auto` 会返回 `400 auto_unsupported_for_gemini`。
  </Tab>

  <Tab title="持续时间">
    ```json theme={null}
    { "start_within": "00h-00m-30s" }
    ```

    在每个端点（包括 `/v1/responses`、`/v1/chat/completions`、`/v1/interactions` 和 `/v1/messages`）上请求 **flex 竞速**（见下文）。FlexInference 首先尝试更便宜的 flex 层，并且仅当 flex 未能在指定时间内启动时才转到标准层。持续时间是请求启动的最大等待时间，格式为 `HHh-MMm-SSs`，每个字段两位数字。它必须介于 **5 秒到 10 分钟**之间（`00h-00m-05s` 到 `00h-10m-00s`）。
  </Tab>
</Tabs>

`default`、`priority` 和 `auto` 将**任何**模型代理到其提供商（OpenAI、Gemini 或 Anthropic）。只有持续时间请求 flex 竞速。如果模型无法使用 flex，持续时间会返回 `400`（`flex_unsupported_for_anthropic` 或 `flex_model_not_capable`）；请改用层级值。

<Note>
  flex 竞速**不适用于 Claude**，因为 Anthropic 没有 flex 层。在 `claude-*`
  模型上使用持续时间 `start_within` 会返回 `400
      flex_unsupported_for_anthropic`。Anthropic 仍然支持 `default`、`priority`
  和 `auto` 层代理请求。
</Note>

<Note>
  持续时间 `start_within` 不能与 `logprobs` 或 `seed`
  等原生 Chat Completions 参数结合使用。请移除这些参数，或改用 `default`、
  `priority` 或 `auto`。
</Note>

## flex 竞速

使用持续时间时，FlexInference 首先尝试提供商的 **flex** 层（OpenAI 或 Gemini）。Flex 按标准费率的一半计费，但容量是尽力而为的。路由器会在您的窗口内等待上游请求开始：

<Steps>
  <Step title="启动 flex">
    FlexInference 将您的请求发送到 flex 层，并在您设置的时间内等待提供商确认请求正在履行。
  </Step>

  <Step title="提交到 flex">
    如果提供商及时启动请求，FlexInference 将提交。您的响应将正常流回，按 flex
    费率计费。响应显示 `"service_tier": "flex"`。
  </Step>

  <Step title="升级到标准层">
    如果 flex 未能及时启动，FlexInference 将取消它并将请求发送到标准层。这是从更便宜的 flex
    层升级到标准层，而不是降级。响应显示 `"service_tier": "default"` (OpenAI) 或
    `"standard"` (Gemini)。
  </Step>
</Steps>

升级到标准层仅在 flex 启动之前发生，即当 flex 返回 `429`（无容量）、任何 `5xx`、启动前失败或在截止日期前未启动时。flex 到标准层的切换是 FlexInference 所做的**唯一**层级更改。提供商回退（您设置一个可选的 `provider` 数组，FlexInference 在某个路由暂时失败后尝试下一个路由）会更改路由，但绝不会更改层级或模型。您命名的任何路由缺少密钥都是配置错误而不是暂时性故障，因此它会返回 `400` 而不是回退。请参阅[提供商路由](/zh/models)。

<Info>
  选择您的用户体验可以容忍的最长持续时间。更长的窗口会给 flex
  更多时间来获胜，从而增加以更便宜费率提供服务的请求份额。
</Info>

## 读取结果

成功的 `200` 响应在每个端点上都包含 Flex 结果头，适用于流式和非流式调用。错误响应则使用错误正文。

| Header                             | 含义                                                                                                                                                                                                              |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-flexinference-flex-requested`   | 当调用者发送持续时间 `start_within` 时为 `true`；当调用者发送 `default`、`priority` 或 `auto` 时为 `false`。                                                                                                                            |
| `x-flexinference-flex-applied`     | 仅当 flex 提供响应时为 `true`。                                                                                                                                                                                          |
| `x-flexinference-flex-reason`      | 机器可读的结果。请参阅下面的值。                                                                                                                                                                                                |
| `x-flexinference-provider-surface` | 规划器选择的提供商表面。值为 `openai.responses`、`openai.chat`、`gemini.interactions` 和 `anthropic.messages`。这可能与调用者端点不同。使用 OpenAI 模型的 `/v1/chat/completions` 调用会报告 `openai.responses`，除非需要原生 Chat 直通，在这种情况下它会报告 `openai.chat`。 |

实时 `x-flexinference-flex-reason` 值如下：

| Reason           | 含义                                                                             |
| ---------------- | ------------------------------------------------------------------------------ |
| `not_requested`  | 请求使用了 `default`、`priority` 或 `auto`；未请求 flex 竞速。                               |
| `flex_committed` | flex 竞速已提交。响应显示 `service_tier: "flex"` 和 `x-flexinference-flex-applied: true`。 |
| `flex_lost_race` | 请求在支持 flex 的模型上使用了持续时间，但 flex 未能及时启动，请求回退到标准层。                                 |

<Note>
  无法运行 flex 竞速的持续时间会返回 `400`（在 `claude-*` 模型上为
  `flex_unsupported_for_anthropic`，在不支持 flex 的 OpenAI/Gemini
  模型上为 `flex_model_not_capable`）；头部原因仅描述运行了 flex
  或未请求 flex 的请求。
</Note>

## 当 flex 池不可用时

flex 层使用共享的、尽力而为的容量。在请求开始之前，当没有容量时，flex 可能会返回 `429`，返回任何 `5xx`，在启动前失败，或错过截止日期。FlexInference 随后会将请求发送到标准层。

在极少数情况下，flex 在请求被接受并开始流式传输**之后**失败。FlexInference 会暴露该故障。对于流式请求，您会收到一个终端 `response.failed` 事件。对于非流式请求，您会收到 `502`。它在提交后不会重试，因为这可能会掩盖不完整的请求。如果您遇到这种情况，请**重试**，或使用 `default`、`priority` 或 `auto` 跳过 flex。

## 传输重试

flex 竞速决定哪个层级服务您的请求。传输重试决定当该层级未能启动时会发生什么。添加一个可选的 `retry` 对象，FlexInference 会在瞬态上游故障时等待并重新命中已确定的层级，而不是将错误返回给您。

```json theme={null}
{ "retry": { "count": 2 } }
```

| Field     | Required | Values                                  | 含义                                                         |
| --------- | -------- | --------------------------------------- | ---------------------------------------------------------- |
| `count`   | yes      | integer, `1` to `5`                     | 第一次尝试失败后，对已确定层级的重新命中次数。                                    |
| `backoff` | no       | `"exponential"` (default) or `"linear"` | 尝试之间的等待模式。指数退避从 0.5 秒开始，每次翻倍，最长 8 秒；线性退避每次增加 0.5 秒，最长 8 秒。 |
| `jitter`  | no       | boolean (default `true`)                | 分散等待时间以平滑突发。抖动只会缩短等待时间，绝不会延长。                              |

无效的 `retry` 会返回 `400` [`invalid_retry`](/zh/errors#invalid_retry)。

FlexInference 仅重试来自已确定层级的真正的预提交传输故障：真正的 `429`、真正的 `5xx` 或从未打开的连接（[`upstream_unavailable`](/zh/errors#upstream_unavailable)）。它不会重试客户端 `4xx`、上游认证失败（[`upstream_auth_failed`](/zh/errors#upstream_auth_failed)）、上游超时（[`upstream_timeout`](/zh/errors#upstream_timeout)）或客户端取消的请求。这些要么在重新命中时以相同方式失败，要么意味着调用者已经离开。

重试会重新命中确定您请求的层级，而不是 flex 阶段。对于 `default`、`priority` 或 `auto` 请求，这是您命名的层级。对于输掉 flex 竞速的持续时间请求，这是您升级到的标准层级。flex 尝试和升级是 flex 竞速自己的工作，绝不计入 `count`。层级升级和重试同一层级是相互独立的步骤，它们可以串联：flex 输给标准层，然后标准层可以自行重试。

当提供商发送 `Retry-After` 头部时，FlexInference 会等待该时间，而不是退避计划，并将其限制在 60 秒内，以防止不良值阻塞您的请求。

<Note>
  重试仅限于预提交。一旦层级提交，它就会停止，这对于流式和非流式调用都是 `200`
  状态行。一旦第一个字节正在传输给您，FlexInference 绝不会重试，这与 flex
  竞速在提交后遵循的规则相同。流中故障或提交 `200` 后的非流式 `502`
  会直接传递给您。
</Note>

服务器端 `retry` 与客户端中的任何重试循环是分开的，两者可以叠加。FlexInference SDK 不会重试，但默认情况下，标准的 OpenAI 或 Anthropic SDK 会重试两次。客户端在服务器 `count` 为 `3` 的基础上重试两次，会导致多达六次上游尝试，因为每次客户端尝试都会运行完整的服务器预算。当您设置 `retry` 时，FlexInference 会在响应上标记 `x-flexinference-retries`，其中包含它运行的重新命中次数，这样您就可以调低客户端自己的 `max_retries`。

## 计费

使用 BYOK，FlexInference 在服务器端使用您存储的加密提供商密钥；您无需为每个请求发送提供商密钥。您的提供商会根据提供请求的层级费率向您的账户收费。当 flex 提交时，您支付 flex 费率；升级后，您支付标准费率。flex 尝试在失败前可能会消耗少量 token。您的提供商会以与您直接调用 flex 相同的方式计费该使用量，FlexInference 会将其包含在使用量中。FlexInference 不会对您的 token 加收任何费用。它会收取您节省金额的 20%，如果没有节省则不收取任何费用。

## FlexInference 的更改

FlexInference 可能会更改层级。它不会更改您请求的含义或提供商的结果。它绝不会重写提供商的状态或消息。它仅规范化错误信封：错误以您调用的端点（OpenAI 上的 responses 和 chat，Anthropic 上的 messages，Google 上的 interactions）的形状返回，携带提供商的状态和消息，以便您的 SDK 可以解析它。请参阅[错误](/zh/errors)。

<Note>
  `start_within` 是**必填项**。如果没有它，请求将返回 `400
      missing_start_within`，包括使用指向我们基本 URL 的普通 OpenAI SDK
  时。如果您发送 FlexInference 无法读取的值，您将收到
  `invalid_start_within`。有效值为 `"default"`、`"priority"`、`"auto"`
  或持续时间，例如 `"00h-00m-30s"`。以前允许使用裸词 `standard`，但现在不再允许，因此请改用
  `default`。有关完整列表，请参阅[错误](/zh/errors)。
</Note>