面向正在接入 OpenAI API、Claude API 的 Python 开发者。本文不展开复杂架构，只保留最关键的链路检测、超时配置、错误判断和网络出口建议，方便直接放进项目里做排查。

很多开发者接入 OpenAI API 或 Claude API 时，第一步通常是安装 SDK、配置 API Key、复制官方 Demo。最小示例跑通以后，看起来问题已经解决，但真正接进业务后，经常会遇到另一类问题：

• 本地偶尔能请求成功，部署到服务器后开始超时。
• 短 prompt 正常，长文本生成或流式输出中途断开。
• 同一段代码昨天能跑，今天出现 connection error。
• 团队里 A 同事能调通，B 同事一直失败。

这些现象不一定是 SDK 写错，也不一定是模型不可用。Python 程序发出一次 API 请求，中间会经过 DNS 解析、TCP 建连、TLS 握手、HTTP 客户端连接池、网络出口、API 服务端处理和响应返回等环节。任意一层不稳定，最后都可能表现为超时、连接失败或响应中断。

所以，国内开发者更需要关注的是一套可检测、可配置、可复现的 API 网络链路方案，而不是只确认“代码能不能调用一次”。

一、先判断问题在哪一层

排查 API 请求失败时，可以先按下面几层拆开看：

层级	典型问题	常见表现
DNS	域名解析慢、解析失败	请求刚开始就卡住
TCP/TLS	建连慢、握手失败	ConnectTimeout、连接错误
HTTP 客户端	代理、连接池、超时配置不合理	ProxyError、PoolTimeout
API 服务	Key、权限、额度、限流	401、403、429、5xx
长请求	响应时间长、连接中途断开	ReadTimeout、streaming 中断

这里最容易混淆的是 ConnectTimeout 和 ReadTimeout。

ConnectTimeout 通常说明连接还没建立成功，重点查 DNS、网络出口、代理配置、服务器安全组。

ReadTimeout 通常说明连接已经建立，但服务端响应或返回链路耗时过长，重点查长 prompt、模型处理时间、streaming、链路稳定性。

二、最小链路检测脚本

下面这段代码只做三件事：检查 DNS、检查 TCP、检查 OpenAI API 的基础 endpoint 是否可达。Claude API 也可以用同样思路扩展。

代码不追求复杂，目的是让你先判断：问题到底发生在网络层，还是 API Key / 权限 / 限流层。

import os
import socket
import time

import httpx
from dotenv import load_dotenv

load_dotenv()

OPENAI_HOST = "api.openai.com"
OPENAI_MODELS_URL = "https://api.openai.com/v1/models"
PROXY_URL = os.getenv("HTTPS_PROXY")


def cost_ms(start):
    return int((time.time() - start) * 1000)


def check_dns(host):
    start = time.time()
    try:
        records = socket.getaddrinfo(host, 443, type=socket.SOCK_STREAM)
        ips = sorted({item[4][0] for item in records})
        print(f"[OK] DNS {host} {cost_ms(start)}ms {ips[:3]}")
    except Exception as exc:
        print(f"[FAIL] DNS {host} {cost_ms(start)}ms {exc!r}")


def check_tcp(host, port=443):
    start = time.time()
    try:
        with socket.create_connection((host, port), timeout=8):
            print(f"[OK] TCP {host}:{port} {cost_ms(start)}ms")
    except Exception as exc:
        print(f"[FAIL] TCP {host}:{port} {cost_ms(start)}ms {exc!r}")


def check_openai_api():
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        print("[FAIL] missing OPENAI_API_KEY")
        return

    timeout = httpx.Timeout(connect=10, read=30, write=10, pool=10)
    with httpx.Client(proxy=PROXY_URL or None, timeout=timeout) as client:
        start = time.time()
        try:
            resp = client.get(
                OPENAI_MODELS_URL,
                headers={"Authorization": f"Bearer {api_key}"},
            )
            print(f"[API] status={resp.status_code} cost={cost_ms(start)}ms")
            print(resp.text[:200])
        except httpx.ConnectTimeout:
            print("[FAIL] connect timeout：优先检查 DNS、TCP、代理或网络出口")
        except httpx.ReadTimeout:
            print("[FAIL] read timeout：连接已建立，但响应返回过慢")
        except httpx.ProxyError as exc:
            print(f"[FAIL] proxy error：{exc!r}")


if __name__ == "__main__":
    check_dns(OPENAI_HOST)
    check_tcp(OPENAI_HOST)
    check_openai_api()

运行方式：

pip install httpx python-dotenv
python llm_network_check.py

如果 DNS 和 TCP 都失败，优先处理本机网络、服务器出口或代理配置；如果 DNS/TCP 正常，但 API 返回 401、403、429，则重点检查 Key、权限、额度和请求频率。

三、OpenAI/Claude SDK 的超时配置怎么写

