Bagikan melalui

Men-debug set keterampilan Azure AI Search di portal Azure

  • Artikel

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

Sesi debug adalah pengindeks cache dan eksekusi set keterampilan, dicakup ke satu dokumen, yang dapat Anda gunakan untuk mengedit dan menguji perubahan set keterampilan 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 Azure AI Search. Untuk mempraktikkan alur kerja debug dengan dokumen sampel, lihat Tutorial: Sesi debug.

Prasyarat

  • Azure AI layanan Pencarian. Sebaiknya gunakan identitas terkelola dan penetapan peran yang ditetapkan sistem yang memungkinkan Azure AI Search menulis ke Azure Storage dan memanggil sumber daya Azure AI yang digunakan dalam set keterampilan.

  • Akun Azure Storage, digunakan untuk menyimpan status sesi.

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

  • Untuk penetapan peran, identitas layanan pencarian harus memiliki:

    • Izin Pengguna Cognitive Services pada akun multiservice Azure AI yang digunakan oleh set keterampilan.

    • Izin Kontributor Data Blob Penyimpanan di Azure Storage. Jika tidak, rencanakan penggunaan akses penuh string koneksi untuk koneksi sesi debug ke Azure Storage.

  • Jika akun Azure Storage berada di belakang firewall, konfigurasikan untuk mengizinkan akses layanan pencarian.

Batasan

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

  • Pengindeks SharePoint Online.

  • Pengindeks Azure Cosmos DB for 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 SQL 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 string koneksi akses penuh yang menyertakan kunci. Untuk informasi selengkapnya, lihat Menyambungkan layanan pencarian ke sumber daya Azure lainnya menggunakan identitas terkelola.

Membuat sesi debug

  1. Masuk ke portal Azure dan temukan layanan pencarian Anda.

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

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

    Cuplikan layar perintah sesi debug di halaman portal.

  4. Di Nama sesi debug, berikan nama yang akan membantu Anda mengingat kumpulan keterampilan, pengindeks, dan sumber data yang terkait dengan sesi debug.

  5. Di Template pengindeks, pilih pengindeks yang menggerakkan kumpulan keterampilan yang ingin Anda debug. Salinan pengindeks dan kumpulan keterampilan digunakan untuk menginisialisasi sesi.

  6. Di Akun penyimpanan, temukan akun penyimpanan tujuan umum untuk menyimpan cache sesi debug.

  7. Pilih Autentikasi menggunakan identitas terkelola jika sebelumnya Anda menetapkan izin Kontributor Data Blob Penyimpanan ke identitas yang dikelola sistem layanan pencarian.

  8. Pilih Simpan.

    • Azure AI Search membuat kontainer blob di 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.

  9. Sesi debug terbuka ke halaman pengaturan. Anda dapat melakukan modifikasi pada konfigurasi awal dan mengambil alih default apa pun.

  10. Di String koneksi Penyimpanan, Anda dapat menentukan string koneksi atau mengubah akun penyimpanan.

  11. Dalam Dokumen untuk 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.

    Jika dokumen spesifik Anda adalah blob, berikan URI blob. Anda dapat menemukan URI di halaman properti blob di portal.

    Cuplikan layar properti URI dalam penyimpanan blob.

  12. Secara opsional, di pengaturan Pengindeks, tentukan pengaturan eksekusi pengindeks apa pun yang digunakan untuk membuat sesi. Pengaturan harus mencerminkan pengaturan yang digunakan oleh pengindeks aktual. Setiap opsi pengindeks yang Anda tentukan dalam sesi debug tidak berpengaruh pada pengindeks itu sendiri.

  13. Jika Anda membuat perubahan, pilih Simpan sesi, diikuti dengan Jalankan.

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 dijalankan menggunakan tombol Batalkan . 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 di 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.

Cuplikan layar tombol kesalahan dan peringatan di bagian atas halaman.

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

Alur pengayaan AI mengekstrak atau menyimpulkan informasi dan struktur dari dokumen sumber, membuat dokumen yang diperkaya dalam proses. Dokumen yang diperkaya pertama kali dibuat selama pemecahan dokumen dan diisi dengan simpul akar (/document), ditambah simpul untuk konten apa pun yang diangkat 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 keterampilan atau pemetaan, detailnya adalah tentang objek tersebut.

    Cuplikan layar yang menunjukkan panah biru yang digunakan untuk menampilkan detail sensitif konteks.

  2. Pilih keterampilan.

    Cuplikan layar memperlihatkan panel detail keterampilan dengan telusuri paling detail untuk informasi selengkapnya.

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

    Cuplikan layar memperlihatkan panel detail keterampilan dengan Evaluator Ekspresi untuk output tertentu.

Memeriksa 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.

Cuplikan layar area pemetaan indeks alur kerja.

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 dan vektorisasi data. Pemetaan ini menentukan pemetaan bidang induk-anak (gugus) dan apakah indeks sekunder dibuat hanya untuk konten yang dipotong

  • 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.

Cuplikan layar simpul dan detail Pemetaan Bidang Output.

Mengedit definisi keterampilan

Jika pemetaan bidang sudah benar, periksa keterampilan individual 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 kumpulan 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 di 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 properti 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 kustom bisa lebih menantang untuk debug karena kode berjalan secara eksternal, sehingga sesi debug tidak dapat digunakan untuk men-debugnya. Bagian ini menjelaskan cara men-debug keterampilan API Web Kustom, sesi debug, Visual Studio Code, dan ngrok atau Tunnelmole Secara lokal. Teknik ini bekerja dengan keterampilan kustom yang dijalankan di 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 keterampilan 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 menginstal NodeJS, unduh file .exe yang telah dikompilasi sebelumnya 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 fungsi Azure diekspos.

Gunakan ngrok

ngrok adalah aplikasi lintas platform yang populer, sumber tertutup, yang dapat membuat URL penerowongan atau penerusan, sehingga permintaan internet menjangkau komputer lokal Anda. Gunakan ngrok untuk meneruskan permintaan dari alur pengayaan di layanan pencarian Anda ke komputer Anda untuk memungkinkan penelusuran kesalahan 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 7071. Alat dan konfigurasi lain mungkin mengharuskan Anda menyediakan port yang berbeda.

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

    Cuplikan layar terminal ngrok.

Mengonfigurasikan di portal Azure

Setelah Anda memiliki URL publik untuk keterampilan kustom Anda, ubah URI Keterampilan 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

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

Langkah berikutnya

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

Tutorial: Menjelajahi sesi Debug