Timeout dan percobaan ulang OpenAI Python SDK: atur untuk CheapTokens

Skrip Anda memanggil model, tidak ada yang kembali, dan sepuluh menit kemudian masih menunggu. Itulah default OpenAI Python SDK: timeout 10 menit dan 2 percobaan ulang. Untuk mengubahnya, lewati timeout=30.0 dan max_retries=2 ke OpenAI(...), timpa keduanya per panggilan dengan client.with_options(...), dan batasi jawaban dengan max_tokens.

README SDK (diperiksa 27 Oktober 2026) mendokumentasikan semua ini. Di bawah ini diterapkan ke endpoint CheapTokens, https://api.cheaptokens.dev/v1, yang berbicara dalam format OpenAI Chat Completions. Detail pengaturan itu ada di Permintaan API pertama Anda dengan CheapTokens dan dokumentasi.

Apa yang dilakukan SDK saat Anda tidak mengatur apa pun#

Dua default penting. Timeout adalah 10 menit. Percobaan ulang adalah 2, dengan backoff eksponensial singkat, untuk kesalahan koneksi dan untuk respons 408, 409, 429 dan 5xx, dan hanya ketika body permintaan dapat dikirim ulang dengan aman. Permintaan yang timeout juga dicoba ulang.

Jadi setiap percobaan mendapat timeout-nya sendiri, dan kasus terburuk kira-kira timeout dikalikan jumlah percobaan, ditambah jeda di antaranya:

• default: 600 × 3 = 1800 detik, setengah jam
• timeout=30.0, max_retries=2: 30 × 3 = 90 detik

Misalkan endpoint web harus menjawab dalam 30 detik. Dengan default, endpoint dapat menggantung selama setengah jam sebelum kode Anda melihat kesalahan. Coba pada pengaturan lain sebelum membaca lebih lanjut.

Atur timeout dan max_retries pada klien#

Perbaikan paling sederhana adalah mengatur keduanya sekali, saat Anda membuat klien:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
    timeout=30.0,      # seconds per attempt
    max_retries=2,     # 0 turns retries off
)

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Summarize this ticket in two sentences: ..."}],
    max_tokens=800,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

max_retries harus berupa bilangan bulat non-negatif. timeout menerima float, atau objek httpx Timeout jika Anda ingin batas terpisah untuk koneksi dan pembacaan. README dari branch main saat ini mengimpor httpx2 untuk itu, versi lama menggunakan httpx, jadi jalankan pip show openai dan periksa mana yang digunakan instalasi Anda. Float biasa tidak memerlukan impor dan berfungsi baik dengan cara apa pun.

Gunakan id model lengkap dari dokumentasi CheapTokens, deepseek-ai/DeepSeek-V4-Flash-0731 di sini: id berbeda antar penyedia. Model ini menerima hingga 32.768 token keluaran per jawaban dan memiliki konteks 380K, itulah sebabnya baris max_tokens di atas ada dengan sengaja. Lebih lanjut tentang itu di bawah, dan tentang model di DeepSeek murah.

Timpa untuk satu permintaan#

Satu klien, pekerjaan berbeda. Balasan chat harus menyerah dengan cepat, ringkasan malam hari bisa menunggu. Alih-alih membuat klien kedua, turunkan satu untuk panggilan tersebut:

quick = client.with_options(timeout=5.0, max_retries=0)
resp = quick.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Reply with one word: ok"}],
    max_tokens=5,
)

with_options mengembalikan salinan dengan nilai baru dan membiarkan client tidak berubah. Mengatur max_retries=0 adalah pilihan yang tepat ketika kode Anda sendiri sudah mencoba ulang, misalnya antrean pekerjaan yang memasukkan ulang tugas. Jika tidak, kedua lapisan akan berlipat ganda: 3 percobaan SDK di dalam 3 percobaan antrean adalah 9 permintaan untuk satu tugas.

Tangkap kesalahan yang penting#

Setelah percobaan ulang habis, SDK memunculkan pengecualian. Setiap kelas kesalahan mewarisi dari openai.APIError, dan permintaan yang gagal membawa request_id, yang Anda catat:

import openai

def ask(prompt: str) -> str | None:
    try:
        r = client.chat.completions.create(
            model="deepseek-ai/DeepSeek-V4-Flash-0731",
            messages=[{"role": "user", "content": prompt}],
            max_tokens=800,
        )
        return r.choices[0].message.content
    except openai.APITimeoutError:
        print("timed out after retries")
    except openai.RateLimitError as e:
        print("429, slow down:", e.request_id)
    except openai.APIConnectionError:
        print("cannot reach the API")
    except openai.APIStatusError as e:
        print("HTTP", e.status_code, e.request_id)
    return None

Urutannya dari sempit ke luas. APIStatusError mencakup respons 4xx atau 5xx apa pun, jadi jika berada di depan ia akan menelan RateLimitError. Ide yang sama untuk timeout: ia berada di atas kesalahan koneksi umum. Dalam skrip batch, return None adalah intinya: catat prompt, lanjut ke yang berikutnya, dan jalankan ulang yang gagal di akhir.

Ketika timeout terjadi dan percobaan ulang habis, inilah tampilan pengecualiannya:

Untuk kasus 429 secara detail, termasuk menunggu antar percobaan, lihat 429 Too Many Requests dari API AI.

Batasi max_tokens agar jawaban panjang tidak lepas kendali#

Timeout menghentikan penantian. Itu tidak membuat model menulis lebih sedikit. Tanpa max_tokens, model dengan batas jawaban 32.768 token bebas menulis balasan yang sangat panjang, dan balasan panjang itu lambat. Tetapkan batas yang sesuai dengan pekerjaan: 800 untuk ringkasan tiket, 5 untuk ya/tidak.

Biayanya adalah jawaban bisa terpotong. Periksa resp.choices[0].finish_reason: length berarti batas tercapai sebelum model selesai. Mengapa jawaban AI berhenti di tengah kalimat? membahasnya. Jika Anda melakukan streaming jawaban, kata-kata pertama tiba lebih awal dan penantian terasa lebih singkat, lihat Respons streaming di Python.

Apa dampak percobaan ulang pada tagihan#

Percobaan ulang adalah permintaan baru. Jika suatu percobaan telah diproses, itu adalah permintaan terpisah dengan tokennya sendiri. Misalkan ringkasan tiket adalah 1.500 token masuk dan 400 keluar: satu permintaan berbiaya $0.000063 dengan harga hari ini, dan tabel harga lengkap memuat model lainnya. Harga tetap per model, tanpa jam sibuk, jadi percobaan ulang pukul 3 pagi berbiaya sama dengan pukul 12 siang.

Geser slider ke batch Anda sendiri:

Tabel menunjukkan satu lintasan. Jika sepersepuluh batch memerlukan percobaan kedua, tambahkan sepersepuluh. Percobaan ulang adalah asuransi murah ketika kegagalan jarang terjadi, dan kebiasaan mahal ketika Anda mengatur max_retries=10 terhadap endpoint yang terus gagal.

Sebelum Anda merilis#