Men-debug set keterampilan Azure Cognitive Search di portal Azure

  • Artikel
  • 6 menit untuk membaca

Mulai sesi debug berbasis portal untuk mengidentifikasi dan mengatasi kesalahan, memvalidasi perubahan, dan mendorong perubahan ke set keterampilan yang diterbitkan di layanan Azure Cognitive Search Anda.

Sesi debug adalah pengindeks cache dan eksekusi set keterampilan, tercakup ke satu dokumen, yang dapat Anda gunakan untuk mengedit dan menguji perubahan Anda secara interaktif. Jika Anda tidak terbiasa dengan cara kerja sesi debug, lihat Sesi debug di Azure Cognitive Search. Untuk mempraktikkan alur kerja debug dengan dokumen sampel, lihat Tutorial: Sesi debug.

Prasyarat

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

  • Penetapan peran Kontributor di layanan Pencarian.

  • Akun Azure Storage, digunakan untuk menyimpan status sesi.

  • Penetapan peran Kontributor Data Blob Storage di 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. Daftar berikut mencatat pengecualian:

  • MongoDB API (pratinjau) Cosmos DB saat ini tidak didukung.

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

  • Untuk API SQL Cosmos DB, jika koleksi yang dipartisi sebelumnya non-partisi, Sesi Debug tidak akan menemukan dokumen.

Membuat sesi debug

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

  2. Di halaman Gambaran Umum layanan pencarian Anda, pilih tab Sesi Debug .

  3. Pilih + Sesi Debug Baru.

    Screenshot of the debug sessions commands in the portal page.

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

  5. Dalam koneksi Storage, temukan akun penyimpanan tujuan umum untuk penembolokan sesi debug. Anda akan diminta untuk memilih dan secara opsional membuat kontainer blob di Blob Storage atau Azure Data Lake Storage Gen2. Anda dapat menggunakan kembali kontainer yang sama untuk semua sesi debug berikutnya yang Anda buat. Nama kontainer yang bermanfaat mungkin "cognitive-search-debug-sessions".

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

  7. Di Dokumen yang akan 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.

    Jika dokumen spesifik Anda adalah blob, Anda akan dimintai URI blob. Anda dapat menemukan URL di halaman properti blob di portal.

    Screenshot of the URI property in blob storage.

  8. Secara opsional, dalam pengaturan Pengindeks, tentukan pengaturan eksekusi pengindeks apa pun yang digunakan untuk membuat sesi. Pengaturan harus meniru pengaturan yang digunakan oleh pengindeks aktual. Opsi pengindeks apa pun yang Anda tentukan dalam sesi debug tidak berpengaruh pada pengindeks itu sendiri.

  9. Konfigurasi Anda akan terlihat mirip dengan cuplikan layar ini. Pilih Simpan Sesi untuk memulai.

    Screenshot of a debug session page.

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

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 akan dibatasi pada satu dokumen. Anda akan mengerjakan daftar ini, membuat perubahan, lalu kembali ke daftar untuk memverifikasi apakah masalah diselesaikan.

Untuk menampilkan pesan, pilih keterampilan dalam Keterampilan Pengayaan > AI Graph lalu pilih Kesalahan/Peringatan di panel detail.

Sebagai praktik terbaik, selesaikan 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/Peringatan untuk melihat apakah jumlahnya berkurang. Daftar tidak akan disegarkan hingga Anda membuka tab.

Melihat konten simpul pengayaan

Alur pengayaan AI 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 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.

Dokumen yang diperkaya bersifat internal, tetapi sesi debug memberi Anda akses ke konten yang dihasilkan selama eksekusi keterampilan. Untuk melihat konten atau output dari setiap keterampilan, ikuti langkah-langkah berikut:

  1. Mulailah dengan tampilan default: Keterampilan pengayaan > AI Graph, dengan jenis grafik diatur ke Graph Dependensi.

  2. Pilih keterampilan.

  3. Di panel detail di sebelah kanan, pilih Eksekusi, pilih OUTPUT, lalu buka Evaluator Ekspresi (</>) untuk menampilkan ekspresi dan hasilnya.

    Screenshot of a skill execution showing output values.

  4. Atau, buka Pengayaan > AI Struktur Data yang Diperkaya untuk menggulir ke bawah daftar simpul. Daftar ini mencakup simpul potensial dan aktual, dengan kolom untuk output, dan kolom lain yang menunjukkan objek hulu yang digunakan untuk menghasilkan output.

    Screenshot of enriched document showing output values.

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 bukan cara memperbaikinya. Untuk bantuan terkait konteks dan sintaks input, lihat Mereferensikan anotasi dalam kumpulan keterampilan Azure Cognitive Search. 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. Dalam Graph Keterampilan pengayaan > AI, pilih keterampilan. Panel Detail Keterampilan terbuka di sebelah kanan.

  2. Edit definisi keterampilan menggunakan salah satu pendekatan:

    • Keterampilan Pengaturan jika Anda lebih suka editor visual
    • Editor JSON Keterampilan untuk mengedit dokumen JSON secara langsung

  3. Periksa sintaks jalur untuk mereferensikan simpul di pohon pengayaan. Berikut ini 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.

Memeriksa pemetaan bidang

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

  1. Mulailah dengan tampilan default: Keterampilan pengayaan > AI Graph, dengan jenis grafik diatur ke Graph Dependensi.

  2. Pilih Pemetaan Bidang di dekat bagian atas. Anda harus menemukan setidaknya kunci dokumen yang secara unik mengidentifikasi dan mengaitkan setiap dokumen pencarian dalam indeks pencarian dengan dokumen sumbernya di sumber data.

    Jika Anda mengimpor konten mentah langsung dari sumber data, melewati pengayaan, Anda harus menemukan bidang tersebut di Pemetaan Bidang.

  3. Pilih Pemetaan Bidang Output di bagian bawah grafik. Di sini Anda akan menemukan pemetaan dari output keterampilan ke bidang target dalam indeks pencarian. Kecuali Anda menggunakan wizard Impor Data, pemetaan bidang output ditentukan secara manual dan mungkin tidak lengkap atau salah ketik.

    Verifikasi bahwa bidang dalam Pemetaan Bidang Output ada dalam indeks pencarian seperti yang ditentukan, memeriksa sintaks jalur simpul ejaan dan pengayaan.

    Screenshot of the Output Field Mappings node and details.

Men-debug keterampilan kustom secara lokal

Keterampilan kustom bisa lebih menantang untuk debug karena kode berjalan secara eksternal. Bagian ini menjelaskan cara men-debug keterampilan Custom Web API, sesi debug, Visual Studio Code dan ngrok Anda secara lokal. Teknik ini bekerja dengan keterampilan kustom yang dijalankan di Azure Functions atau Web Framework lainnya yang berjalan secara lokal (misalnya, FastAPI).

Jalankan ngrok

ngrok adalah aplikasi lintas platform yang dapat membuat URL penerowongan atau penerusan, sehingga permintaan internet mencapai 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.

    Screenshot of ngrok terminal.

Mengonfigurasi di portal Microsoft Azure

Dalam sesi debug, ubah URI Keterampilan API Web Kustom Anda untuk memanggil URL penerusan ngrok. Pastikan Anda menambahkan "/api/FunctionName" saat menggunakan Azure Function untuk menjalankan kode skillset.

Anda dapat mengedit definisi keterampilan di portal.

Menguji kode

Pada titik ini, permintaan baru dari sesi debug Anda sekarang harus dikirim ke Azure Function lokal Anda. Anda dapat menggunakan titik henti dalam kode Visual Studio 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