Timeout bukan satu angka. Strategi timeout AI API untuk produksi membutuhkan anggaran terpisah untuk menghubungkan, membaca respons, streaming event token, menunggu dalam antrean, melakukan retry dengan aman, dan menentukan kapan fallback harus berhenti. Jika anggaran itu digabung, provider yang lambat, connection pool yang terblokir, atau stream yang setengah terbuka bisa terlihat seperti insiden yang sama.
Tujuan strategi timeout AI API adalah membuat kegagalan tetap terbatas dan dapat diamati. Permintaan chat yang dilihat pengguna mungkin memerlukan token pertama yang cepat dan batas berhenti yang tegas. Tugas riset latar belakang mungkin memerlukan deadline antrean dan polling. Pekerjaan ekstraksi skema mungkin memerlukan satu retry pada route yang sama sebelum fallback. Setiap alur kerja membutuhkan anggaran sendiri, dan setiap timeout harus meninggalkan bukti untuk engineering, finance, dan pemilik produk.
Flatkey cocok untuk pekerjaan reliabilitas ini karena kebijakan timeout lebih mudah ditinjau ketika akses model, routing, billing, analitik penggunaan, dan kontrol operasional ditangani melalui satu gateway. Gunakan checklist di bawah sebagai kebijakan aplikasi, lalu validasi baris model Flatkey saat ini, family endpoint, bukti penggunaan, dan perilaku route sebelum mengirim traffic produksi.
Strategi timeout AI API dalam satu tabel
Mulailah dengan menetapkan satu pemilik dan satu kondisi berhenti untuk setiap lapisan timeout.
| Lapisan timeout | Yang dilindungi | Anggaran awal | Aturan retry | Aturan fallback | Bukti yang dicatat |
|---|---|---|---|---|---|
| Connect | DNS, TLS, keterjangkauan gateway, dan penyiapan socket | Pendek, biasanya lebih rendah daripada anggaran request | Retry hanya jika tidak ada request body yang diterima | Gunakan backup route hanya ketika family endpoint setara | connect_ms, route, host, kelas error |
| Pool atau queue acquire | Menunggu worker lokal, connection, atau slot rate-limit | Sangat pendek untuk pekerjaan interaktif | Jangan retry secara membabi buta; kurangi concurrency terlebih dahulu | Queue atau kurangi beban sebelum mengganti model | usia queue, waktu tunggu pool, concurrency, pemilik |
| Request/read | Menunggu body respons setelah request dikirim | Terkait dengan UX atau deadline pekerjaan | Satu atau dua retry terbatas untuk kegagalan sementara | Fallback hanya ke route yang mempertahankan kontrak output | ID request, status, read timeout, usage jika ada |
| Stream first event | Menunggu SSE pertama atau event token pertama | Lebih rendah daripada deadline total stream | Retry sebelum output yang terlihat pengguna dimulai | Fallback hanya sebelum output parsial dikomit | latensi event pertama, model yang diminta, model yang dilayani |
| Stream idle | Jeda antar chunk stream setelah output dimulai | Berdasarkan gap antar-event normal | Resume hanya ketika API mendukungnya; jika tidak, berhenti dengan bersih | Hindari mengganti model di tengah jawaban | sequence terakhir, gap idle, penanda output parsial |
| Background queue | Pekerjaan jangka panjang di luar request pengguna | Deadline eksplisit dan interval polling | Polling sampai state terminal atau deadline | Escalate atau cancel sebelum pekerjaan duplikat | response/job ID, status, usia queue, alasan cancel |
| Fallback stop | Mencegah retry menjadi biaya yang tak terkendali | Batas keras untuk attempt dan spend | Berhenti setelah anggaran habis | Tinjauan manusia untuk perubahan alur kerja berisiko tinggi | attempts, alasan fallback, biaya, pemilik |
Tabel ini adalah inti dari strategi timeout AI API. Angka yang tepat harus berasal dari traffic nyata, tetapi pemisahan ini harus sudah ada sebelum insiden produksi pertama.
Bangun anggaran dari maksud alur kerja
Jangan menyalin satu nilai timeout ke setiap fitur AI. Timeout yang terasa longgar untuk evaluasi latar belakang bisa tidak dapat diterima dalam chat dukungan. Timeout yang baik untuk jawaban teks bisa terlalu singkat untuk workflow tool dengan konteks panjang. Tulis strategi timeout AI API berdasarkan maksud alur kerja:
- Chat interaktif membutuhkan anggaran event pertama, anggaran respons total, dan pesan pengguna yang ramah saat anggaran habis.
- UX streaming membutuhkan anggaran event pertama dan idle, karena stream yang terhubung tetapi berhenti menghasilkan event berbeda dari respons lengkap yang lambat.
- Ekstraksi terstruktur membutuhkan anggaran retry validitas skema, bukan loop retry umum.
- Pekerjaan agentic atau yang berat pada tool membutuhkan deadline antrean, batas panggilan tool, jalur cancel, dan catatan polling.
- Tinjauan finance, procurement, atau compliance membutuhkan fallback yang konservatif karena mengganti model dapat mengubah risiko, biaya, bukti, atau status persetujuan.
Panduan timeout OpenAI saat ini untuk SDK resmi menyatakan bahwa request default time out setelah 10 menit, dan SDK Python maupun JavaScript menyediakan opsi timeout. Default ini berguna untuk diketahui, tetapi tidak boleh menjadi kebijakan aplikasi. Tim produksi tetap memerlukan anggaran workflow yang lebih ketat untuk pengalaman pengguna, biaya, dan respons insiden.
Anggaran connect dan pool harus gagal cepat
Anggaran connect menjawab pertanyaan sempit: apakah client dapat mencapai gateway atau endpoint provider cukup cepat untuk memulai request? Anggaran ini biasanya harus jauh lebih pendek daripada anggaran read. Jika penyiapan connection gagal, tidak ada model yang menghasilkan apa pun, sehingga keputusan retry risikonya lebih rendah daripada retry setelah respons parsial.
Tim Python yang menggunakan HTTPX dapat mengekspresikannya dengan jelas karena HTTPX memisahkan timeout connect, read, write, dan pool. OpenAI Python SDK juga menerima objek httpx.Timeout, sehingga aplikasi dapat menjaga anggaran connect dan read tetap terpisah:
import os
import httpx
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url="https://router.flatkey.ai/v1",
timeout=httpx.Timeout(
timeout=20.0,
connect=2.0,
read=10.0,
write=10.0,
pool=1.0,
),
max_retries=1,
)Bagian yang penting bukan nilai contoh tersebut. Bagian yang penting adalah bahwa strategi timeout AI API tidak menghabiskan 20 detik untuk menemukan bahwa socket tidak dapat dibuka atau bahwa pool koneksi lokal sudah jenuh.
Untuk Node.js, OpenAI JavaScript SDK menyediakan opsi timeout dalam milidetik, dan Node juga menyediakan AbortSignal.timeout(delay) untuk API yang menerima abort signal. Gunakan pola itu agar batas waktu aplikasi tetap eksplisit alih-alih bergantung pada pemanggil yang tak berbatas.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: "https://router.flatkey.ai/v1",
timeout: 20_000,
maxRetries: 1,
});Anggap timeout koneksi sebagai sinyal infrastruktur. Jika nilainya melonjak, periksa DNS, TLS, keterjangkauan gateway, batas pool, kejenuhan worker lokal, dan kebijakan egress sebelum mengubah model.
Anggaran read melindungi biaya dan pengalaman pengguna
Anggaran read adalah waktu maksimum yang akan ditunggu aplikasi untuk respons setelah permintaan diterima. Di sinilah beban kerja AI berbeda dari API JSON biasa: model mungkin sah-sah saja lambat, output bisa panjang, atau prompt dapat memicu pekerjaan tool. Karena itu, timeout read harus ditetapkan dari deadline alur kerja, bukan dari default library.
Gunakan aturan berikut:
| Alur kerja | Aturan anggaran read | Yang dilakukan saat timeout |
|---|---|---|
| Chat atau dukungan | Anggaran berdasarkan kesabaran pengguna dan SLO layanan | Tampilkan status timeout yang mulus, catat permintaan, coba ulang hanya sebelum output terlihat oleh pengguna |
| Ekstraksi batch | Anggaran dari deadline job dan kapasitas antrean | Coba ulang rute yang sama sekali, lalu tandai record untuk ditinjau |
| Kode atau penalaran | Anggaran dari kompleksitas tugas dan batas tool | Pertimbangkan mode latar belakang jika tugas memang berjalan lama |
| Keuangan atau pengadaan | Anggaran dari SLA peninjauan | Berhenti dan antrekan daripada diam-diam mengubah rute |
| Otomasi internal | Anggaran dari deadline dependensi downstream | Gagal lebih awal agar pemanggil bisa melakukan kompensasi |
Strategi timeout AI API juga harus membatasi ukuran output, panggilan tool, dan upaya fallback. Timeout read saja tidak mengendalikan biaya jika lapisan retry menciptakan pekerjaan duplikat.
Anggaran streaming membutuhkan dua jam
Streaming tidak selesai hanya dengan menaikkan timeout permintaan. Respons AI yang di-stream memiliki setidaknya dua jam:
- Timeout event pertama: berapa lama pengguna menunggu sebelum event stream atau token pertama.
- Timeout idle: berapa lama aplikasi menoleransi keheningan setelah streaming dimulai.
Referensi OpenAI API menjelaskan streaming sebagai server-sent events ketika stream diaktifkan. Untuk background responses, OpenAI juga mendokumentasikan streaming dengan sequence number sehingga klien dapat melacak posisi dan melakukan reconnect jika didukung. Perbedaan itu penting: jika API bisa melanjutkan stream dari cursor, strategi timeout AI API dapat pulih dengan cara yang berbeda dibandingkan stream biasa tanpa kontrak resume.
Jangan ganti model setelah sebagian output sudah terlihat oleh pengguna kecuali produk memang dirancang untuk itu. Jawaban fallback yang dimulai di tengah jawaban sebelumnya biasanya lebih buruk daripada pesan kegagalan yang bersih. Untuk chat yang di-stream, log:
| Field | Mengapa ini penting |
|---|---|
time_to_first_event_ms | Memisahkan latensi awal model dari total waktu penyelesaian |
last_event_at | Menunjukkan di mana stream menjadi idle |
sequence_number atau cursor | Memungkinkan resume yang aman saat API mendukungnya |
partial_output_committed | Mencegah retry yang tidak aman setelah output terlihat |
requested_model dan served_model | Menunjukkan apakah routing atau fallback mengubah perilaku |
finish_reason atau event terminal | Membedakan keberhasilan dari stream yang ditinggalkan |
Pasangkan halaman ini dengan panduan Flatkey tentang keandalan streaming AI API ketika mode kegagalan utama adalah bentuk SSE, disconnect klien, atau penanganan output parsial.
Anggaran antrean harus berada di luar request pengguna
Beberapa tugas AI tidak cocok sebagai request sinkron. Riset multi-langkah, alur kerja tool yang panjang, peninjauan dokumen besar, dan pembuatan media yang kompleks dapat berjalan lebih lama daripada yang semestinya dibiarkan terbuka oleh sebuah request web. Kebijakan timeout harus memindahkan beban kerja tersebut ke mode antrean atau background alih-alih membuat pengguna menunggu pada satu koneksi yang rapuh.
Dokumentasi mode background OpenAI menjelaskan Responses asinkron yang dapat dipoll saat berada dalam status queued atau in_progress, dibatalkan saat diperlukan, dan di-stream dari background mode ketika dibuat dengan cara itu. Itulah model mental yang tepat untuk pekerjaan AI jangka panjang meskipun implementasi provider atau gateway berbeda: request pengguna membuat job yang tahan lama, dan aplikasi menerapkan deadline antrean, cadence polling, aturan pembatalan, serta kebijakan retensi hasil.
Anggaran antrean harus mendefinisikan:
| Bidang queue | Pertanyaan kebijakan |
|---|---|
| Usia maksimum queue | Berapa lama pekerjaan dapat menunggu sebelum dianggap usang? |
| Interval polling | Seberapa sering aplikasi harus memeriksa status tanpa menimbulkan beban berlebih? |
| Aturan pembatalan | Siapa yang dapat membatalkan, dan apa yang terjadi pada pekerjaan parsial? |
| Pencegah duplikasi | Bagaimana Anda mencegah retry membuat pekerjaan mahal yang sama dua kali? |
| Notifikasi pengguna | Apakah pengguna melihat pending, failed, cancelled, atau completed? |
| Pemilik biaya | Kunci, tim, pelanggan, atau alur kerja mana yang memiliki pengeluaran tersebut? |
Di sinilah strategi timeout AI API menjadi kebijakan operasional, bukan sekadar pengaturan SDK.
Anggaran retry sebelum anggaran fallback
Retry dan fallback adalah tindakan yang berbeda. Retry mengulangi kontrak yang sama. Fallback mengubah rute, model, penyedia, kapabilitas, biaya, atau permukaan bukti.
README Python dan JavaScript SDK OpenAI menyatakan bahwa error koneksi, timeout permintaan 408, konflik 409, batas laju 429, dan error server di-retry dua kali secara default dengan exponential backoff singkat. Itu perilaku SDK yang berguna, tetapi dapat mengejutkan tim yang menambahkan retry gateway sendiri, retry queue, dan retry job di atasnya. Hitung setiap lapisan.
Gunakan anggaran retry seperti ini:
workflow: support_chat_answer
timeouts:
connect_ms: 2000
first_event_ms: 5000
stream_idle_ms: 20000
total_ms: 30000
retry:
sdk_max_retries: 1
gateway_max_retries: 1
retry_only_before_partial_output: true
fallback:
allowed_before_first_event:
- reviewed_support_backup_route
blocked_after_partial_output: true
stop_when:
- schema_contract_changes
- tool_support_missing
- cost_cap_exceeded
- data_boundary_changes
evidence:
required:
- workflow
- owner_key
- requested_model
- served_model
- timeout_layer
- retry_attempt
- fallback_reason
- usage_unitsUntuk jalur evaluasi fallback yang lebih mendalam, gunakan panduan Flatkey tentang evaluasi fallback model. Untuk perilaku khusus retry, gunakan panduan Flatkey tentang strategi retry AI API.
Bidang observabilitas menentukan apakah timeout dapat di-debug
Timeout tanpa bukti hanyalah keluhan. Strategi timeout AI API harus mewajibkan cukup banyak field untuk menjawab apa yang gagal, siapa pemiliknya, apakah model menghasilkan sesuatu, dan berapa biaya percobaan tersebut.
| Bidang bukti | Mengapa harus ada di kebijakan timeout |
|---|---|
| Nama workflow | Menghubungkan timeout ke permukaan produk |
| Owner key, tim, pelanggan, atau lingkungan | Menetapkan pengeluaran dan kepemilikan insiden |
| Lapisan timeout | Memisahkan connect, pool, read, stream idle, queue, dan penghentian fallback |
| Model yang diminta dan model yang dilayani | Mengekspos perubahan rute dan fallback |
| Famili endpoint | Memisahkan chat, responses, Anthropic, Gemini, image, video, dan bentuk lainnya |
| Request ID atau response/job ID | Memungkinkan korelasi provider, gateway, dan aplikasi |
| Jumlah retry dan alasan fallback | Mencegah amplifikasi retry yang tersembunyi |
| Satuan penggunaan dan sinyal biaya | Membantu keuangan meninjau pekerjaan duplikat atau yang ditinggalkan |
| Flag output parsial | Melindungi pengguna dari jawaban streamed yang duplikat |
Situs publik Flatkey saat ini memposisikan produk di sekitar akses model terpadu, routing, billing, analitik penggunaan, dan kontrol operasional. Halaman pricing saat ini adalah jalur tinjauan untuk akses model, routing, dan opsi billing, dan snapshot API pricing 3 Juli 2026 menampilkan famili endpoint termasuk openai, anthropic, gemini, image-generation, openai-video, dan video. Perlakukan itu sebagai bukti bertanggal, bukan klaim ketersediaan permanen. Selalu validasi katalog saat ini dan jalankan tes rute kecil sebelum peluncuran produksi.
Rencana rollout praktis
Gunakan urutan rollout ini saat menambahkan atau merevisi strategi timeout AI API:
- Pilih satu workflow dan beri nama pemiliknya.
- Pilih anggaran connect, pool, read, stream first-event, stream idle, queue, retry, dan fallback.
- Nonaktifkan lapisan retry duplikat atau turunkan agar jumlah total percobaan menjadi jelas.
- Tambahkan logging lapisan timeout sebelum mengubah perilaku rute.
- Jalankan kasus uji normal, lambat, dibatasi laju, streamed, dan kegagalan terkontrol.
- Konfirmasi bahwa retry berhenti sebelum output parsial diduplikasi.
- Konfirmasi bahwa fallback mempertahankan tools, skema, boundary data, dan ekspektasi biaya yang diperlukan.
- Tinjau log request, satuan penggunaan, dan bukti biaya di Flatkey.
- Pindahkan hanya workflow yang telah diuji ke produksi.
- Ulangi untuk workflow berikutnya alih-alih menyatakan satu kebijakan timeout global.
Strategi timeout AI API terbaik cukup kecil untuk diuji dan cukup ketat untuk menghentikan. Strategi itu harus membuat timeout menjadi biasa saja: satu lapisan gagal, anggaran retry jelas, fallback tetap berada dalam kontrak yang disetujui atau berhenti, dan log menunjukkan apa yang terjadi.
Pertanyaan yang sering diajukan
Apa itu strategi timeout AI API?
Strategi timeout AI API adalah kebijakan di tingkat workflow yang menetapkan anggaran terpisah untuk setup koneksi, waktu permintaan/read, event pertama streaming, jeda idle streaming, queue background, retry, fallback, dan observabilitas.
Mengapa tidak menggunakan timeout default SDK?
Default SDK adalah pagar pengaman yang luas. Aplikasi produksi membutuhkan anggaran yang lebih ketat berdasarkan pengalaman pengguna, biaya, perilaku retry, dan risiko alur kerja. SDK resmi OpenAI menyediakan pengaturan timeout, sehingga tim dapat menetapkan batas khusus per alur kerja.
Apakah setiap timeout harus memicu fallback?
Tidak. Timeout koneksi mungkin aman untuk di-retry atau dialihkan. Timeout idle stream setelah sebagian output yang terlihat oleh pengguna biasanya harus dihentikan dengan bersih. Alur kerja keuangan atau kepatuhan mungkin memerlukan antrean atau peninjauan manusia вместо fallback otomatis.
Berapa kali sebuah request AI seharusnya diberi retry?
Hitung semua lapisan retry secara keseluruhan: SDK, gateway, worker, queue, dan aplikasi. Jaga totalnya tetap kecil, log setiap percobaan, dan berhenti sebelum retry menimbulkan biaya ganda atau output yang terlihat oleh pengguna menjadi tidak konsisten.
Apa yang harus diukur tim terlebih dahulu?
Mulailah dengan tingkat timeout per lapisan, waktu ke event pertama, kegagalan idle stream, penggandaan retry, tingkat fallback, biaya per hasil yang diterima, dan usia antrean yang belum terselesaikan. Metrik tersebut menunjukkan apakah kebijakan timeout melindungi alur kerja atau justru menyembunyikan insiden.
Bagaimana Flatkey membantu operasi timeout?
Flatkey memberi tim satu permukaan gateway untuk akses model yang terhubung, routing, penagihan, analitik penggunaan, dan kontrol operasional. Gunakan untuk meninjau model saat ini dan path endpoint, mengamati bukti request, serta menjaga keputusan timeout, retry, fallback, dan biaya tetap terikat pada satu owner key.
Mulailah dengan harga Flatkey, pilih satu alur kerja, lalu dapatkan key dan uji anggaran timeout sebelum merutekan traffic produksi melaluinya.
