概述

大多数 OpenAI 兼容调用迁移到 UOUODUO Gateway 只需要三步。

替换 base URL。

替换 API key。

确认模型 ID。

请求体结构可以基本保持不变。

三步迁移

1. 替换 base URL

把原来的 OpenAI base URL：

https://api.openai.com/v1

替换为：

https://api.example.com/v1

2. 替换 API key

在 `/app/keys` 创建新的 API key。

将应用里的环境变量改为：

export UOUODUO_API_KEY="sk-xxx..."

请求时使用：

Authorization: Bearer $UOUODUO_API_KEY

3. 确认模型 ID

如果你继续使用 OpenAI 模型，模型 ID 通常可以保持不变。

如果切到其他供应商模型，请在 `/models` 查找目标模型 ID。

也可以请求 `/v1/models` 获取当前账户可见模型。

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UOUODUO_API_KEY"],
    base_url="https://api.example.com/v1",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "给我一个迁移检查清单。"}],
)

Node.js 示例

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.UOUODUO_API_KEY,
  baseURL: 'https://api.example.com/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: '给我一个迁移检查清单。' }],
});

行为差异

迁移后需要注意：

• 某些模型 ID 可能映射到不同供应商
• 流式 chunk 可能透传上游的少量额外字段
• 错误 message 可能包含网关或上游上下文
• 费用以 UOUODUO 控制台记录为准
• 多模态字段取决于目标模型是否支持

模型映射

不要假设所有模型都支持完全相同的参数。

例如一个模型支持 vision，不代表另一个同名或同类模型也支持。

迁移前建议先读 `/docs/api/models` 和 `/models`。

streaming 差异

OpenAI 兼容 streaming 使用 `data:` 和 `[DONE]`。

不同上游在 tool calling、reasoning 字段和 usage 尾包上可能存在差异。

应用层解析时应忽略未知字段。

不要把完整 chunk schema 写死成只允许固定字段。

tool calling

如果你使用 tools 或 function calling，请先用测试环境验证。

重点确认：

• tool name 是否符合目标模型限制
• arguments 是否是完整 JSON 字符串
• 并行 tool calls 是否被支持
• 模型是否会返回空 content 加 tool calls

费用验证

迁移后先跑小流量。

在 `/app/logs` 检查单次请求费用。

在 `/app/usage` 检查聚合趋势。

确认费用符合预期后再切换全部流量。

故障排查清单

• 401：确认 API key 是否来自 `/app/keys`
• 404：确认模型 ID 是否可见
• 429：检查限流和重试策略
• 402 或余额相关错误：检查 Credits 和项目预算
• 502 或 503：换同能力模型验证是否为上游问题
• 流式中断：查看 `/docs/guides/streaming`