Memecahkan masalah set keterampilan Pencarian Azure AI di portal Azure

Mulai sesi debug berbasis portal untuk mengidentifikasi dan mengatasi kesalahan, memvalidasi perubahan, dan mendorong perubahan ke set keterampilan yang ada di Search service Azure AI Anda.

Sesi debug adalah eksekusi indeks pencarian yang disimpan dalam cache dan skillset, yang dibatasi hanya pada satu dokumen, dan dapat Anda gunakan untuk mengedit serta menguji perubahan skillset secara interaktif. Setelah selesai men-debug, Anda dapat menyimpan perubahan ke set keterampilan.

Untuk latar belakang tentang cara kerja sesi debug, lihat sesi Debug di Pencarian Azure AI. Untuk mempraktikkan alur kerja debug dengan dokumen sampel, lihat Tutorial: Sesi debug.

Prerequisites

• Layanan Pencarian Azure AI, di wilayah atau tingkat apa pun.

• Akun Azure Storage, digunakan untuk menyimpan status sesi.

• Alur pengayaan yang ada, termasuk sumber data, set keterampilan, pengindeks, dan indeks.

Limitations

Sesi debug berfungsi dengan semua sumber data pengindeks yang tersedia secara umum dan sebagian besar sumber data pratinjau, dengan pengecualian berikut:

• Pengindeks SharePoint.

• Azure Cosmos DB untuk pengindeks MongoDB.

• Untuk Azure Cosmos DB for NoSQL, jika baris gagal selama indeks dan tidak ada metadata yang sesuai, sesi debug mungkin tidak memilih baris yang benar.

• Untuk NOSQL API Azure Cosmos DB, jika koleksi yang dipartisi sebelumnya tidak dipartisi, sesi debug tidak akan menemukan dokumen.

• Untuk keterampilan kustom, identitas terkelola yang ditetapkan pengguna tidak didukung untuk koneksi sesi debug ke Azure Storage. Seperti yang dinyatakan dalam prasyarat, Anda dapat menggunakan identitas terkelola sistem, atau menentukan access string koneksi lengkap yang menyertakan kunci. Untuk informasi selengkapnya, lihat Menyambungkan search service ke sumber daya Azure lain menggunakan identitas terkelola.

Keamanan dan izin

• Untuk menyimpan sesi debug ke Azure Storage, identitas layanan penelusuran harus memiliki izin Kontributor Data Blob Storage pada Azure Storage. Jika tidak, rencanakan untuk memilih string koneksi akses penuh untuk koneksi sesi debug ke Azure Storage.

• Jika akun Azure Storage berada di belakang firewall, konfigurasikan ke perbolehkan search service access.

• Jika Pencarian Azure AI dikonfigurasi untuk menggunakan kunci enkripsi yang dikelola pelanggan (CMK), informasi sensitif dalam sesi debug dienkripsi dengan kunci tersebut saat data dipertahankan.

Membuat sesi debug

1. Buka layanan pencarian Anda di portal Microsoft Azure.

2. Di menu sebelah kiri, pilih Manajemen pencarian>Sesi debug.

3. Pada bilah tindakan di bagian atas, pilih Tambahkan sesi debug.

   

4. Dalam Nama sesi debug, berikan nama yang akan membantu Anda mengingat skillset, pengindeks, dan sumber data mana yang menjadi tujuan sesi debug.

5. Di templat Pengindeks, pilih pengindeks yang mendorong set keterampilan yang ingin Anda debug. Salinan indeks dan skillset digunakan untuk menginisialisasi sesi.

6. Di Dokumen untuk di-debug, pilih dokumen pertama dalam indeks atau pilih dokumen tertentu. Jika Anda memilih dokumen tertentu, bergantung pada sumber data, Anda akan dimintai URI atau ID baris.

   Untuk dokumen tertentu dalam Blob storage: berikan URI blob. Anda dapat menemukan URI di halaman properti blob di Azure portal.

   

   Untuk dokumen tertentu di Azure Cosmos DB for NoSQL: berikan kunci dokumen dalam indeks pencarian untuk nilai tersebut, dan ID entitas di Cosmos DB untuk kunci partisi.

   

   Berikut adalah konfigurasi sesi debug untuk contoh Cosmos DB.

   

7. Di akun Storage, pilih akun storage tujuan umum untuk membuat cache sesi debug.

8. Pilih Authenticate menggunakan identitas terkelola jika sebelumnya Anda menetapkan izin Storage Blob Data Contributor ke identitas terkelola sistem dari search service. Jika Anda tidak mencentang kotak ini, layanan pencarian tersambung menggunakan string koneksi akses penuh.

9. Pilih Simpan.

   • Pencarian Azure AI membuat kontainer blob pada Azure Storage bernama ms-az-cognitive-search-debugsession.
   • Dalam kontainer tersebut, ia membuat folder menggunakan nama yang Anda berikan untuk nama sesi.
   • Ini memulai sesi debug Anda.

