Memahami Batas Jendela Konteks
Salah satu alasan paling sering kegagalan API adalah melebihi jendela konteks. Jendela konteks menentukan jumlah token maksimum yang dapat diproses model dalam satu permintaan, termasuk input (prompt, riwayat, alat) dan output (completion). Jika jumlah token gabungan Anda melebihi batas ini, API biasanya akan mengembalikan error atau memotong respons Anda secara tidak terduga.
Sebagai contoh, jika Anda menggunakan model Qwen tanpa sensor dengan jendela konteks 100.000 token, Anda harus memastikan bahwa riwayat percakapan Anda ditambah prompt baru tidak melampaui ambang batas ini. Banyak pengembang gagal melacak jumlah token kumulatif dari sesi yang berjalan lama, yang menyebabkan gangguan integrasi tiba-tiba ketika batas tercapai.
- Lacak penggunaan token: Gunakan perpustakaan tokenizer yang konsisten dengan tokenizer model untuk menghitung token secara akurat.
- Truncate history: Terapkan logika untuk menghapus pesan lama ketika jendela konteks penuh.
- Pantau batas: Periksa header respons API untuk kapasitas konteks yang tersisa jika disediakan.
Mengabaikan batas ini tidak hanya menyebabkan kesalahan; hal itu juga dapat menurunkan kualitas respons karena model kesulitan memperhatikan informasi yang relevan di jendela yang penuh sesak.
Menangani Respons Streaming dengan Benar
Streaming adalah fitur standar untuk API LLM modern, memungkinkan Anda menerima respons parsial saat dihasilkan. Namun, banyak pengembang secara keliru mengasumsikan bahwa streaming mengembalikan objek JSON lengkap untuk setiap bagian. Pada kenyataannya, streaming mengembalikan serangkaian Server-Sent Events (SSE), yang masing-masing berisi fragmen JSON parsial.
Jika Anda menggunakan klien HTTP standar tanpa dukungan SSE, Anda mungkin perlu mengurai aliran teks mentah, memisahkan berdasarkan baris data: dan mengurai setiap objek JSON secara individual. Kegagalan untuk menangani ini dengan benar dapat menghasilkan kesalahan JSON yang rusak atau teks yang terpotong.
Selain itu, pastikan UI atau perpustakaan klien Anda dirancang untuk menambahkan teks inkremental daripada menggantikan konten sebelumnya. Streaming juga memengaruhi penghitungan token; Anda harus menghitung token saat tiba untuk tetap berada dalam batas laju dan kendala anggaran.
Kesalahan Pemformatan Umum dalam Prompt
LLM sensitif terhadap pemformatan prompt. Penyimpangan kecil dari struktur yang diharapkan dapat menyebabkan kinerja buruk atau kesalahan penguraian, terutama saat menggunakan pemanggilan fungsi. Sebagai contoh, jika Anda menggunakan pemanggilan fungsi, model mengharapkan skema JSON tertentu dalam prompt. Jika prompt Anda menyertakan spasi ekstra, koma yang hilang, atau nama kunci yang salah, model mungkin gagal menghasilkan panggilan alat yang valid.
- Gunakan templat: Adopsi perpustakaan templat prompt yang konsisten untuk mengurangi kesalahan pemformatan manual.
- Validasi JSON: Selalu validasi output JSON terhadap skema yang Anda harapkan sebelum memprosesnya.
- Uji kasus tepi: Uji prompt dengan karakter khusus, baris baru, dan panjang yang bervariasi untuk memastikan ketangguhan.
Saat mengintegrasikan dengan model Qwen tanpa sensor, pastikan format prompt Anda cocok dengan struktur data pelatihan model. Format yang tidak cocok dapat menyebabkan model mengabaikan instruksi atau menghasilkan output yang tidak valid.
Pembatasan Laju dan Lalu Lintas Lonjakan
API memberlakukan batas laju untuk mencegah penyalahgunaan dan memastikan kinerja yang stabil. Kesalahan umum adalah mengirim lonjakan permintaan yang melebihi batas per menit, menyebabkan permintaan berikutnya gagal dengan kesalahan 429 Too Many Requests. Pengembang sering mengabaikan ini dengan menguji dengan volume lalu lintas rendah dan kemudian menerapkan dalam skala besar tanpa menyesuaikan strategi permintaan mereka.
Sebagai contoh, jika API mengizinkan 300 permintaan per menit, mengirim 301 permintaan dalam satu menit akan menyebabkan permintaan terakhir gagal. Untuk menghindari ini, terapkan backoff eksponensial di perpustakaan klien Anda. Strategi ini menunggu lebih lama antara percobaan ulang setelah setiap kegagalan, mencegah kemacetan lebih lanjut.
Selain itu, pantau pola permintaan Anda. Jika Anda memproses batch besar, pertimbangkan untuk menyebarkan permintaan seiring waktu daripada mengirim semuanya sekaligus. Ini memastikan kinerja yang konsisten dan menghindari batas keras.
Perhitungan Hitungan Token yang Salah
Penghitungan token sering kali diremehkan. Pengembang sering menghitung karakter atau kata alih-alih token, yang menyebabkan biaya tak terduga atau kelebihan jendela konteks. Tokenizer membagi teks menjadi subkata, artinya satu kata dapat dihitung sebagai beberapa token, terutama untuk bahasa non-Inggris atau jargon teknis.
Sebagai contoh, kata uncensored mungkin dihitung sebagai beberapa token tergantung pada tokenizer. Selalu gunakan tokenizer resmi yang disediakan oleh penyedia API untuk mendapatkan hitungan yang akurat. Ini sangat penting untuk menghitung biaya, karena harga biasanya per 1M token.
- Gunakan tokenizer resmi: Hindari perkiraan seperti 4 karakter per token.
- Hitung input dan output: Ingat bahwa token prompt dan kelengkapan keduanya ditagih.
- Pantau penggunaan: Tetapkan peringatan untuk penggunaan token tinggi untuk menghindari biaya kejutan.
Penghitungan token yang akurat memastikan Anda tetap berada dalam anggaran dan batas konteks, mencegah gangguan layanan selama operasi kritis.
Masalah Konfigurasi Pemanggilan Fungsi
Pemanggilan fungsi memungkinkan model memanggil fungsi eksternal, tetapi memerlukan konfigurasi yang tepat. Kesalahan umum adalah ketidakcocokan skema fungsi yang didefinisikan dalam permintaan API dengan implementasi fungsi aktual dalam kode Anda. Jika skema menentukan jenis parameter yang tidak cocok dengan tanda tangan fungsi Anda, model mungkin menghasilkan argumen yang tidak valid.
Masalah lain adalah lupa menyertakan hasil panggilan fungsi dalam prompt berikutnya. Model memerlukan output alat untuk menghasilkan respons akhir. Jika Anda melewatkan langkah ini, model mungkin berhalusinasi atau memberikan jawaban yang tidak lengkap.
Pastikan definisi alat Anda jelas, dengan nama dan parameter yang deskriptif. Uji alur pemanggilan fungsi secara menyeluruh dengan berbagai input untuk memastikan model menafsirkan dan mengeksekusi fungsi dengan benar. Ini sangat penting saat menggunakan model bobot terbuka seperti Qwen tanpa sensor, yang mungkin memiliki distribusi data pelatihan yang berbeda.
Kesalahan Header Autentikasi
Autentikasi adalah garis pertahanan pertama untuk akses API Anda. Kesalahan umum adalah menggunakan format header yang salah. Sebagian besar API yang kompatibel dengan OpenAI mengharapkan header otorisasi diformat sebagaiAuthorization: Bearer YOUR_API_KEY. Menggunakan API-Key atau varian lain dapat menghasilkan kesalahan 401 Unauthorized.Masalah lain adalah meneruskan kunci API dalam string kueri alih-alih header. Meskipun beberapa API mendukung ini, ini kurang aman dan mungkin tidak berfungsi dengan semua klien. Selalu lebih memilih metode header untuk keamanan dan kompatibilitas yang lebih baik.
- Verifikasi format header: Periksa kembali format header yang diperlukan dalam dokumentasi API.
- Penyimpanan kunci yang aman: Simpan kunci API dalam variabel lingkungan, bukan dalam kode.
- Rotasi kunci: Regenerasi kunci secara berkala untuk meminimalkan risiko jika kunci telah dikompromikan.
Autentikasi yang tepat memastikan bahwa permintaan Anda dikenali dan diproses dengan benar, menghindari percobaan ulang dan kesalahan yang tidak perlu.
Interpretasi Respons Error
Error API memberikan petunjuk berharga untuk debugging, tetapi sering disalahartikan. Error 400 Bad Request biasanya menunjukkan masalah dengan data input, seperti JSON yang tidak valid atau bidang yang diperlukan hilang. Error 401 Unauthorized menunjukkan masalah autentikasi, sedangkan error 429 Too Many Requests menandakan pelanggaran batas laju.
Baca pesan error dengan cermat. Pesan tersebut sering berisi detail seperti bidang yang menyebabkan error atau batasan spesifik yang dilanggar. Sebagai contoh, error mungkin menyatakan "Invalid value: 'function'", yang menunjukkan bahwa bidang role dalam pesan tidak benar.
Log error secara konsisten dan sertakan konteks seperti payload permintaan dan header. Hal ini memudahkan untuk mereproduksi dan mendiagnosis masalah di kemudian hari. Jangan abaikan error sementara; terapkan logika retry dengan backoff eksponensial untuk menangani masalah jaringan atau server sementara.
