用 Python SDK 切换 base_url 时最容易忽略的五件事

改一行代码就够了？基本上是

from openai import OpenAI

client = OpenAI(
    base_url="https://站点域名/v1",
    api_key="你的key",
)

但下面五件事会在之后找上门。

一、base_url 要不要带 /v1

这是最高频的问题。

SDK 的行为是：它会把 base_url 和具体路径拼接。所以：

# 正确（多数情况）
base_url="https://站点域名/v1"
# 实际请求 → https://站点域名/v1/chat/completions

# 如果站点要求不带 v1
base_url="https://站点域名"
# 实际请求 → https://站点域名/chat/completions

判断方法：两种都试，看哪个通。或者直接看站点文档给的示例。

二、超时设置

SDK 默认超时通常偏短（几十秒到几分钟）。但：

• 推理模型响应可能超过 5 分钟
• 长文档处理也可能很慢

建议：按请求类型分别设超时，而不是全局一个值。

client = OpenAI(
    base_url=...,
    api_key=...,
    timeout=60.0,      # 普通请求
    max_retries=2,     # 明确设置重试次数
)

注意 max_retries：SDK 默认会自动重试。如果站点不稳定，无脑重试会放大账单。生产环境建议显式设置。

三、重试策略与幂等性

自动重试听起来安全，但要考虑：

• 重试的请求会不会被重复计费？（多数站不会，但部分成功的情况可能已计费）
• 你的业务是否幂等？（生成类请求重试会产生多份结果）

建议：明确设置重试次数（比如 2 次），并对重试做日志，方便事后对账。

四、环境变量与硬编码

# 不推荐 —— 换站要改代码、重新部署
client = OpenAI(base_url="https://某个站.com/v1", api_key="sk-xxx")

# 推荐 —— 换站只改配置
import os
client = OpenAI(
    base_url=os.environ["API_BASE_URL"],
    api_key=os.environ["API_KEY"],
)

这是本文最重要的一条。 把 base_url 做成配置项，意味着：

• 换站不需要改代码
• 可以做多站切换、灰度、故障转移
• 站点跑路时的影响仅限于余额，不影响业务

五、并发控制

SDK 本身不限制并发 —— 你的代码有多少并发就有多少。这在异步场景下容易失控。

# 用信号量限制并发
import asyncio
sem = asyncio.Semaphore(5)   # 最多 5 并发

async def call_api(...):
    async with sem:
        return await client.chat.completions.create(...)

为什么重要：多数中转站对单账号有并发上限。超了不会报「并发超限」，而是表现为部分请求随机失败 —— 很难排查。

一个完整的配置模板

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("API_BASE_URL", "https://默认站/v1"),
    api_key=os.environ["API_KEY"],
    timeout=float(os.environ.get("API_TIMEOUT", "60")),
    max_retries=int(os.environ.get("API_MAX_RETRIES", "2")),
)

# 建议：把实际使用的 base_url 打进日志，方便对账时确认走的是哪个站
import logging
logging.info("API base_url = %s", client.base_url)

最后那行日志很实用：多站切换时，出问题能立刻知道当时走的是哪个通道。

相关阅读

• 中转站突然报错或变慢，怎么判断是谁的问题
• 怎么给项目配置多家 API 互备
• 账号被限流或封禁：中转站风控的常见触发条件