Tutorial: Memperbaiki set keterampilan menggunakan Sesi Debug

Artikel
09/01/2024

Di Azure AI Search, set keterampilan mengoordinasikan tindakan keterampilan yang menganalisis, mengubah, atau membuat konten yang dapat dicari. Sering kali, output dari satu keterampilan menjadi input dari keterampilan lain. Saat input tergantung pada output, kesalahan dalam definisi set keterampilan dan asosiasi lapangan dapat mengakibatkan operasi dan data yang terlewat.

Sesi Debug adalah alat portal Azure yang menyediakan visualisasi holistik dari set keterampilan yang dijalankan di Azure AI Search. Dengan menggunakan alat ini, Anda dapat menelusuri paling detail langkah-langkah tertentu untuk dengan mudah melihat tempat tindakan mungkin tidak berfungsi.

Dalam artikel ini, gunakan Sesi Debug untuk menemukan dan memperbaiki input dan output yang hilang. Tutorial ini mencakup semuanya. Ini menyediakan data sampel, file REST yang membuat objek, dan instruksi untuk men-debug masalah dalam set keterampilan.

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

Prasyarat

Pencarian Azure AI. Buat layanan atau temukan layanan yang sudah ada dalam langganan Anda saat ini. Anda dapat menggunakan layanan gratis untuk tutorial ini. Tingkat gratis tidak menyediakan dukungan identitas terkelola untuk azure AI layanan Pencarian. Anda harus menggunakan kunci untuk koneksi ke Azure Storage.
Akun Azure Storage dengan penyimpanan Blob, digunakan untuk menghosting data sampel, dan untuk menyimpan data cache yang dibuat selama sesi debug. Jika Anda menggunakan layanan pencarian gratis, akun penyimpanan harus mengaktifkan kunci akses bersama dan harus mengizinkan akses jaringan publik.
Visual Studio Code dengan klien REST.
PDF sampel (uji klinis).
Contoh file debug-sessions.rest yang digunakan untuk membuat alur pengayaan.

Catatan

Tutorial ini juga menggunakan layanan Azure AI untuk deteksi bahasa, pengenalan entitas, dan ekstraksi frasa kunci. Karena beban kerja sangat kecil, layanan Azure AI diketuk di belakang layar untuk pemrosesan gratis hingga 20 transaksi. Ini berarti Anda dapat menyelesaikan latihan ini tanpa harus membuat sumber daya layanan Azure AI yang dapat ditagih.

Menyiapkan data sampel

Bagian ini membuat sampel himpunan data di Azure Blob Storage sehingga pengindeks dan set keterampilan memiliki konten untuk dikerjakan.

Unduh sampel data (uji-klinis-pdf-19), yang terdiri dari 19 file.
Buat akun Azure Storage atau cari akun yang sudah ada.
- Pilih wilayah yang sama dengan Azure AI Search untuk menghindari biaya bandwidth.
- Pilih jenis akun StorageV2 (tujuan umum V2).
Navigasi ke halaman layanan Azure Storage di portal dan buat kontainer Blob. Praktik terbaik adalah menentukan tingkat akses "privat". Beri nama kontainer clinicaltrialdataset Anda.
Dalam kontainer, pilih Unggah untuk mengunggah file sampel yang Anda unduh dan buka zipnya di langkah pertama.
Saat berada di portal, salin string koneksi untuk Azure Storage. Anda bisa mendapatkan string koneksi dari Pengaturan>Kunci Akses di portal.

Menyalin kunci dan URL

Tutorial ini menggunakan kunci API untuk autentikasi dan otorisasi. Anda memerlukan titik akhir layanan pencarian dan kunci API, yang bisa Anda dapatkan dari portal Azure.

Masuk ke portal Azure, navigasikan ke halaman Gambaran Umum, dan salin URL. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.
Di bawah Kunci Pengaturan>, salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu.

Kunci API yang valid menetapkan kepercayaan, berdasarkan per permintaan, antara aplikasi yang mengirim permintaan dan layanan pencarian yang menanganinya.

Membuat sumber data, set keterampilan, indeks, dan pengindeks

Di bagian ini, buat alur kerja "buggy" yang dapat Anda perbaiki dalam tutorial ini.

