Base URL 问题

Base URL 是所有 API 请求的基础地址。配置错误会导致请求失败或指向错误的服务。以下是常见的 Base URL 问题及解决方案。

URL 格式错误

缺少 /v1 路径

现象

请求返回 404 Not Found。

原因

Base URL 末尾缺少 /v1 路径段，导致请求路径不完整。

错误示例

# 错误：缺少 /v1
curl "https://api.example.com/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

正确示例

# 正确：Base URL 包含 /v1，请求路径只写 /chat/completions
curl "https://api.example.com/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

多了 /v1 路径

现象

请求返回 404 Not Found。

原因

在 Base URL 已包含 /v1 的情况下，请求路径中又重复添加了 /v1。

错误示例

# 错误：Base URL 和请求路径都包含 /v1
curl "https://api.example.com/v1/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY"

解决方案

• 方式一：Base URL 包含 /v1，请求路径从 /chat/completions 开始

  BASE_URL="https://api.example.com/v1"
  curl "$BASE_URL/chat/completions" \
    -H "Authorization: Bearer $API_KEY"

• 方式二：Base URL 不包含 /v1，请求路径从 /v1/chat/completions 开始

  BASE_URL="https://api.example.com"
  curl "$BASE_URL/v1/chat/completions" \
    -H "Authorization: Bearer $API_KEY"

选定一种方式后保持一致，不要混用。

HTTPS 证书问题

现象

请求报错 SSL certificate problem 或 CERTIFICATE_VERIFY_FAILED。

原因

• 服务器 SSL 证书过期或未正确配置
• 证书链不完整
• 客户端不信任服务器证书

解决方案

1. 确认证书状态：在浏览器中打开 Base URL 查看证书是否正常

2. 临时跳过验证（仅用于测试，不推荐生产环境使用）：

   # cURL
   curl -k "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY"

   # Python
   import requests
   requests.get(f"{BASE_URL}/v1/models", headers={"Authorization": f"Bearer {API_KEY}"}, verify=False)

3. 生产环境建议：联系管理员更新服务器 SSL 证书

域名解析失败

现象

请求报错 ENOTFOUND 或 Could not resolve host。

原因

• Base URL 中的域名拼写错误
• DNS 解析未生效（新域名）
• 本地 DNS 配置问题
• 网络隔离导致无法解析域名

解决方案

1. 检查域名拼写：确认 Base URL 中的域名是否正确

2. 测试域名解析：

   # 使用 ping 或 nslookup 检查域名
   nslookup api.example.com
   # 或
   dig api.example.com

3. 检查本地 DNS：

   # 尝试使用公共 DNS
   curl --resolve api.example.com:443:<IP地址> "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY"

4. 检查网络环境：如果你在公司内网或使用 VPN，确认是否需要配置代理才能访问外部服务

如何确认正确的 Base URL

方法一：查看管理后台

1. 登录管理后台
2. 在首页或 设置 页面查看 Base URL
3. Base URL 通常格式为 https://你的域名/v1

方法二：测试连通性

# 测试 Base URL 是否可达
curl -I "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY"

• 返回 200 → Base URL 正确且可访问
• 返回 404 → 检查路径是否正确
• 连接超时 → 检查域名或网络

方法三：检查常见路径对照

接口	正确路径
模型列表	{BASE_URL}/v1/models
Chat 补全	{BASE_URL}/v1/chat/completions
Embeddings	{BASE_URL}/v1/embeddings
图片生成	{BASE_URL}/v1/images/generations

如果你的 Base URL 已包含 /v1，则路径中不要重复添加。