实际项目里，不建议每个业务文件都自己配置一遍 client。更稳妥的方式是单独封装一个客户端工厂，把 API Key、超时、重试和网络出口统一管理。

OpenAI Python SDK 支持自定义 HTTP client，可以把 HTTPX 的 timeout 和 proxy 放进去：

import os
import httpx
from openai import OpenAI, DefaultHttpxClient

timeout = httpx.Timeout(connect=10, read=60, write=20, pool=10)

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    http_client=DefaultHttpxClient(
        proxy=os.getenv("HTTPS_PROXY") or None,
        timeout=timeout,
    ),
    max_retries=2,
)

response = client.responses.create(
    model=os.getenv("OPENAI_MODEL"),
    input="用一句话解释 API 网络链路检测的意义。",
)

print(response.output_text)
print("request_id:", response._request_id)

Claude Python SDK 可以设置 timeout 和重试次数：

import os
import httpx
from anthropic import Anthropic

client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY"),
    timeout=httpx.Timeout(connect=10, read=60, write=20, pool=10),
    max_retries=2,
)

message = client.messages.create(
    model=os.getenv("CLAUDE_MODEL"),
    max_tokens=128,
    messages=[{"role": "user", "content": "Reply with pong only."}],
)

print(message.content)
print("request_id:", message._request_id)

这里有两个建议：

• 不要把代理地址、账号密码、API Key 写死在代码里，统一放到环境变量或配置中心。
• 一定要记录 request_id，后续定位服务端错误、权限问题和工单排查时非常有用。

四、长请求建议优先考虑 streaming

普通短请求对网络连续性的要求相对低，长文本生成、代码生成、文件分析、Agent 工具调用则不同。如果请求长时间没有返回数据，中间链路可能出现空闲连接中断。

这种场景建议优先考虑 streaming，让服务端持续返回事件，客户端可以边接收边处理。

OpenAI 示例：

stream = client.responses.create(
    model=os.getenv("OPENAI_MODEL"),
    input="写一段 API 超时排查说明。",
    stream=True,
)

for event in stream:
    print(event)

Claude 示例：

with client.messages.stream(
    model=os.getenv("CLAUDE_MODEL"),
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一段 API 网络排查说明。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

streaming 不是让网络“变快”，而是降低长时间无响应带来的等待风险，也方便前端展示增量结果。

五、错误码怎么判断

表现	优先排查
401	API Key 是否正确加载
403	模型权限、账号权限、服务可用范围
413	请求体过大，文件或 prompt 需要压缩
429	速率限制、并发过高、额度不足
500/529	服务端异常或繁忙，记录 request id 后重试
ConnectTimeout	DNS、TCP、代理、网络出口
ReadTimeout	长请求、streaming、返回链路稳定性
ProxyError	proxy 协议、账号、密码、端口

如果是团队项目，建议日志里至少记录这些字段：

• provider：OpenAI / Claude
• model：模型名称
• status_code：HTTP 状态码
• error_type：异常类型
• latency_ms：请求耗时
• request_id：请求 ID
• environment：local / test / prod

有了这些字段，排查时才能判断问题集中在某个模型、某台服务器，还是某个网络出口。

六、团队环境下的网络出口建议

个人测试可以临时调通，但团队长期使用 OpenAI、Claude 等 API 时，不能完全依赖个人电脑的网络状态。更推荐把网络出口做成工程配置的一部分。

推荐结构如下：

业务代码
  ↓
OpenAI / Claude SDK
  ↓
HTTPX timeout / retry
  ↓
统一跨境网络出口
  ↓
API 服务
  ↓
日志监控 / request_id / 错误归因

统一出口后，排查会简单很多：代码层看 SDK 和参数，网络层看 DNS、TCP、超时和出口质量，API 层看状态码、request id 和服务端返回。

七、总结

国内开发者访问 OpenAI/Claude API，不应该只停留在最小 Demo 能不能跑通。真正影响项目稳定性的，往往是网络链路、HTTP 客户端配置、超时重试和日志可观测性。

建议落地时按这四步做：

1. 用最小脚本检测 DNS、TCP 和 API endpoint。
2. 在 SDK 中显式配置 timeout、proxy 和 max retries。
3. 区分 connect timeout、read timeout、401、403、429 等错误。
4. 团队项目统一网络出口和日志字段，保证问题可复现、可定位。

这样写出来的 API 接入方案，才不是一次性 Demo，而是一套可以长期维护的工程方案。

参考资料

• OpenAI Python SDK：https://github.com/openai/openai-python
• OpenAI API Quickstart：https://developers.openai.com/api/docs/quickstart
• Claude Client SDKs：https://docs.anthropic.com/en/api/client-sdks
• Claude API Errors：https://docs.anthropic.com/en/api/errors
• HTTPX Proxies：https://www.python-httpx.org/advanced/proxies/
• HTTPX Timeouts：https://www.python-httpx.org/advanced/timeouts/