Mulai Visual Studio Code dan buka debug-sessions.rest file.
Berikan variabel berikut: URL layanan pencarian, kunci API admin layanan pencarian, string koneksi penyimpanan, dan nama kontainer blob yang menyimpan PDF.
Kirim setiap permintaan secara bergantian. Membuat pengindeks membutuhkan waktu beberapa menit untuk diselesaikan.
Tutup file.

Memeriksa hasil di portal

Samepl kode sengaja membuat indeks buggy sebagai konsekuensi dari masalah yang terjadi selama eksekusi set keterampilan. Masalahnya adalah bahwa indeks kehilangan data.

Di portal Azure, pada halaman Gambaran Umum layanan pencarian, pilih tab Indeks.
Pilih uji klinis.
Masukkan string kueri JSON ini di tampilan JSON penjelajah pencarian. Ini mengembalikan bidang untuk dokumen tertentu (diidentifikasi oleh bidang unik metadata_storage_path ).
```
"search": "*",
"select": "metadata_storage_path, organizations, locations",
"count": true
```
Jalankan kueri. Anda akan melihat nilai kosong untuk organizations dan locations.

Bidang-bidang ini seharusnya diisi melalui keterampilan Pengenalan Entitas set keterampilan, yang digunakan untuk mendeteksi organisasi dan lokasi di mana saja dalam konten blob. Pada latihan berikutnya, Anda akan men-debug set keterampilan untuk menentukan apa yang salah.

Cara lain untuk menyelidiki kesalahan dan peringatan adalah melalui portal Azure.

Buka tab Pengindeks dan pilih clinical-trials-idxr.

Perhatikan bahwa sementara pekerjaan pengindeks berhasil secara keseluruhan, ada peringatan.
Pilih Berhasil untuk melihat peringatan (jika sebagian besar ada kesalahan, tautan detail akan Gagal). Anda akan melihat daftar panjang setiap peringatan yang dikeluarkan oleh pengindeks.

Memulai sesi debug Anda

Dari panel navigasi kiri layanan pencarian, di bawah Manajemen pencarian, pilih Sesi debug.
Pilih + Tambahkan Sesi Debug.
Beri nama sesi.
Di templat Pengindeks, berikan nama pengindeks. Pengindeks memiliki referensi ke sumber data, set keterampilan, dan indeks.
Pilih akun penyimpanan.
Simpan sesi.
Sesi debug terbuka ke halaman pengaturan. Anda dapat melakukan modifikasi pada konfigurasi awal dan mengambil alih default apa pun. Sesi debug hanya berfungsi dengan satu dokumen. Defaultnya adalah menerima dokumen pertama dalam koleksi sebagai dasar sesi debug Anda. Anda dapat memilih dokumen tertentu untuk di-debug dengan menyediakan URI-nya di Azure Storage.
Setelah sesi debug selesai diinisialisasi, Anda akan melihat alur kerja keterampilan dengan pemetaan dan indeks pencarian. Struktur data dokumen yang diperkaya muncul di panel detail di samping. Kami mengecualikannya dari cuplikan layar berikut sehingga Anda dapat melihat lebih banyak alur kerja.

Menemukan masalah dengan set keterampilan

Masalah apa pun yang dilaporkan oleh pengindeks ditunjukkan sebagai Kesalahan dan Peringatan.

Perhatikan bahwa jumlah kesalahan dan peringatan adalah daftar yang jauh lebih kecil daripada yang ditampilkan sebelumnya karena daftar ini hanya merinci kesalahan untuk satu dokumen. Seperti daftar yang ditampilkan oleh pengindeks, Anda dapat memilih pesan peringatan dan melihat detail peringatan ini.

Pilih Peringatan untuk meninjau pemberitahuan. Anda akan melihat empat:

