Base URL 配置错误：API 地址、路径和兼容模式怎么排查
Base URL 错了会伪装成 401、404、timeout、JSON 解析失败或 HTML 响应。先确认协议、域名、/v1 路径和平台兼容模式。
排查结论
先用最小请求隔离问题：只保留 API Key、Base URL、模型名和一条 ping 消息。最小请求失败，先修配置；最小请求成功，再回到业务代码排查并发、上下文和部署环境。
1. 问题现象
- 返回 404、HTML 页面、Cannot GET /v1/chat/completions、JSON parse error 或连接超时。
- Key 和模型名确认无误，但请求始终打不到正确 API。
- 浏览器能打开官网，代码调用 API 却失败，因为官网域名不是 API endpoint。
- 把 /v1 写了两次，或 SDK 自动拼接路径后变成 /v1/v1/chat/completions。
2. 最可能原因
3. 快速排查清单
打印最终请求 URL
确认最终请求是 https://域名/.../chat/completions，而不是官网页面或重复路径。
确认是否 OpenAI 兼容
只有明确支持 OpenAI 兼容的服务，才使用 OpenAI SDK 的 chat.completions.create。
用 /models 或最小聊天请求探测
平台支持 /v1/models 时先测模型列表，不支持时按控制台给出的完整示例测试。
Base URL 和模型名一起切换
换供应商时不要只换 Key；Base URL、模型名、Key 必须成套。
检查部署环境变量
本地 .env 正确不代表线上 Secret 正确；线上常见问题是漏了路径或多了斜杠。
4. 对应 API 的特殊情况
OpenAI SDK 示例常用 base_url=https://api.deepseek.com，SDK 会拼接 /v1/chat/completions。
OpenAI 兼容模式常用 https://dashscope.aliyuncs.com/compatible-mode/v1，少了 compatible-mode/v1 会请求到错误接口。
OpenAI 兼容地址是 https://api.moonshot.cn/v1，模型名用 moonshot-v1-* 或控制台可见模型。
OpenAI 兼容地址可用 https://api.hunyuan.cloud.tencent.com/v1，密钥和模型名按控制台说明填写。
常见地址是 https://ark.cn-beijing.volces.com/api/v3，但不同区域和接入点可能不同，复制控制台参数最稳。
直连官方 API 不等于 OpenAI 兼容 Base URL。使用官方 SDK，或确认你使用的网关明确支持 OpenAI 兼容。
5. 可复制的修复示例
# DeepSeek
export BASE_URL="https://api.deepseek.com"
export MODEL_ID="deepseek-chat"
# 通义千问 DashScope 兼容模式
# export BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
# export MODEL_ID="qwen-plus"
# Kimi
# export BASE_URL="https://api.moonshot.cn/v1"
# export MODEL_ID="moonshot-v1-8k"
# 豆包火山方舟：以控制台实际区域和接入点为准
# export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
# export MODEL_ID="你的推理接入点ID"from openai import OpenAI
import os
# 正确：base_url 只写平台要求的根路径
client = OpenAI(
api_key=os.environ["API_KEY"],
base_url=os.environ["BASE_URL"].rstrip("/"),
)
response = client.chat.completions.create(
model=os.environ["MODEL_ID"],
messages=[{"role": "user", "content": "ping"}],
)
print(response.choices[0].message.content)