Streaming API AI: SSE, output pertama & batas waktu
Bangun streaming API AI yang andal dengan event Chat dan Responses yang tepat, parsing SSE, metrik output efektif pertama, batas waktu per fase, dan diagnosis 499.

Streaming API AI mengirim output secara bertahap selama model menghasilkan jawaban, alih-alih menunggu seluruh isi respons selesai. Streaming dapat meningkatkan responsivitas yang dirasakan, tetapi tidak otomatis mengurangi latensi model, dan menambahkan kontrak protokol yang harus diurai dengan benar oleh klien.
Aturan pertama adalah mencocokkan parser dengan endpoint. Chat Completions mengirim chunk completion secara streaming, sedangkan Responses menggunakan event respons bertipe. Klien dapat menerima HTTP 200 dan tetap tidak menampilkan apa pun jika mengharapkan bentuk event yang salah.
Mulai dengan permintaan tanpa buffering
Untuk model Chat Completions, curl -N menonaktifkan buffering output curl:
curl -N -sS https://modelflare.dev/v1/chat/completions \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CHAT_MODEL",
"messages": [{"role": "user", "content": "Explain SSE in three points."}],
"stream": true
}'
Untuk model yang kompatibel dengan Responses:
curl -N -sS https://modelflare.dev/v1/responses \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_RESPONSES_MODEL",
"input": "Explain SSE in three points.",
"stream": true
}'
Gunakan ID model persis dari Model & Harga. Uji permintaan yang sama sekali dengan streaming dinonaktifkan terlebih dahulu; langkah ini memisahkan validasi permintaan dari penguraian stream.
Perlakukan stream event sebagai protokol
Server-Sent Events adalah record berbingkai, bukan potongan JSON sembarang. Klien produksi perlu:
- menjaga isi respons tetap tanpa buffering di library HTTP, proxy, dan lapisan UI;
- mengumpulkan pembacaan jaringan parsial hingga satu event lengkap tersedia;
- mengurai jenis event yang digunakan endpoint yang dipilih;
- menangani delta teks, event penalaran atau alat, event penyelesaian, dan event error;
- tidak berasumsi bahwa setiap respons yang berguna berisi teks yang terlihat;
- mempertahankan informasi pembatalan dan penggunaan akhir;
- menutup stream setelah event terminal, bukan menunggu tanpa batas.
Jika memungkinkan, gunakan SDK yang mendukung protokol pilihan secara native. Parser buatan sendiri harus diuji dengan frame yang terfragmentasi, beberapa event dalam satu pembacaan, output yang hanya berisi alat, dan event terminal yang bersih.
Ukur lebih dari sekadar waktu ke token pertama
"Waktu ke token pertama" sering terlalu kabur untuk traffic agen. Pisahkan pengukuran berikut:
| Pengukuran | Artinya |
|---|---|
| Koneksi dan autentikasi | Waktu untuk mencapai gateway dan memvalidasi kunci |
| Header respons penyedia layanan | Waktu hingga rute yang dipilih mulai mengirim respons |
| Output efektif pertama | Event teks, penalaran, atau alat pertama yang berguna |
| Teks terlihat pertama | Teks pertama yang benar-benar dapat dilihat pengguna |
| Throughput output | Kecepatan generasi yang terlihat setelah output dimulai |
| Total waktu respons | Waktu hingga selesai, gagal, atau dibatalkan |
Panggilan alat dapat menghasilkan output efektif sebelum ada teks yang terlihat. Karena itu, output efektif pertama adalah metrik operasional yang lebih aman, sedangkan teks terlihat pertama berguna untuk pengalaman pengguna.
Log penggunaan Modelflare menyimpan bukti waktu per permintaan sehingga fase-fase ini dapat dibandingkan dengan model, grup, status, token, dan biaya.
Rancang batas waktu per fase
Satu batas waktu global yang singkat menimbulkan kegagalan yang ambigu. Klien streaming sebaiknya mempertimbangkan beberapa anggaran waktu:
- Batas waktu koneksi: gagal membuat koneksi HTTP.
- Batas waktu header atau output pertama: tidak ada respons atau event efektif setelah permintaan diterima.
- Batas waktu idle: stream sudah dimulai, tetapi tidak ada event baru dalam waktu yang lebih lama dari perkiraan.
- Tenggat keseluruhan: seluruh operasi melampaui batas bisnis beban kerja.
Permintaan yang banyak menggunakan penalaran atau digerakkan oleh alat memang dapat menunggu lebih lama sebelum teks terlihat dibandingkan chat completion yang singkat. Tentukan anggaran waktu berdasarkan perilaku beban kerja yang teramati, dan batalkan secara sengaja ketika pengguna tidak lagi membutuhkan hasilnya.
Pahami pembatalan dan catatan 499
Jika klien, reverse proxy, tab browser, atau tenggat pemanggil menutup koneksi downstream, gateway dapat mencatat permintaan sebagai dibatalkan oleh klien. Label 499 pada catatan permintaan adalah bukti bahwa koneksi downstream berakhir sebelum permintaan selesai; label itu sendiri bukan bukti bahwa model atau kanal yang dipilih gagal.
Saat menyelidiki pembatalan, bandingkan:
- tenggat klien dan sinyal abort;
- buffering proxy dan batas waktu idle;
- waktu hingga output efektif pertama;
- apakah ada event yang sampai ke klien;
- model dan grup yang dipilih;
- ID permintaan dan stempel waktu pembatalan.
Diagnosis stream yang tidak menampilkan teks
Gunakan urutan berikut:
- Ulangi permintaan dengan "stream": false.
- Pastikan model mendukung endpoint yang dipilih.
- Tangkap event mentah sebelum UI mengubahnya.
- Periksa apakah respons berisi panggilan alat atau event penalaran, bukan teks.
- Pastikan tidak ada perantara yang melakukan buffering pada isi respons.
- Pastikan parser menangani event terminal milik endpoint tersebut.
- Tinjau log penggunaan untuk melihat status, output pertama, total waktu, dan pembatalan.
Jika non-streaming berhasil dan event streaming mentah tiba, kegagalan biasanya terletak pada penguraian atau rendering di klien, bukan pada autentikasi atau akses model. Jika tidak ada event mentah yang tiba, lanjutkan dengan Panduan error API AI.
Daftar periksa streaming produksi
- Cocokkan parser secara eksplisit dengan Chat Completions atau Responses.
- Nonaktifkan buffering di klien HTTP dan di setiap lapisan proxy yang Anda kendalikan.
- Uji event teks, penalaran, khusus alat, dan error yang digunakan aplikasi.
- Bedakan output efektif pertama dari teks terlihat pertama.
- Gunakan batas waktu yang sesuai untuk setiap fase dan sinyal abort yang disengaja.
- Perlakukan percobaan ulang sebagai permintaan baru, kecuali operasi memiliki desain idempotensi yang aman.
- Simpan ID permintaan, status, model yang dipilih, grup, dan waktu untuk diagnosis.
- Bandingkan keputusan endpoint dalam Responses API vs. Chat Completions.
Pertanyaan umum
Apakah streaming membuat model menghasilkan output lebih cepat?
Belum tentu. Streaming menampilkan output lebih awal; kecepatan generasi dan waktu sebelum event pertama tetap bergantung pada model, rute, konteks, penalaran, dan alat.
Mengapa curl berhasil, tetapi aplikasi tidak menampilkan apa pun?
Aplikasi atau perantara mungkin melakukan buffering pada isi respons, atau parser mengharapkan chunk Chat Completions padahal yang diterima adalah event Responses. Tangkap frame mentah di batas aplikasi sebelum mengganti model atau rute.
Apakah klien harus mencoba lagi setelah stream terputus?
Hanya jika mengulang operasi tersebut aman. Stream yang terputus mungkin sudah memicu pekerjaan di penyedia layanan atau aktivitas alat. Gunakan percobaan ulang terbatas dan idempotensi di tingkat aplikasi jika efek samping ganda berdampak.