"Tidak dapat menjalankan keterampilan karena satu atau beberapa input keterampilan tidak valid. Input keterampilan yang diperlukan hilang. Nama: 'text', Source: '/document/content'."
"Tidak dapat memetakan 'lokasi' bidang output ke indeks pencarian. Periksa properti 'outputFieldMappings' dari pengindeks. Nilai hilang '/document/merged_content/locations'."
"Tidak dapat memetakan 'organisasi' bidang output ke indeks pencarian. Periksa properti 'outputFieldMappings' dari pengindeks. Nilai tidak ada '/document/merged_content/organizations'."
"Keterampilan dijalankan tetapi mungkin memiliki hasil yang tidak terduga karena satu atau beberapa input keterampilan tidak valid. Input keterampilan opsional tidak ada. Nama: 'languageCode', Sumber: '/document/languageCode'. Masalah penguraian bahasa ekspresi: Nilai tidak ada '/document/languageCode'."

Banyak keterampilan memiliki parameter "languageCode". Dengan memeriksa operasi, Anda dapat melihat bahwa input kode bahasa ini hilang dari EntityRecognitionSkill.#1, yang merupakan keterampilan pengenalan entitas yang sama yang mengalami masalah dengan output 'lokasi' dan 'organisasi'.

Karena keempat pemberitahuan adalah tentang keterampilan ini, langkah Anda selanjutnya adalah men-debug keterampilan ini. Jika memungkinkan, mulailah dengan memecahkan masalah input terlebih dahulu sebelum beralih ke masalah output.

Memperbaiki nilai input keterampilan yang hilang

Pada permukaan kerja, pilih keterampilan yang melaporkan peringatan. Dalam tutorial ini, ini adalah keterampilan pengenalan entitas.
Panel Detail keterampilan terbuka di sebelah kanan dengan bagian untuk iterasi dan input dan output masing-masing, pengaturan keterampilan untuk definisi JSON keterampilan, dan pesan untuk kesalahan dan peringatan apa pun yang dipancarkan keterampilan ini.
Arahkan mouse ke atas setiap input (atau pilih input) untuk memperlihatkan nilai dalam evaluator Ekspresi. Perhatikan bahwa hasil yang ditampilkan untuk input ini tidak terlihat seperti input teks. Ini terlihat seperti serangkaian karakter \n \n\n\n\n baris baru alih-alih teks. Kurangnya teks berarti bahwa tidak ada entitas yang dapat diidentifikasi, jadi dokumen ini gagal memenuhi prasyarat keterampilan, atau ada input lain yang harus digunakan sebagai gantinya.
Beralih kembali ke Struktur data yang diperkaya dan tinjau simpul pengayaan untuk dokumen ini. \n \n\n\n\n Perhatikan untuk "konten" tidak memiliki sumber asal, tetapi nilai lain untuk "merged_content" memiliki output OCR. Meskipun tidak ada indikasi, konten PDF ini tampaknya merupakan file JPEG, sebagaimana dibuktikan oleh teks yang diekstraksi dan diproses dalam "merged_content".
Beralih kembali ke keterampilan dan pilih Pengaturan set keterampilan untuk membuka definisi JSON.
Ubah ekspresi dari /document/content ke /document/merged_content, lalu pilih Simpan. Perhatikan bahwa peringatan tidak lagi tercantum.
Pilih Jalankan di menu jendela sesi. Ini memulai eksekusi set keterampilan lain menggunakan dokumen.
Setelah eksekusi sesi debug selesai, perhatikan bahwa jumlah peringatan telah berkurang satu. Peringatan menunjukkan bahwa kesalahan untuk input teks hilang, tetapi peringatan lainnya tetap ada. Langkah selanjutnya adalah mengatasi peringatan tentang nilai /document/languageCodeyang hilang atau kosong .
Pilih keterampilan dan arahkan mouse ke atas /document/languageCode. Nilai untuk input ini null, yang bukan input yang valid.
Seperti halnya masalah sebelumnya, mulailah dengan meninjau struktur data yang diperkaya untuk bukti nodenya. Perhatikan bahwa tidak ada simpul "languageCode", tetapi ada satu untuk "bahasa". Jadi, ada kesalahan ketik dalam pengaturan keterampilan.
Salin ekspresi /document/language.
Di panel Detail keterampilan, pilih Pengaturan Keterampilan untuk keterampilan #1 dan tempelkan nilai baru, /document/language.
Pilih Simpan.
Pilih Jalankan.
Setelah eksekusi sesi debug selesai, Anda dapat memeriksa hasilnya di panel Detail keterampilan. Saat mengarahkan mouse ke atas /document/language, Anda akan melihat en sebagai nilai dalam evaluator Ekspresi.

