Khắc phục lỗi Anthropic SDK APIConnectionError: Request timed out

Tại sao yêu cầu của bạn bị timeout

Gặp lỗi APIConnectionError: Request timed out thường có nghĩa là script cục bộ của bạn đã ngừng chờ trước khi Claude có thể hoàn tất tạo phản hồi. Theo mặc định, Anthropic SDK đặt giới hạn 60 giây. Mặc dù một phút có vẻ dài, nhưng thường không đủ để Claude 3.5 Sonnet hoặc Opus xử lý các prompt khổng lồ hoặc viết các tài liệu kỹ thuật phức tạp dài 2.000 từ.

anthropic.APIConnectionError: Request timed out.

Các nguyên nhân phổ biến

Khối lượng đầu ra lớn: Yêu cầu một bài đăng blog chi tiết 3.000 từ hoặc toàn bộ mã nguồn thường vượt quá cửa sổ 60 giây.
Cửa sổ ngữ cảnh lớn: Gửi một tài liệu 100k-token yêu cầu vài giây thời gian "pre-fill" trước khi từ đầu tiên được tạo ra.
Proxy hoạt động mạnh: Firewall của doanh nghiệp hoặc bộ cân bằng tải (như Nginx) thường ngắt các kết nối ở trạng thái chờ quá 30 hoặc 60 giây.
Nhiễu mạng (Jitter): Độ trễ cao trên điểm phát sóng di động hoặc VPN bị nghẽn có thể khiến kết nối bị ngắt.

Bước 1: Tăng thời gian Timeout mặc định

Cách khắc phục nhanh nhất là cho SDK thêm thời gian chờ. Đối với hầu hết các ứng dụng production, timeout 2 phút (120 giây) hoặc 5 phút (300 giây) sẽ an toàn hơn nhiều cho các tác vụ phức tạp.

Cấu hình Python

Trong Python, đối số timeout sử dụng đơn vị giây. Bạn có thể thiết lập nó trên toàn cục cho client hoặc ghi đè cho một lời gọi cụ thể.

from anthropic import Anthropic

# Tăng timeout toàn cục lên 2 phút
client = Anthropic(
    api_key="your_api_key",
    timeout=120.0 
)

# Hoặc, đặt timeout 5 phút cho một yêu cầu nặng
response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Phân tích năm tệp PDF 50 trang này..."}],
    timeout=300.0 
)

Cấu hình Node.js

JavaScript SDK sử dụng đơn vị mili giây. Hãy nhân số giây bạn muốn với 1.000.

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: 'my_api_key',
  timeout: 120 * 1000, // 120 giây
});

// Ghi đè cho yêu cầu cụ thể (5 phút)
const message = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20240620',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Tạo một kiến trúc hệ thống đầy đủ.' }],
}, { timeout: 300000 });

Bước 2: Điều chỉnh Network Proxy

Nếu bạn đang ở sau một proxy doanh nghiệp, timeout trong code của bạn có thể không phải là vấn đề. Nhiều proxy có bộ đếm thời gian nội bộ riêng. Nếu code của bạn được đặt thành 300 giây nhưng proxy ngắt kết nối ở giây thứ 60, bạn vẫn sẽ gặp lỗi timeout.

Đảm bảo các biến môi trường của bạn đang hoạt động trong terminal:

export HTTP_PROXY="http://your-proxy-server:8080"
export HTTPS_PROXY="http://your-proxy-server:8080"

Mẹo chuyên nghiệp: Nếu bạn sử dụng Nginx làm reverse proxy, hãy kiểm tra cài đặt proxy_read_timeout. Nó phải bằng hoặc lớn hơn timeout của SDK.

Bước 3: Chuyển sang Streaming (Cách tiếp cận tốt nhất)

Streaming là cách mạnh mẽ nhất để ngăn chặn timeout. Thay vì đợi toàn bộ phản hồi 4.000 token hoàn tất, Claude sẽ gửi dữ liệu theo từng phần. Điều này giữ cho kết nối "hoạt động" và ngăn mạng nghĩ rằng yêu cầu đã bị đình trệ.

Ví dụ về Python Streaming

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Viết một bài nghiên cứu dài."}],
    model="claude-3-5-sonnet-20240620",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Cách kiểm tra giải pháp của bạn

Đừng chỉ đợi lỗi xảy ra lần nữa. Bạn có thể xác minh các cài đặt của mình bằng các bước sau:

Ép buộc xảy ra lỗi: Đặt timeout=0.001. Nếu code của bạn ngay lập tức ném ra lỗi APIConnectionError, bạn biết mình đang chỉnh sửa đúng cấu hình.
Kiểm tra với tải nặng: Đặt timeout thành 120.0 và yêu cầu Claude "Viết một bài tiểu luận 2.000 từ về lịch sử điện toán."
Kiểm tra đồng hồ: Sử dụng đồng hồ bấm giờ. Nếu yêu cầu hoàn tất thành công sau 75 giây, timeout mới của bạn đang hoạt động hoàn hảo.

Danh sách kiểm tra cuối cùng

Cập nhật SDK: Anthropic thường xuyên cải thiện khả năng xử lý kết nối. Chạy pip install -U anthropic hoặc npm install @anthropic-ai/sdk@latest.
Kiểm tra DNS: Nếu timeout xảy ra trong vòng chưa đầy 1 giây, có khả năng đó là vấn đề DNS. Hãy thử ping api.anthropic.com để xem máy của bạn có thể kết nối tới máy chủ hay không.
Logic thử lại (Retry): SDK mặc định thử lại hai lần. Bạn có thể tăng con số này bằng max_retries=5 nếu kết nối internet của bạn đặc biệt không ổn định.