Tutorial: Memperbaiki kumpulan keterampilan menggunakan Sesi Debug

2025-03-31

Di Azure AI Search, sekumpulan keterampilan mengoordinasikan tindakan untuk 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 langkah-langkah tertentu secara mendetail untuk dengan mudah melihat tempat di mana tindakan mungkin mengalami kegagalan.

Dalam tutorial ini, Anda menggunakan 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.

Prasyarat

Sebuah akun Azure dengan langganan aktif. Buat akun secara gratis.
Pencarian Azure AI. Buat layanan atau temukan layanan yang sudah ada di langganan Anda saat ini. Anda dapat menggunakan layanan gratis untuk tutorial ini. Tingkat Gratis tidak menyediakan dukungan identitas terkelola untuk layanan Azure AI Search. 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 pipeline 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 dimanfaatkan di belakang layar untuk pemrosesan tanpa biaya 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).
Buka halaman layanan Azure Storage di portal Microsoft Azure 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.
Di portal Microsoft Azure, pilih Pengaturan>Kunci Akses dan salin string koneksi untuk Azure Storage.

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 Microsoft Azure, buka 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, keterampilan, indeks, dan pengindeksan

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.

Periksa hasil di portal Azure

Kode contoh sengaja membuat indeks buggy sebagai konsekuensi dari masalah yang terjadi selama eksekusi 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 dari set keterampilan, yang digunakan untuk mendeteksi organisasi dan lokasi di seluruh konten blob. Pada latihan berikutnya, Anda men-debug kemampuan Anda untuk menentukan apa yang menyebabkan kesalahan.

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

Pada tab Pengindeks , pilih clinical-trials-idxr.

Perhatikan bahwa meskipun pekerjaan pengindeksan berhasil secara keseluruhan, ada peringatan.
Pilih Berhasil untuk melihat peringatan. Jika sebagian besar ada kesalahan, tautan detail gagal. Anda akan melihat daftar panjang setiap peringatan yang dipancarkan oleh pengindeks.

Memulai sesi debug Anda

Dari panel navigasi kiri layanan pencarian, di bawah Manajemen pencarian, pilih Sesi debug.
Pilih + Tambahkan Sesi Debug.
Berikan nama pada 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.
Ketika 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.

Mengidentifikasi masalah dengan keterampilan.

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

Perhatikan bahwa jumlah kesalahan dan peringatan adalah daftar yang lebih kecil dari 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 '/document/merged_content/locations' tidak ditemukan.
"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. Masukan keterampilan opsional belum tersedia. Nama: 'languageCode', Sumber: '/document/languageCode'. Masalah analisis bahasa ekspresi: Nilai hilang untuk '/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 antarmuka kerja, pilih keterampilan yang melaporkan peringatan. Dalam tutorial ini, ini adalah keterampilan pengenalan entitas.
Panel Detail Keterampilan terbuka di sisi kanan dengan bagian untuk iterasi serta input dan output-nya masing-masing, pengaturan keterampilan untuk definisi JSON keterampilan, dan pesan untuk setiap kesalahan dan peringatan yang dihasilkan oleh keterampilan ini.
Arahkan mouse ke setiap input (atau pilih input) untuk memperlihatkan nilai dalam Ekspresi evaluator. 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. Baik dokumen ini tidak 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. Perhatikan bahwa \n \n\n\n\n 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".
Kembali ke menu kemampuan dan pilih Pengaturan Skillset 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 pelaksanaan rangkaian keterampilan lainnya dengan 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.
Pada 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 menggerakkan mouse ke atas /document/language, Anda seharusnya melihat en sebagai nilai dalam Expression evaluator.

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

Memperbaiki nilai output keterampilan yang hilang

Pesan tersebut mengatakan untuk memeriksa properti 'outputFieldMappings' dari pengindeks Anda, jadi ayo kita mulai dari sana.

Pilih Pemetaan Bidang Output di 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 induk dari adalah "konten" bukan "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 diselesaikan.

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 men-debug keterampilan Anda, perbaikan dapat dilakukan (menggantikan 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 kiri.
Pilih 'clinical-trials-idxr'.
Pilih Atur ulang.
Pilih Jalankan.
Pilih Refresh untuk memperlihatkan status reset dan jalankan perintah.

Ketika 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 diterapkan:

Di panel 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 Cari.

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 aktif 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 Azure, 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 individual di portal Azure agar tetap di bawah batas.

Langkah berikutnya

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