# Bagaimana Menguji Kompatibilitas Streaming dan Tool Call Sebelum Mengganti API LLM? > Uji migrasi API LLM dengan fixture kontrak yang direkam, bukan demo chat. Verifikasi streaming teks, satu tool paksa, argumen terfragmentasi, beberapa panggilan, kelanjutan hasil tool, pembatalan, error, dan akuntansi penggunaan. Tes chat sepuluh menit dapat melewatkan kegagalan terpenting: panggilan ganda setelah retry, JSON yang dieksekusi sebelum event stream terakhir, hasil tool dengan role salah, atau pembatalan yang membiarkan proses tulis tetap berjalan. Gate migrasi yang berguna mengirim request tetap melalui parser dan executor sebenarnya, lalu menilai invarian struktural. Buat suite awal cukup kecil untuk dijalankan rutin dan cukup deterministik untuk dibandingkan antarmodel. Tujuannya bukan menilai kecerdasan, tetapi membuktikan API baru dapat menggerakkan loop agent dengan aman. ## Definisikan kontrak yang dibutuhkan klien Tuliskan perilaku yang diperlukan sebelum menguji provider. Hindari label samar seperti “kompatibel dengan OpenAI”. | Area kontrak | Invarian wajib | Bukti yang disimpan | |---|---|---| | Autentikasi | Endpoint menerima key | Status dan request ID | | Stream teks | Delta menjadi satu pesan final | Event mentah berurutan | | Stream tool | Panggilan selesai sebelum eksekusi | Buffer panggilan dan event final | | Korelasi | Hasil terhubung ke panggilan benar | Pemetaan call ID | | Retry | Panggilan dieksekusi maksimal sekali | Log idempotensi | | Penggunaan | Counter tersedia atau ditandai tidak tersedia | Metadata respons final | Dukungan protokol bersifat khusus model. Atlas Cloud menyediakan beberapa format request, jadi periksa panduan [`supported_apis`](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis) sebelum memilih route pengujian. ## Buat empat tool deterministik Gunakan fixture yang menyingkap mode kegagalan berbeda: * `echo_json` mengembalikan argumen tervalidasi tanpa perubahan. * `read_fixture` membaca satu file yang diketahui dari sandbox. * `delayed_value` selesai setelah jeda terkontrol. * `always_error` mengembalikan error terstruktur yang stabil. Berikan skema ketat dengan `additionalProperties: false` dan ID fixture unik agar eksekusi ganda terlihat. Jangan bergantung pada cuaca, hasil pencarian, atau repository yang berubah. ## Jalankan matriks kompatibilitas bertahap Uji non-streaming sebelum streaming dan satu panggilan sebelum banyak panggilan. | Tahap | Perilaku prompt | Syarat lulus | |---|---|---| | A | Kembalikan teks biasa | Teks final dan status berhenti tiba | | B | Paksa `echo_json` | Nama dan argumen valid tiba | | C | Stream `echo_json` | Fragmen dirakit sekali | | D | Panggil dua tool baca | Kedua hasil terkorelasi dengan benar | | E | Terima satu error tool | Model memperbaiki atau berhenti bersih | | F | Batalkan di tengah stream | Tidak ada eksekusi tool terlambat | Gunakan skema dan maksud semantik yang sama untuk setiap kandidat. Jika protokol native memerlukan envelope lain, ubah representasi wire saja. ## Tangkap event mentah di bawah SDK Objek SDK tingkat tinggi praktis di produksi tetapi dapat menutupi perbedaan migrasi. Tambahkan transport debug yang mencatat nomor urut monotonik, response ID, output index, call ID, jenis event, dan panjang payload yang sudah disensor. Argumen fungsi streaming bersifat inkremental. Rakit per panggilan dan tunggu event argumen final: ```text START -> CALL_OPEN -> ARGUMENT_DELTAS -> CALL_DONE -> VALIDATED -> EXECUTED | | +-> CANCELLED <---+ ``` Tolak transisi mundur dan eksekusi ganda. Jika koneksi terputus setelah `EXECUTED` tetapi sebelum model menerima hasil, gunakan idempotency key alih-alih mengulangi aksi tulis secara buta. ## Uji perjalanan pulang-pergi hasil tool Tool call valid baru setengah kontrak. Kembalikan hasil menggunakan message atau item type yang diwajibkan protokol, kemudian minta jawaban final menyebut field yang diketahui dari hasil tersebut. Uji hasil besar, kosong, Unicode, dan error terstruktur. Batasi ukuran hasil sebelum masuk kembali ke konteks. Migrasi bisa tampak berhasil sampai tool pertama mengembalikan konten yang melampaui asumsi adapter. ## Bandingkan invarian, bukan gaya bahasa Jangan menggagalkan suite hanya karena dua model menulis jawaban final berbeda. Pastikan: * Nama tool yang diharapkan dipilih. * Argumen lulus validasi JSON Schema. * Setiap call ID unik dan terkorelasi. * Setiap tool dieksekusi nol atau satu kali sesuai rencana. * Loop selesai dalam batas panggilan. * Jawaban final menggunakan hasil fixture. Simpan snapshot khusus kandidat hanya untuk debugging. Pertahankan kriteria lulus yang netral terhadap provider. ## Tambahkan kasus error dan pembatalan Putuskan stream setelah fragmen argumen pertama, setelah panggilan selesai, dan setelah tool dieksekusi. Injeksikan 429, timeout, JSON rusak, dan nama tool yang tidak dikenal. Pastikan klien retry, melanjutkan dengan aman, atau berhenti dengan error yang berguna. Bug paling berbahaya adalah retry ambigu yang mengulangi tool pengubah state. Wajibkan idempotensi eksplisit untuk operasi tulis. ## Jadikan suite sebagai release gate Pertahankan smoke suite cepat untuk perubahan konfigurasi dan matriks penuh untuk upgrade SDK atau gateway. Simpan model, protokol, base URL, hash skema, flag streaming, versi klien, dan timestamp. Atlas Cloud mendukung request LLM streaming dan non-streaming serta menyediakan kandidat dalam satu [katalog model](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis). Jalankan gate yang sama untuk setiap model; akses bersama tidak berarti kemampuan identik. ## Kesimpulan Uji migrasi API LLM sebagai perubahan protokol yang memiliki state. Mulailah dengan tool deterministik, rekam event mentah, rakit argumen hanya saat selesai, verifikasi round trip hasil tool, lalu injeksikan retry dan pembatalan. Promosikan model baru hanya ketika suite kontrak lulus, bukan ketika satu respons chat terlihat benar. ## FAQ ### Apa yang harus dicakup tes kompatibilitas pertama? Mulailah dengan satu request teks non-streaming dan satu tool read-only paksa untuk mengisolasi masalah endpoint, autentikasi, skema, dan bentuk respons dasar. ### Mengapa event streaming mentah perlu direkam? Helper SDK dapat menyembunyikan urutan event dan perbedaan field. Event mentah menunjukkan bagaimana call ID, fragmen argumen, penanda selesai, error, dan penggunaan benar-benar tiba. ### Bisakah provider dibandingkan berdasarkan teks yang persis sama? Biasanya tidak. Bandingkan invarian struktural seperti panggilan valid, field wajib, jumlah eksekusi, status akhir, dan hasil tugas. ### Bagaimana menguji argumen tool yang rusak? Kembalikan error validasi terstruktur dan pastikan loop memperbaiki atau berhenti dalam batas panggilan yang ditetapkan tanpa mengeksekusi input berbahaya. ### Apakah test suite sebaiknya memakai tool tulis? Mulailah dengan tool read-only deterministik. Tambahkan fixture tulis dalam sandbox setelah perakitan, validasi, deduplikasi, dan pemulihan error lulus. ### Seberapa sering tes kompatibilitas dijalankan? Jalankan smoke subset sebelum setiap perubahan model atau protokol dan suite lengkap ketika versi SDK, skema, gateway, atau parser stream berubah.