玄枢API玄枢API

玄枢API

OpenAI SDK 迁移结论

迁移需要修改 Base URL 与 API Key，并核对模型、流式、错误重试和回滚；这不是 100% 无缝替换。

最后验证日期:

连接与鉴权

统一 OpenAI 兼容 Base URL: https://www.xuanshuapi.com/v1

OpenAI 兼容接口使用 Authorization: Bearer <YOUR_API_KEY>；Claude Messages 也支持 x-api-key: <YOUR_API_KEY>；Gemini v1beta 使用 x-goog-api-key: <YOUR_API_KEY>。

export OPENAI_API_KEY="<YOUR_API_KEY>"
export OPENAI_BASE_URL="https://www.xuanshuapi.com/v1"

OpenAI SDK 迁移结论

玄枢API 提供 OpenAI 兼容接口，但并非 100% 无缝：模型、参数、错误与流式事件可能存在差异，应先灰度验证。

并非每个模型都支持相同参数，请先查询 Models。

1. 保存配置并切换 Base URL 与 API Key

先保留原配置，再使用独立的 XUANSHU_API_KEY 与 XUANSHU_MODEL 做灰度验证。

export ORIGINAL_OPENAI_BASE_URL="${OPENAI_BASE_URL:-https://api.openai.com/v1}"
export ORIGINAL_OPENAI_API_KEY="<YOUR_ORIGINAL_KEY>"
export XUANSHU_API_KEY="<YOUR_API_KEY>"
export XUANSHU_MODEL="<MODEL_FROM_MODELS>"

2. Python 初始化与实际请求

安装 openai 包后运行以下最小 Chat Completions 请求。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XUANSHU_API_KEY"],
    base_url="https://www.xuanshuapi.com/v1",
)
response = client.chat.completions.create(
    model=os.environ["XUANSHU_MODEL"],
    messages=[{"role": "user", "content": "Reply with OK"}],
)
print(response.choices[0].message.content)

3. JavaScript 初始化与实际请求

安装 openai 包后运行以下 ESM 示例。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XUANSHU_API_KEY,
  baseURL: "https://www.xuanshuapi.com/v1",
});
const response = await client.chat.completions.create({
  model: process.env.XUANSHU_MODEL,
  messages: [{ role: "user", content: "Reply with OK" }],
});
console.log(response.choices[0].message.content);

4. 发现并验证模型列表

先查询当前 Key 可见模型，把返回的模型 ID 写入 XUANSHU_MODEL，再运行 SDK 示例。

curl https://www.xuanshuapi.com/v1/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"

5. 验证流式输出

流式调用要逐块消费并处理空增量、超时和中断；先确认非流式请求成功。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XUANSHU_API_KEY,
  baseURL: "https://www.xuanshuapi.com/v1",
});
const stream = await client.chat.completions.create({
  model: process.env.XUANSHU_MODEL,
  messages: [{ role: "user", content: "Count to three" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

6. 错误处理与有限重试

401/403 不应自动重试；仅对 429、超时和可恢复 5xx 使用有上限的指数退避。

import os
import random
import time
from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI, RateLimitError

client = OpenAI(
    api_key=os.environ["XUANSHU_API_KEY"],
    base_url="https://www.xuanshuapi.com/v1",
    max_retries=0,
)

for attempt in range(4):
    try:
        response = client.chat.completions.create(
            model=os.environ["XUANSHU_MODEL"],
            messages=[{"role": "user", "content": "Reply with OK"}],
        )
        break
    except RateLimitError:
        if attempt == 3:
            raise
        time.sleep((2 ** attempt) + random.random())
    except (APITimeoutError, APIConnectionError):
        if attempt == 3:
            raise
        time.sleep((2 ** attempt) + random.random())
    except APIStatusError as error:
        if error.status_code < 500 or attempt == 3:
            raise
        time.sleep((2 ** attempt) + random.random())

print(response.choices[0].message.content)

7. 回滚

保留官方端点和原 Key 的独立引用；验证失败时恢复原环境变量并核对迁移期间用量。

export ORIGINAL_OPENAI_BASE_URL="https://api.openai.com/v1"
export ORIGINAL_OPENAI_API_KEY="<YOUR_ORIGINAL_KEY>"

# Roll back
export OPENAI_BASE_URL="$ORIGINAL_OPENAI_BASE_URL"
export OPENAI_API_KEY="$ORIGINAL_OPENAI_API_KEY"
unset XUANSHU_API_KEY XUANSHU_MODEL