Python OpenAI SDK 接入 TimRouter

已有 OpenAI 兼容 Python 项目，可用 OpenAI客户端显式设置 TimRouter 的 base_url与 Key。本教程先验证最小 Chat Completions 请求；Responses、工具调用或其它模态需要分别确认目标模型与接口支持。

更新于 2026-10-03。

1. 前置条件

准备符合当前 OpenAI SDK 要求的 Python 环境；在项目虚拟环境中安装，避免混用系统 Python 和其它项目依赖。
准备 TimRouter Key、余额，以及支持 Chat Completions 的完整模型 ID。
在实时价格页确认模型分组与计费单位；首次验证使用短提示词。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade openai
python -m pip show openai

Windows PowerShell 在创建虚拟环境后使用 .venv\Scripts\Activate.ps1激活。已有项目先检查依赖锁定与迁移影响，不要直接在生产环境升级。

2. 设置 Key 与模型

从控制台选择当前分组有权限的模型，复制完整模型 ID。先在当前终端设置 TIMROUTER_API_KEY 和 TIMROUTER_MODEL；下面的示例只读取环境变量，缺少任一项就停止，不会使用默认模型。密钥不要写入代码仓库。

macOS / Linux 的 Bash 或 Zsh 可通过交互输入：

printf 'TimRouter API Key: '
read -r -s TIMROUTER_API_KEY
printf '\n模型 ID（从控制台复制）: '
read -r TIMROUTER_MODEL
export TIMROUTER_API_KEY TIMROUTER_MODEL
: "${TIMROUTER_API_KEY:?未设置 TIMROUTER_API_KEY}"
: "${TIMROUTER_MODEL:?未设置 TIMROUTER_MODEL}"

在运行 Python 的同一终端设置变量。Windows PowerShell 对应 $env:TIMROUTER_API_KEY和 $env:TIMROUTER_MODEL。Base URL 填到 /v1，不要再追加 /chat/completions。

3. 最小 Chat Completions 请求

保存为 timrouter_check.py并运行 python timrouter_check.py。Key 与模型没有默认值；首次核账关闭自动重试，便于对应单次请求。

import os
import sys
from openai import OpenAI, APIConnectionError, APIStatusError

api_key = os.environ.get("TIMROUTER_API_KEY", "").strip()
model = os.environ.get("TIMROUTER_MODEL", "").strip()
if not api_key or not model:
    sys.exit("先设置 TIMROUTER_API_KEY 和 TIMROUTER_MODEL")

client = OpenAI(
    api_key=api_key,
    base_url="https://api.timrouter.com/v1",
    timeout=30.0,
    max_retries=0,
)
try:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "只回复 OK"}],
    )
except APIConnectionError:
    sys.exit("连接失败或超时：检查网络，并核对控制台是否已产生用量")
except APIStatusError as exc:
    sys.exit(f"HTTP {exc.status_code}; request_id={exc.request_id}")

if not response.choices:
    sys.exit("返回中没有 choices，请检查接口兼容性")
content = response.choices[0].message.content
if not content or not content.strip():
    sys.exit("未返回文本回复，请检查模型和接口兼容性")
print(content)
print("model:", response.model)
print("usage:", response.usage)
print("request_id:", response._request_id)

此示例使用当前客户端写法 OpenAI(...)。旧教程中的 openai.api_base属于旧式全局配置，不应与这里的客户端代码混用。第三方框架是否读取 OPENAI_BASE_URL或其它变量，需查它自己的版本文档。

4. 验收返回与费用

进程成功完成，并输出实际回复；没有 choices 或空回复时继续检查返回数据，不能只以没有异常判定成功。
核对返回模型、usage 与请求 ID。兼容端点不一定提供全部字段；缺失字段不能当作零用量或免费调用。
在控制台用同一时间、Key 分组与模型定位调用记录，按核账方法对应扣费。
需要 Responses 时，先确认 /v1/responses与模型支持，再按 Responses 文档接入；不要仅因 SDK 有 responses 方法就认为网关一定支持。

5. 常见 SDK 错误

现象	先检查
ModuleNotFoundError / 无 OpenAI 客户端	检查当前解释器、虚拟环境和 openai 包版本；安装命令使用同一 python -m pip。
401 / AuthenticationError	环境变量是否传入、Key 是否有效，是否错用了其它提供商 Key。
404 / NotFoundError	Base URL 是否为 /v1，目标模型与 Chat Completions 接口是否存在并有权限。
400 / 参数不支持	从最小 messages 请求开始，按模型文档逐项加入 temperature、推理或多模态参数。
429 / RateLimitError	根据错误正文区分速率和额度原因，检查余额、Key 限额与并发。
APIConnectionError / 超时 / 5xx	保存时间和请求 ID（如有），先核对用量，再决定是否重试；不要直接把超时当作未计费。

OpenAI 官方 SDK 资料

OpenAI SDK 的参数说明适用于客户端；TimRouter 的实际模型权限、字段与计费以接口返回及控制台记录为准。