Sesi debug dimulai dengan menjalankan pengindeks dan set keterampilan pada dokumen yang dipilih. Konten dan metadata dokumen terlihat dan tersedia dalam sesi.

Sesi debug dapat dibatalkan saat sedang dieksekusi. Jika Anda menekan tombol Batalkan , Anda harus dapat menganalisis hasil parsial.

Diharapkan sesi debug membutuhkan waktu lebih lama untuk dijalankan daripada pengindeks karena melalui pemrosesan ekstra.

Mulai dengan kesalahan dan peringatan

Riwayat eksekusi pengindeks dalam Azure portal memberi Anda daftar kesalahan dan peringatan lengkap untuk semua dokumen. Dalam sesi debug, kesalahan dan peringatan terbatas pada satu dokumen. Anda dapat mengerjakan daftar ini, membuat perubahan, lalu kembali ke daftar untuk memverifikasi apakah masalah diselesaikan.

Ingat bahwa sesi debug didasarkan pada satu dokumen dari seluruh indeks. Jika input atau output terlihat salah, masalahnya bisa spesifik untuk dokumen tersebut. Anda dapat memilih dokumen lain untuk mengonfirmasi apakah kesalahan dan peringatan bersifat pervasif atau khusus untuk satu dokumen.

Pilih Kesalahan atau Peringatan untuk daftar masalah.

Sebagai praktik terbaik, atasi masalah dengan input sebelum beralih ke output.

Untuk membuktikan apakah modifikasi menyelesaikan kesalahan, ikuti langkah-langkah berikut:

1. Pilih Simpan di panel detail keterampilan untuk mempertahankan perubahan Anda.

2. Pilih Jalankan di jendela sesi untuk memanggil eksekusi set keterampilan menggunakan definisi yang dimodifikasi.

3. Kembali ke Kesalahan atau Peringatanuntuk melihat apakah jumlah berkurang.

Menampilkan konten yang diperkaya atau dihasilkan

Pengayaan AI pipelines mengekstrak atau menyimpulkan informasi dan struktur dari dokumen sumber, membuat dokumen yang diperkaya dalam prosesnya. Dokumen yang diperkaya pertama kali dibuat selama pemecahan dokumen dan diisi dengan simpul akar (/document), ditambah simpul untuk konten apa pun yang diekstraksi langsung dari sumber data, seperti metadata dan kunci dokumen. Lebih banyak simpul dibuat oleh keterampilan selama eksekusi keterampilan, di mana setiap output keterampilan menambahkan simpul baru ke pohon pengayaan.

Semua konten yang dibuat atau digunakan oleh set keterampilan muncul di Evaluator Ekspresi. Anda dapat mengarahkan mouse ke atas tautan untuk melihat setiap nilai input atau output di pohon dokumen yang diperkaya. Untuk melihat input atau output dari setiap keterampilan, ikuti langkah-langkah berikut:

1. Dalam sesi debug, perluas panah biru untuk melihat detail sensitif konteks. Secara default, detailnya adalah struktur data dokumen yang diperkaya. Namun, jika Anda memilih kemampuan atau pemetaan, detailnya adalah tentang objek tersebut.

   

2. Pilih keterampilan.

   

3. Ikuti tautan untuk menelaah lebih dalam ke dalam proses keterampilan. Misalnya, cuplikan layar berikut menunjukkan output perulangan pertama dari keterampilan Pemisahan Teks.

   

Periksa pemetaan indeks

Jika keterampilan menghasilkan output tetapi indeks pencarian kosong, periksa pemetaan bidang. Pemetaan bidang menentukan bagaimana konten berpindah keluar dari alur dan ke indeks pencarian.

Pilih salah satu opsi pemetaan dan perluas tampilan detail untuk meninjau definisi sumber dan target.

• Pemetaan proyeksi ditemukan dalam set keterampilan yang menyediakan vektorisasi terintegrasi, seperti keterampilan yang dibuat oleh wizard Impor data. Pemetaan ini menentukan pemetaan bidang induk-anak (chunk) dan apakah indeks sekunder dibuat hanya untuk konten yang dibagi menjadi potongan.

• Pemetaan bidang output ditemukan di pengindeks dan digunakan saat set keterampilan memanggil keterampilan bawaan atau kustom. Pemetaan ini digunakan untuk mengatur jalur data dari simpul di pohon pengayaan ke bidang dalam indeks pencarian. Untuk informasi selengkapnya tentang jalur, lihat sintaks jalur simpul pengayaan.

• Pemetaan bidang ditemukan dalam definisi pengindeks dan menetapkan jalur data dari konten mentah di sumber data dan bidang dalam indeks. Anda juga dapat menggunakan pemetaan bidang untuk menambahkan langkah-langkah pengodean dan pendekodean.

Contoh ini menunjukkan detail untuk pemetaan proyeksi. Anda dapat mengedit JSON untuk memperbaiki masalah pemetaan apa pun.

Mengedit definisi keterampilan

