Memperluas kemampuan khusus secara efisien

Keterampilan kustom adalah API web yang mengimplementasikan antarmuka tertentu. Keterampilan khusus dapat diimplementasikan pada sumber daya apa pun yang dapat diatasi secara publik. Implementasi yang paling umum untuk keterampilan kustom adalah:

• Azure Functions untuk keterampilan logika kustom
• Azure Web Apps untuk keterampilan AI kontainer sederhana
• Azure Kubernetes Service untuk keterampilan yang lebih kompleks atau lebih besar.

Konfigurasi Keterampilan

Properti berikut pada keterampilan khusus digunakan untuk skala. Tinjau antarmuka keterampilan kustom untuk pengenalan input dan output yang harus diterapkan keterampilan kustom.

1. Atur batchSize pada keterampilan kustom untuk mengonfigurasi jumlah catatan yang dikirim dalam satu pemanggilan keterampilan.

2. Atur degreeOfParallelism untuk mengkalibrasi jumlah permintaan bersamaan yang dibuat pengindeks ke keterampilan Anda.

3. Atur timeout ke nilai yang cukup bagi keterampilan untuk mengembalikan respons yang valid.

4. Dalam definisi indexer, atur batchSize ke jumlah dokumen yang harus dibaca dari sumber data dan diperkaya secara bersamaan.

Pertimbangan

Tidak ada pendekatan yang serba cocok. Rencanakan untuk menguji konfigurasi yang berbeda untuk mencapai hasil yang optimal. Strategi peningkatan skala didasarkan pada permintaan besar yang lebih sedikit atau banyak permintaan kecil.

• Kardinalitas pemanggilan keterampilan: pastikan Anda tahu apakah keterampilan kustom dijalankan sekali untuk setiap dokumen (/document/content) atau beberapa kali per dokumen (/document/reviews_text/pages/*). Jika terjadi beberapa kali dalam satu dokumen, tetap menggunakan nilai rendah dari batchSize dan degreeOfParallelism untuk mengurangi churn, dan coba atur ukuran batch pengindeksan ke nilai yang lebih tinggi secara bertahap untuk meningkatkan skala.

• Koordinasikan keahlian khusus batchSize dan pengindeks batchSize, dan pastikan Anda tidak membuat kemacetan. Misalnya, jika ukuran batch pengindeks adalah 5, dan ukuran batch keterampilan adalah 50, Anda akan memerlukan 10 batch pengindeks untuk mengisi permintaan keterampilan kustom. Idealnya, ukuran batch keterampilan harus kurang dari atau sama dengan ukuran batch pengindeks.

• Untuk degreeOfParallelism, gunakan jumlah rata-rata permintaan yang dapat dihasilkan batch pengindeks untuk memandu cara Anda mengatur nilai ini. Jika infrastruktur yang menghosting kapabilitas (misalnya, Fungsi Azure) tidak dapat mendukung tingkat konkurensi yang tinggi, pertimbangkan untuk menurunkan tingkat paralelisme. Anda dapat menguji konfigurasi dengan beberapa dokumen untuk memvalidasi pemahaman Anda tentang jumlah rata-rata permintaan.

• Meskipun tujuan Anda adalah untuk menskalakan dan mendukung volume tinggi, pengujian dengan sampel dokumen yang lebih kecil membantu mengukur berbagai tahap eksekusi. Misalnya, Anda dapat mengevaluasi waktu eksekusi keterampilan Anda relatif terhadap waktu keseluruhan yang diperlukan untuk memproses subset dokumen. Ini membantu Anda menjawab pertanyaan: apakah pengindeks Anda menghabiskan lebih banyak waktu untuk membangun batch atau menunggu respons dari keterampilan Anda?

• Pertimbangkan implikasi pada tahap awal dari penggunaan proses paralel. Jika input ke sebuah skill khusus adalah output dari skill sebelumnya, apakah semua skill dalam skillset telah di-skala keluar secara efisien untuk meminimalkan latensi?

Penanganan kesalahan dalam keterampilan kustom

Keterampilan kustom harus mengembalikan kode status keberhasilan HTTP 200 ketika keterampilan berhasil diselesaikan. Jika satu atau beberapa rekaman dalam batch menghasilkan kesalahan, pertimbangkan untuk mengembalikan kode multistatus 207. Daftar kesalahan atau peringatan untuk catatan harus berisi pesan yang sesuai.

Item apa pun dalam batch yang kesalahan menyebabkan dokumen terkait gagal. Jika Anda memerlukan dokumen agar berhasil, kembalikan peringatan.

Kode status apa pun di atas 299 dievaluasi sebagai kesalahan dan semua pengayaan gagal, mengakibatkan dokumen gagal.

Pesan kesalahan umum

• Could not execute skill because it did not execute within the time limit '00:00:30'. This is likely transient. Please try again later. For custom skills, consider increasing the 'timeout' parameter on your skill in the skillset. Atur parameter timeout pada keterampilan untuk memungkinkan durasi eksekusi yang lebih lama.

• Could not execute skill because Web Api skill response is invalid. Menunjukkan bahwa keterampilan tidak mengembalikan pesan dalam format tanggapan keterampilan kustom. Ini bisa menjadi hasil dari pengecualian yang tidak terdeteksi dalam fitur.

• Could not execute skill because the Web Api request failed. Kemungkinan besar disebabkan oleh kesalahan otorisasi atau pengecualian.

• Could not execute skill. Biasanya hasil dari respons keterampilan dipetakan ke properti yang ada dalam hierarki dokumen.

Menguji keterampilan kustom

Mulailah dengan menguji keterampilan kustom Anda dengan klien REST API untuk memvalidasi:

• Keterampilan ini mengimplementasikan antarmuka keterampilan kustom untuk permintaan dan respons

• Fitur mengembalikan JSON yang valid berformat jenis MIME application/json

• Keterampilan mengembalikan kode status HTTP yang valid

Buat sesi debug untuk menambahkan keterampilan Anda ke skillet dan pastikan untuk menghasilkan pengayaan yang valid. Meskipun sesi debug tidak memungkinkan Anda untuk menyetel performa keterampilan, itu memungkinkan Anda untuk memastikan bahwa keterampilan dikonfigurasi dengan nilai yang valid dan mengembalikan objek yang diperkaya yang diharapkan.

Praktik terbaik

• Walau keterampilan dapat menerima dan mengembalikan payload yang lebih besar, pertimbangkan untuk membatasi respons hingga 150 MB atau kurang saat mengembalikan JSON.

• Pertimbangkan untuk mengatur ukuran batch pada pengindeks dan fungsi agar memastikan setiap batch sumber data menghasilkan payload penuh untuk fungsi Anda.

• Untuk tugas yang berjalan lama, atur batas waktu ke nilai yang cukup tinggi untuk memastikan pengindeks tidak mengalami kesalahan saat memproses dokumen secara bersamaan.

• Optimalkan ukuran batch pengindeks, ukuran batch keterampilan, dan tingkat keterampilan paralelisme untuk menghasilkan pola beban yang diharapkan keterampilan Anda, lebih sedikit permintaan besar atau banyak permintaan kecil.

• Pantau keterampilan kustom dengan log kegagalan terperinci karena varianbilitas data dapat menyebabkan permintaan tertentu gagal secara konsisten.