> ## 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.

# 从 Vercel AI Gateway 迁移

> 将 Vercel AI Gateway 的路由切换到 Phaseo Gateway，同时保留 AI SDK 或 OpenAI 兼容应用的行为。

如果你已通过 Vercel AI SDK 或 OpenAI 兼容客户端使用 Vercel AI Gateway，最稳妥的方式是保持应用逻辑不变，先只替换与提供商的连接边界。

## 变更内容

| 设置 | 之前 | 之后 |
| - | - | - |
| Gateway URL | `https://ai-gateway.vercel.sh/v1` | `https://api.phaseo.app/v1` |
| API 密钥 | Vercel AI Gateway 密钥 | `PHASEO_API_KEY` |
| AI SDK 提供商 | 现有配置 | 直接使用 AI SDK 时改为 `@phaseo/ai-sdk-provider` |
| 应用流程 | 现有生成逻辑 | 首次迁移时保持不变 |

## 开始之前

* 当前的 Vercel AI Gateway 基础 URL 和密钥配置。
* 在本地、预发布和生产环境中配置 `PHASEO_API_KEY`。
* 一组小规模提示词或集成测试，覆盖非流式、流式请求以及依赖的工具调用路径。

## 1) 记录当前 Gateway 接入点

找到应用创建模型提供商或 API 客户端的统一位置，将其作为迁移点。

* 找到应用使用的提供商或客户端工厂。
* 列出当前在生产环境中使用的模型 ID。
* 记录重试、超时和备用路由的默认设置。
* 确认 edge 和服务器运行环境是否都需要相同的配置变更。
* 找出应改为 Gateway 预设的共享提示词或参数默认值，避免分散在各个 AI SDK 调用中。

## 2) 替换端点和密钥

对于大多数 OpenAI 兼容客户端，只需替换基础 URL 和密钥。

<CodeGroup>
  ```typescript TypeScript theme={null}
  // OpenAI-compatible client before
  import OpenAI from "openai";

  const before = new OpenAI({
    apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY,
    baseURL: "https://ai-gateway.vercel.sh/v1",
  });
  ```

  ```typescript TypeScript theme={null}
  // OpenAI-compatible client after
  import OpenAI from "openai";

  const after = new OpenAI({
    apiKey: process.env.PHASEO_API_KEY,
    baseURL: "https://api.phaseo.app/v1",
  });
  ```

  ```typescript TypeScript theme={null}
  // Official Phaseo provider for the Vercel AI SDK
  import { generateText } from "ai";
  import { createPhaseo } from "@phaseo/ai-sdk-provider";

  const phaseo = createPhaseo({
    apiKey: process.env.PHASEO_API_KEY,
    baseURL: "https://api.phaseo.app/v1",
  });

  const { text } = await generateText({
    model: phaseo("openai/gpt-4.1-mini"),
    prompt: "Generate a migration checklist.",
  });
  ```

  ```bash cURL theme={null}
  curl -s "https://api.phaseo.app/v1/chat/completions" \
    -H "Authorization: Bearer $PHASEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4.1-mini",
      "messages": [{"role":"user","content":"Hello"}]
    }'
  ```
</CodeGroup>

## 3) 确认行为一致

使用相同提示词集调用旧路径和新路径，然后比较延迟、输出格式和令牌用量。

* 验证非流式文本生成。
* 使用生产环境相同的代码路径验证流式数据块处理。
* 如果应用依赖工具调用，请验证相应路径。
* 确认应用级错误映射未发生变化。
* 将持久的路由默认值和提供商限制移至[预设](../guides/presets.mdx)或[路由和回退](../guides/routing-and-fallbacks.mdx)，避免在每个模型工厂中重复实现。

## 4) Vercel AI SDK 和 Gateway 检查清单

增加流量前，请完成以下检查：

* 基础 URL 已更新为 `https://api.phaseo.app/v1`。
* 所有之前使用 Vercel Gateway 密钥的运行环境均已配置 `PHASEO_API_KEY`。
* 应用直接使用 Vercel AI SDK 时，已接入官方提供商 `@phaseo/ai-sdk-provider`。
* AI SDK 的主要文本生成路径已在预发布环境通过。
* 应用级流式测试无需修改即可通过。
* 如有使用，已重新检查工具调用和结构化输出流程。
* 已用一小组提示词比较旧路径和新路径的输出。
* 仍可仅通过配置更改或功能标志回滚。
* 在适用情况下，已将共享提示词和路由默认值移入预设。
* 已重新检查通过 `GET /v1/generations?id=<request_id>` 查询生成记录；当 `replay_supported=true` 时，可使用已保存的 `replay_request` 负载重放失败请求。

## 5) 低风险发布计划

1. 通过功能标志或按百分比逐步放量发布。
2. 从内部流量或极小比例的生产流量开始。
3. 监控延迟、错误率以及令牌用量和成本的变化。
4. 至少在一个发布周期内保留两套配置。

## 验证命令

```bash theme={null}
curl -s "https://api.phaseo.app/v1/health"
curl -s "https://api.phaseo.app/v1/models" -H "Authorization: Bearer $PHASEO_API_KEY"
```

然后：

* 运行应用的主要文本生成集成测试。
* 在预发布环境运行一项流式测试。
* 全量切换前，比较主要提示词在旧路径和新路径上的输出。

## 后续步骤

* [从 OpenRouter 迁移](./from-openrouter.mdx)
* [快速入门](../quickstart.mdx)
* [示例](../guides/examples.mdx)


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