Jika pemetaan bidang sudah benar, periksa keterampilan individu untuk konfigurasi dan konten. Jika keterampilan gagal menghasilkan output, mungkin kehilangan properti atau parameter, yang dapat ditentukan melalui pesan kesalahan dan validasi.

Masalah lain, seperti konteks atau ekspresi input yang tidak valid, bisa lebih sulit diselesaikan karena kesalahan akan memberi tahu Anda apa yang salah, tetapi tidak cara memperbaikinya. Untuk bantuan terkait konteks dan sintaks input, lihat Pengayaan Referensi dalam set keterampilan Pencarian Azure AI. Untuk bantuan terkait pesan individual, lihat Memecahkan masalah kesalahan dan peringatan pengindeks umum.

Langkah-langkah berikut menunjukkan kepada Anda cara mendapatkan informasi tentang keterampilan.

1. Pilih keterampilan pada permukaan kerja. Panel detail keterampilan terbuka di sebelah kanan.

2. Edit definisi keterampilan menggunakan Pengaturan Keterampilan. Anda dapat mengedit JSON secara langsung.

3. Periksa sintaks jalur untuk mereferensikan simpul di pohon pengayaan. Berikut adalah beberapa jalur input yang paling umum:

   • /document/content untuk potongan teks. Simpul ini diisi dari atribut konten blob.
   • /document/merged_content untuk potongan teks dalam keterampilan yang menyertakan keterampilan Penggabungan Teks.
   • /document/normalized_images/* untuk teks yang dikenali atau disimpulkan dari gambar.

Men-debug keterampilan kustom secara lokal

Keterampilan khusus bisa lebih menantang untuk di-debug karena kode berjalan secara eksternal, sehingga sesi debug tidak dapat digunakan untuk men-debugnya. Bagian ini menjelaskan cara men-debug skill API Web Kustom Anda, sesi debug Anda, kode Visual Studio Anda, dan ngrok atau Tunnelmole. Teknik ini bekerja dengan keterampilan kustom yang dijalankan dalam Azure Functions atau Kerangka Kerja Web lainnya yang berjalan secara lokal (misalnya, FastAPI).

Mendapatkan URL publik

Bagian ini menjelaskan dua pendekatan untuk mendapatkan URL publik ke skill kustom.

Menggunakan Tunnelmole

Tunnelmole adalah alat penerowongan sumber terbuka yang dapat membuat URL publik yang meneruskan permintaan ke komputer lokal Anda melalui terowongan.

1. Pasang Tunnelmole:

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: Instal dengan menggunakan npm. Atau jika Anda tidak memiliki Node.js terinstal, unduh file .exe yang telah dikompresi untuk Windows dan letakkan di suatu tempat di JALUR Anda.

2. Jalankan perintah ini untuk membuat terowongan baru:

   tmole 7071
   

   Anda akan melihat respons yang terlihat seperti ini:

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   Dalam contoh sebelumnya, https://m5hdpb-ip-49-183-170-144.tunnelmole.net meneruskan ke port 7071 pada komputer lokal Anda, yang merupakan port default tempat Azure functions diekspos.

Gunakan ngrok

ngrok adalah aplikasi lintas platform yang populer, berkode sumber tertutup, untuk membuat URL penerusan atau penerowongan, sehingga permintaan internet menjangkau komputer lokal Anda. Gunakan ngrok untuk meneruskan permintaan dari alur pengayaan di search service Anda ke komputer Anda untuk memungkinkan debugging lokal.

1. Pasang ngrok.

2. Buka terminal dan buka folder dengan ngrok executable.

3. Jalankan ngrok dengan perintah berikut untuk membuat terowongan baru:

   ngrok http 7071 
   

   Catatan

   Secara default, fungsi Azure diekspos pada port 7071. Alat dan konfigurasi lain mungkin mengharuskan Anda menyediakan port yang berbeda.

4. Saat ngrok dimulai, salin dan simpan alamat web URL penerusan publik untuk digunakan di langkah berikutnya. URL penerusan dihasilkan secara acak.

   

Konfigurasi di portal Azure

Setelah Anda memiliki URL publik untuk keahlian kustom Anda, ubah URI Keahlian API Web Kustom Anda dalam sesi debug untuk memanggil URL penerusan Tunnelmole atau ngrok. Pastikan untuk menambahkan "/api/FunctionName" saat menggunakan Azure Function untuk menjalankan kode skillset.

Anda dapat mengedit definisi keterampilan di bagian Pengaturan keterampilan di panel Detail keterampilan .

Menguji kode Anda

Pada titik ini, permintaan baru dari sesi debug Anda sekarang harus dikirim ke Fungsi Azure lokal Anda. Anda dapat menggunakan titik henti di Kode Visual Studio untuk men-debug kode Anda atau menjalankan langkah demi langkah.

Langkah selanjutnya

Sekarang setelah Anda memahami tata letak dan kemampuan editor visual Sesi Debug, coba tutorial untuk pengalaman langsung.