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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# 自动路由

> 发送 phaseo/auto，让 Phaseo 在你的工作区规则范围内为每个请求选择模型。

发送 `"model": "phaseo/auto"`，Phaseo 就会根据工作负载、你的工作区目标及其价格上限，为每个请求选择一个模型。自动路由目前处于 Alpha 阶段，仅向部分工作区开放。

```json theme={null}
{
  "model": "phaseo/auto",
  "input": "Review this TypeScript function for correctness."
}
```

响应中的 `model` 字段会显示由哪个模型作答。

## 如何选择模型

```mermaid theme={null}
flowchart TD
  all["所有符合条件的生产文本模型"] --> rules["工作区规则：模型模式和支出档位"]
  rules --> checks["常规检查：端点、提供商、隐私、地区、护栏、熔断器"]
  checks --> classify["分类器读取请求：工作负载构成和复杂度"]
  classify --> score["为候选模型评分：基准测试匹配度、目标、价格、延迟、提供商健康状况"]
  score --> pick["调用排名第一的模型"]
  pick -->|"429 或 5xx，且已开启回退"| next["尝试排名下一位的模型"]
```

1. **候选模型。** Phaseo 从所有具有已知标准价格的生产文本模型开始，只保留与你的模型模式和支出档位相符的模型。
2. **检查。** 每个候选模型都必须通过与固定模型请求相同的端点、工作区模型、提供商、隐私、护栏和熔断器检查。
3. **分类器。** 一个固定的低成本模型会读取请求，并返回工作负载构成（代码、推理、工具使用等）、复杂度分数和置信度。它从不自己选择模型。请求中的工具和结构化输出会作为可信事实传给它。
4. **评分。** 复杂度决定了可能给出可接受答案的最低能力模型，再加上一定余量。然后，Phaseo 将非自报的目录基准测试与你的目标，以及每个候选模型当前的价格、延迟、健康状况和可靠性结合起来。缺失的数据按中性处理；它永远不会扩大候选名单。

请求无法更改工作区的目标、支出档位或模式。指定了固定模型的请求会完全跳过自动路由。

## 配置自动路由

**1. 打开自动路由**

前往**控制台 -> 设置 -> 路由 -> 自动路由**。

**2. 选择目标**

| 目标 | 最看重 |
| - | - |
| `balanced` | 质量、价格、延迟和可靠性之间的实用平衡。 |
| `quality` | 与工作负载相关的基准测试结果。 |
| `cost` | 更低的输入和输出 token 价格。 |
| `latency` | 更低的近期提供商延迟。 |

**3. 选择支出档位**

每个档位都是标准级文本价格的硬性上限，单位为每百万 token 的 USD 价格。高于上限的模型永远不会被考虑。

| 支出档位 | 最高输入价格 | 最高输出价格 |
| - | -: | -: |
| 经济 | \$0.10 | \$0.50 |
| 标准 | \$0.30 | \$1.50 |
| 高级 | \$1 | \$5 |
| 不限价格 | 无 | 无 |

**自定义**可以自行设置这两个上限。

**4. 缩小模型范围（可选）**

添加模式，例如 `anthropic/*`、`openai/gpt-5.*` 或确切的模型 ID。

**5. 允许回退并保存**

开启回退后，遇到 `429`、`500`、`502`、`503` 或 `504` 时，Phaseo 会尝试排名下一位的模型。每次回退都会重新经过所有检查。客户端错误不会切换模型。

使用 CLI：`phaseo routing auto update --objective <o> --spend-profile <p> --allowed-patterns <list> --allow-fallbacks`，用 `phaseo routing auto get` 读取配置。对应的 API 是 `PATCH /v1/routing/auto`。

> [!WARNING]
>
> 支出档位和模式决定哪些模型符合条件。它们并不保证质量，因此请用你自己的工作负载检查最终的模型构成。

## 分类器请求

每个 `phaseo/auto` 请求都会在同一工作区和计费身份下，向分类器模型发起一个独立的子请求。它会以 `purpose=auto_routing_classifier` 和父请求 ID 单独出现在请求日志中，并单独计量。

如果分类器失败、超时或返回无效数据，Phaseo 会改用本地基于规则的分类器（代码、推理、工具使用、结构化输出、翻译、摘要或通用），因此主请求仍会执行。

## 隐私和地区限制

请求上的数据限制同样适用于自动路由：

* 如果设置了 `provider.require_zero_data_retention: true`，或者工作区或密钥护栏只允许零数据保留的提供商，那么只有拥有此类提供商的模型才会进入候选名单。
* 所需地区会与每个候选模型的提供商逐一核对。
* 分类器请求带有相同的限制，以及 `only` 和 `ignore` 提供商列表。如果分类器模型无法满足这些限制，Phaseo 会使用本地分类器。

如果仅因数据驻留要求而没有任何可用模型，请求会以 `403 model_region_unavailable` 和 `unmet_requirements` 失败，与固定模型的行为相同。如果还有模型因其他原因被排除，请求会以 `400 unsupported_model_or_endpoint` 失败。

## 查看路由决策

请求详情会显示工作负载、目标、所选模型、回退顺序、每个候选模型的分数和各因素分数、基准测试 ID、排除项以及算法版本。追踪记录不包含提示词或响应内容。

## 与其他路由方式结合

* **动态路由。** 由已关联的[动态路由](https://phaseo.app/docs/zh-Hans/v1/guides/routing-and-fallbacks.md#attach-routing-rules-to-api-keys)选定的固定模型优先。该覆盖会被记录，并且该请求不会使用自动路由的回退。
* **请求级回退。** `phaseo/auto` 自行管理排序后的回退，因此不能与 [`models` 列表](./routing-and-fallbacks#request-level-model-fallbacks)组合使用，也不能出现在其中。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.