UnderSky 文档

迁移 OpenAI 集成

通过修改 base URL、API Key、模型 ID 和运行检查,将现有的 OpenAI SDK 或 HTTP 集成迁移到 UnderSky。

UnderSky 兼容 OpenAI 的请求格式,覆盖 Chat Completions、Responses、Embeddings 和图片生成。大多数集成只需要修改四处配置。

修改客户端配置

将 base URL 设为 https://api.undersky.ai/v1,并从密钥管理器读取 UnderSky Key。

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UNDERSKY_API_KEY"],
    base_url="https://api.undersky.ai/v1",
)

把 API Key 保留在服务端,不要放进浏览器代码。

选择支持的模型

验证集成时先使用 auto。需要固定路由时,从UnderSky 模型目录选择模型,并在配置中固定该 ID。

response = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Hello"}],
)

不要直接复制 OpenAI 的模型 ID,先确认它出现在当前的公开模型列表中。

保留流式响应和工具调用

stream、tools、tool_choice 和 response_format 在兼容 OpenAI 的 Chat 端点中可用。保留已有的事件解析和工具执行循环,再根据 Chat 参考发送请求。

更新错误处理

为 UnderSky 的额度和网关状态增加处理逻辑:

  • 402 表示账户需要充值。
  • 429 需要有上限的指数退避。
  • 幂等请求遇到 5xx 可以重试,并先查看服务状态。
  • 401 表示进程拿到的 Key 无效或不可用。

使用错误码指南和速率限制指南设置重试上限。

上线前验证

  1. 不带认证调用 GET /v1/models,确认选择的模型在列表中。
  2. 使用短提示词发送一次非流式请求。
  3. 发送一次流式请求,确认解析器在 [DONE] 停止。
  4. 在 Dashboard → Settings → Credit & Usage 确认用量记录。
  5. 设置生产预算前查看定价和服务状态。

快速开始还提供 curl、Python、Node、图片、JSON 和恢复示例。

目录