Perhatikan bahwa peringatan input hilang. Sekarang hanya ada dua peringatan tentang bidang output untuk organisasi dan lokasi.

Memperbaiki nilai output keterampilan yang tidak ada

Pesan mengatakan untuk memeriksa properti 'outputFieldMappings' pengindeks Anda, jadi mari kita mulai di sana.

Pilih Pemetaan Bidang Output pada permukaan kerja. Perhatikan bahwa pemetaan bidang output hilang.
Sebagai langkah pertama, konfirmasikan bahwa indeks pencarian memiliki bidang yang diharapkan. Dalam hal ini, indeks memiliki bidang untuk "lokasi" dan "organisasi".
Jika tidak ada masalah dengan indeks, langkah selanjutnya adalah memeriksa output keterampilan. Seperti sebelumnya, pilih struktur data yang diperkaya, dan gulir simpul untuk menemukan "lokasi" dan "organisasi". Perhatikan bahwa induknya adalah "konten" alih-alih "merged_content". Konteksnya salah.
Beralih kembali ke panel Detail keterampilan untuk keterampilan pengenalan entitas.
Di Pengaturan Keterampilan, ubah context ke document/merged_content. Pada titik ini, Anda harus memiliki tiga modifikasi pada definisi keterampilan sama sekali.
Pilih Simpan.
Pilih Jalankan.

Semua kesalahan telah diatasi.

Melakukan perubahan pada set keterampilan

Saat sesi debug dimulai, layanan pencarian membuat salinan set keterampilan. Ini dilakukan untuk melindungi set keterampilan asli di layanan pencarian Anda. Sekarang setelah Anda selesai menelusuri kesalahan set keterampilan Anda, perbaikan dapat dilakukan (menimpa set keterampilan asli).

Atau, jika belum siap untuk melakukan perubahan, Anda dapat menyimpan sesi debug dan membukanya kembali nanti.

Pilih Terapkan perubahan di menu sesi Debug utama.
Pilih OK untuk mengonfirmasi bahwa Anda ingin memperbarui set keterampilan Anda.
Tutup sesi Debug dan buka Pengindeks dari panel navigasi kiri.
Pilih 'clinical-trials-idxr'.
Pilih Atur ulang.
Pilih Jalankan.
Pilih Refresh untuk memperlihatkan status reset dan jalankan perintah.

Saat pengindeks selesai berjalan, harus ada tanda centang hijau dan kata Berhasil di samping stempel waktu untuk eksekusi terbaru di tab Riwayat eksekusi. Untuk memastikan bahwa perubahan telah diterapkan:

Di panel navigasi kiri, buka Indeks.
Pilih indeks 'uji klinis' dan di tab Penjelajah pencarian, masukkan string kueri ini: $select=metadata_storage_path, organizations, locations&$count=true untuk mengembalikan bidang untuk dokumen tertentu (diidentifikasi oleh bidang unik metadata_storage_path ).
Pilih Telusuri.

Hasilnya akan menunjukkan bahwa organisasi dan lokasi sekarang diisi dengan nilai yang diharapkan.

Membersihkan sumber daya

Saat bekerja dengan langganan Anda sendiri, sebaiknya identifikasi apakah Anda masih membutuhkan sumber daya yang Anda buat di akhir proyek. Sumber daya yang dibiarkan berjalan dapat menghabiskan uang Anda. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh rangkaian sumber daya.

Anda dapat menemukan dan mengelola sumber daya di portal, menggunakan tautan Semua sumber daya atau Grup sumber daya di panel navigasi kiri.

Layanan gratis dibatasi hingga tiga indeks, pengindeks, dan sumber data. Anda dapat menghapus item individu di portal agar tetap berada dalam batasan.

Langkah berikutnya

Tutorial ini membahas berbagai aspek definisi dan pemrosesan set keterampilan. Untuk mempelajari lebih lanjut tentang konsep dan alur kerja, lihat artikel berikut:

Bagikan melalui