文本生成/模型选择与回退

说明如何在 OpenAI、Claude、Gemini 间选择模型并配置回退链路。

模型选择与回退

在生产环境中为 OpenAI、Claude、Gemini 三类模型建立稳定的编排与回退链路。

前置条件

  • 已获取 UniGateway API Key
  • 已了解业务场景对延迟、成本、输出质量的要求

发现可用模型

调用 GET /v1/models 获取实时模型列表。不要假设外部文档中的模型名在当前账号中一定可用。

curl https://api.unigateway.ai/v1/models \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

每次部署或模型目录变更后，先刷新模型列表再固定使用。

建立回退链

按能力优先级排列回退顺序。文本生成示例链路：

  1. gpt-5.4
  2. claude-sonnet-4-6
  3. gemini-3-pro-preview

最终链路以实时模型列表和延迟/成本目标为准。将模型映射放在配置层，不要硬编码在业务代码里。

使用保守兼容的请求体

优先使用通用的 /v1/chat/completions 基础请求：

{
  "model": "gpt-5.4",
  "messages": [
    { "role": "user", "content": "请用 3 点总结。" }
  ],
  "temperature": 0.2
}

除非已做逐模型校验，否则不要在 fallback 链里依赖提供方特有参数。

配置路由策略

错误类型处理方式
429（限流）或 5xx（服务异常）在同模型内做封顶退避重试
重试预算耗尽切换到下一个回退模型
每次尝试记录 model、request_id、延迟、token 用量

详细重试参数参见 错误处理与重试。

生命周期治理

结合 UniGateway 模型元数据中的生命周期状态制定策略：

状态处理方式
AVAILABLE正常接收流量
PREVIEW验证通过后接入
DEPRECATED / SUNSET不新增正式流量
UNAVAILABLE从回退链中移除

当 fallback 使用率异常飙升时需升级处理，即使整体成功率看起来仍然正常。

Example request

Run it in your stack

Pick the SDK style that matches your app and copy the snippet directly into your project.

from openai import OpenAI

client = OpenAI(api_key="<YOUR_UNIGATEWAY_API_KEY>", base_url="https://api.unigateway.ai/v1")
resp = client.chat.completions.create(model="claude-sonnet-4-6", messages=[{"role":"user","content":"hello"}])
print(resp.choices[0].message.content)