Tutorial: Menelusuri kesalahan set keterampilan menggunakan Sesi Debug

Set keterampilan mengoordinasikan serangkaian tindakan yang menganalisis atau mengubah konten, saat 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 di portal Azure menyediakan visualisasi holistik keterampilan. Dengan menggunakan alat ini, Anda dapat menelusuri paling detail langkah-langkah tertentu untuk dengan mudah melihat tempat tindakan mungkin tidak berfungsi.

Dalam artikel ini, Anda akan menggunakan Sesi debug untuk menemukan dan memperbaiki 1) input yang tidak ada, dan 2) pemetaan bidang output. Tutorial ini mencakup semuanya. Tutorial ini menyediakan data bagi Anda untuk mengindeks (data uji klinis), koleksi Postman yang membuat objek, dan petunjuk untuk menggunakan Sesi debug guna menemukan dan memperbaiki masalah dalam set keterampilan.

Penting

Sesi debug adalah fitur pratinjau yang disediakan tanpa perjanjian tingkat layanan, dan tidak disarankan untuk beban kerja produksi. Untuk mengetahui informasi selengkapnya, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

Prasyarat

Sebelum Anda mulai, siapkan prasyarat berikut:

Catatan

Mulai cepat ini juga menggunakan Azure Cognitive Services untuk AI. Karena beban kerjanya sangat kecil, Layanan Kognitif diketuk di belakang layar untuk pemrosesan gratis hingga 20 transaksi. Artinya, Anda dapat menyelesaikan latihan ini tanpa harus membuat sumber daya Layanan Kognitif tambahan.

Menyiapkan data Anda

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

  1. Unduh sampel data (uji-klinis-pdf-19), yang terdiri dari 19 file.

  2. Buat akun penyimpanan Azure atau cari akun yang sudah ada.

    • Pilih wilayah yang sama dengan Azure Cognitive Search untuk menghindari biaya bandwidth.

    • Pilih jenis akun StorageV2 (tujuan umum V2).

  3. Navigasi ke halaman layanan Azure Storage di portal dan buat kontainer Blob. Praktik terbaik adalah menentukan tingkat akses "privat". Beri nama kontainer clinicaltrialdataset Anda.

  4. Di kontainer, klik Unggah untuk mengunggah sampel file yang Anda unduh dan ekstrak di langkah pertama.

  5. Saat berada di portal, dapatkan dan simpan string koneksi untuk Azure Storage. Anda akan membutuhkannya untuk panggilan REST API yang mengindeks data. Anda bisa mendapatkan string koneksi dari Pengaturan > Kunci Akses di portal.

Mendapatkan kunci dan URL

Panggilan REST memerlukan URL layanan dan kunci akses pada setiap permintaan. Layanan pencarian dibuat dengan keduanya, jadi jika Anda menambahkan Azure Cognitive Search ke langganan Anda, ikuti langkah-langkah ini untuk mendapatkan informasi yang diperlukan:

  1. Masuk ke portal Microsoft Azure, dan di halaman Gambaran Umum layanan pencarian Anda, dapatkan URL. Contoh titik akhir mungkin terlihat seperti https://mydemo.search.windows.net.

  2. Di Pengaturan > Kunci, dapatkan kunci admin untuk mendapatkan hak penuh pada layanan. Ada dua kunci admin yang dapat dipertukarkan, kunci disediakan untuk kelangsungan bisnis jika Anda perlu menimpa salah satunya. Anda dapat menggunakan kunci utama atau sekunder pada permintaan untuk menambahkan, memodifikasi, dan menghapus objek.

    Mendatkan titik akhir HTTP dan kunci akses

Semua permintaan memerlukan kunci api pada setiap permintaan yang dikirim ke layanan Anda. Memiliki kunci yang valid akan membangun kepercayaan, berdasarkan per permintaan, antara aplikasi yang mengirim permintaan dan layanan yang menanganinya.

Membuat sumber data, set keterampilan, indeks, dan pengindeks

Di bagian ini, Postman dan koleksi yang disediakan digunakan untuk membuat sumber data, set keterampilan, indeks, dan pengindeks Cognitive Search. Jika Anda tidak terbiasa dengan Postman, lihat mulai cepat ini.

Anda akan memerlukan koleksi Postman yang dibuat untuk tutorial ini guna menyelesaikan tugas ini.

  1. Mulai Postman dan impor koleksi. Di bawah File > Baru, pilih koleksi untuk diimpor.

  2. Setelah koleksi diimpor, perluas daftar tindakan (...).

  3. Klik Edit.

  4. Di bawah Nilai Saat Ini, masukkan nama searchService Anda (misalnya, jika titik akhir adalah https://mydemo.search.windows.net, nama layanan adalah "mydemo").

  5. Masukkan apiKey dengan kunci utama atau sekunder layanan pencarian Anda.

  6. Masukkan storageConnectionString dari halaman kunci akun Azure Storage Anda.

  7. Masukkan containerName dari kontainer yang Anda buat di akun penyimpanan, lalu klik Perbarui.

    mengedit variabel di Postman

Koleksi berisi empat panggilan REST berbeda yang digunakan untuk membuat objek yang digunakan dalam tutorial ini.

Panggilan pertama membuat sumber data. clinical-trials-ds. Panggilan kedua membuat set keterampilan, clinical-trials-ss. Panggilan ketiga membuat indeks, clinical-trials. Panggilan keempat dan terakhir membuat pengindeks, clinical-trials-idxr.

  • Buka setiap permintaan secara bergantian, lalu klik Kirim untuk mengirim setiap permintaan ke layanan pencarian.

Setelah semua panggilan dalam koleksi selesai, tutup Postman dan kembali ke portal Azure.

Memeriksa hasil di portal

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

  1. Di portal Azure, di halaman Gambaran Umum layanan pencarian, pilih tab Indeks.
  2. Pilih indeks clinical-trials.
  3. Masukkan string kueri ini: $select=metadata_storage_path, organizations, locations&$count=true untuk menampilkan bidang untuk dokumen tertentu (yang diidentifikasi oleh bidang metadata_storage_path unik).
  4. Klik Cari untuk menjalankan kueri, menampilkan 19 dokumen, yang menunjukkan nilai kosong untuk "organisasi" dan "lokasi".

Bidang ini seharusnya diisi melalui keterampilan Pengenalan Entitas set keterampilan, yang digunakan untuk menemukan organisasi dan lokasi di mana saja dalam konten blob. Di latihan berikutnya, Anda akan menggunakan Sesi debug untuk menentukan apa yang salah.

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

  1. Buka tab Pengindeks, lalu pilih clinical-trials-idxr.

  2. Perhatikan bahwa sementara pekerjaan pengindeks berhasil secara keseluruhan, ada 57 peringatan.

  3. Klik Berhasil untuk melihat peringatan (jika sebagian besar ada kesalahan, tautan detail akan Gagal). Anda akan melihat daftar panjang setiap peringatan yang dikeluarkan oleh pengindeks.

    melihat peringatan

Memulai sesi debug Anda

memulai sesi debug baru

  1. Dari halaman gambaran umum pencarian, klik tab Sesi debug.
  2. Pilih + Sesi Debug Baru.
  3. Beri nama sesi.
  4. Sambungkan sesi ke akun penyimpanan Anda.
  5. Di templat Pengindeks, berikan nama pengindeks. Pengindeks memiliki referensi ke sumber data, set keterampilan, dan indeks.
  6. Terima pilihan dokumen default untuk dokumen pertama dalam koleksi.
  7. Simpan sesi. Menyimpan sesi akan memulai alur pengayaan AI seperti yang ditetapkan oleh set keterampilan.

Penting

Sesi debug hanya berfungsi dengan satu dokumen. Anda dapat memilih dokumen mana yang akan ditelusuri kesalahannya, atau hanya menggunakan dokumen pertama.

Saat sesi debug selesai diinisialisasi, sesi default ke tab Pengayaan AI, menyoroti Grafik Keterampilan. Grafik Keterampilan menyediakan hierarki visual set keterampilan dan urutan eksekusinya secara berurutan dan paralel.

Menemukan masalah dengan set keterampilan

Setiap masalah yang dilaporkan oleh pengindeks dapat ditemukan di tab Kesalahan/Peringatan yang berdekatan.

Perhatikan bahwa tab Kesalahan/Peringatan akan menyediakan 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 mengklik pesan peringatan dan melihat detail peringatan ini.

Pilih Kesalahan/Peringatan untuk meninjau pemberitahuan. Anda akan melihat tiga:

  • "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 tapi 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 tidak ada dari Enrichment.NerSkillV2.#1, yang merupakan keterampilan Pengenalan Entitas yang sama yang mengalami masalah dengan output 'lokasi' dan 'organisasi'.

Karena ketiga notifikasi tentang keterampilan ini, langkah selanjutnya adalah menelusuri kesalahan keterampilan ini. Jika memungkinkan, mulai dengan memecahkan masalah input terlebih dahulu sebelum beralih ke masalah outputFieldMapping.

Sesi debug baru dimulai

Memperbaiki nilai input keterampilan yang tidak ada

Di tab Kesalahan/Peringatan, ada kesalahan untuk operasi berlabel Enrichment.NerSkillV2.#1. Detail kesalahan ini menjelaskan bahwa ada masalah dengan nilai input keterampilan '/document/languageCode'.

  1. Kembali ke tab Pengayaan AI.

  2. Klik Grafik Keterampilan.

  3. Klik keterampilan berlabel #1 untuk menampilkan detailnya di panel kanan.

  4. Cari input untuk "languageCode".

  5. Pilih simbol </> di awal baris dan buka Evaluator Ekspresi.

  6. Klik tombol Evaluasi untuk mengonfirmasi bahwa ekspresi ini mengakibatkan kesalahan. Ini akan mengonfirmasi bahwa properti "languageCode" bukan input yang valid.

    Evaluator Ekspresi

Ada dua cara untuk meneliti kesalahan ini dalam sesi tersebut. Yang pertama adalah melihat asal input - keterampilan apa dalam hierarki yang seharusnya menghasilkan hasil ini? Tab Eksekusi di panel detail keterampilan harus menampilkan sumber input. Jika tidak ada sumber, ini menunjukkan kesalahan pemetaan bidang.

  1. Klik tab Eksekusi.

  2. Lihat INPUTS dan cari "languageCode". Tidak ada sumber untuk input yang dicantumkan ini.

  3. Alihkan panel kiri untuk menampilkan Struktur Data yang Diperkaya. Tidak ada jalur yang dipetakan yang sesuai dengan "languageCode".

    Struktur Data yang Diperkaya

Ada jalur yang dipetakan untuk "bahasa". Jadi, ada kesalahan ketik di pengaturan keterampilan. Untuk memperbaiki ekspresi ini di keterampilan #1 dengan ekspresi '/document/language' perlu diperbarui.

  1. Buka Evaluator Ekspresi </> untuk jalur "bahasa".
  2. Salin ekspresi. Tutup jendela.
  3. Buka Pengaturan Keterampilan untuk keterampilan #1, lalu buka Evaluator Ekspresi </> untuk input "languageCode".
  4. Tempelkan nilai baru, '/dokumen/bahasa' ke dalam kotak Ekspresi, lalu klik Evaluasi.
  5. Ini harus menampilkan input "en" yang benar. Klik Terapkan untuk memperbarui ekspresi.
  6. Klik Simpan di panel detail keterampilan yang tepat.
  7. Klik Jalankan di menu jendela sesi. Ini akan memulai eksekusi set keterampilan lain menggunakan dokumen.

Setelah eksekusi sesi debug selesai, klik tab Kesalahan /Peringatan dan ini akan menunjukkan bahwa kesalahan berlabel "Enrichment.NerSkillV2.#1" tidak ada. Namun, masih ada dua peringatan bahwa layanan tidak dapat memetakan bidang output untuk organisasi dan lokasi ke indeks pencarian. Ada nilai yang tidak ada: '/document/merged_content/organizations' dan '/document/merged_content/locations'.

Memperbaiki nilai output keterampilan yang tidak ada

Kesalahan dan peringatan

Ada nilai output yang tidak ada dari keterampilan. Untuk mengidentifikasi keterampilan dengan kesalahan, buka Struktur Data yang Diperkaya, temukan nama nilai, dan lihat Sumber Asalnya. Dalam kasus nilai organisasi dan lokasi yang tidak ada, keduanya adalah output dari keterampilan #1. Membuka Evaluator Ekspresi </> untuk setiap jalur, akan menampilkan ekspresi yang tercantum sebagai '/document/conten/organization' dan '/document/content/locations', masing-masing.

Entitas organisasi evaluator ekspresi

Output untuk entitas ini kosong dan tidak boleh kosong. Apa saja input yang menghasilkan hasil ini?

  1. Buka Grafik Keterampilan dan pilih keterampilan #1.

  2. Pilih tab Eksekusi di panel detail keterampilan yang tepat.

  3. Buka Evaluator Ekspresi </> untuk "teks" INPUT.

    Input untuk keterampilan teks

Hasil yang ditampilkan untuk input ini tidak terlihat seperti input teks. Ini sepertinya gambar yang dikelilingi oleh garis baru. Kurangnya teks artinya tidak ada entitas yang dapat diidentifikasi. Melihat hierarki set keterampilan menampilkan konten pertama kali diproses oleh keterampilan #6 (OCR) dan kemudian diteruskan ke keterampilan #5 (Merge).

  1. Pilih keterampilan #5 (Merge) dalam Grafik Keterampilan.

  2. Pilih tab Eksekusi di panel detail keterampilan yang tepat, lalu buka Evaluator Ekspresi </> untuk "mergedText" OUTPUTS.

    Output untuk keterampilan Merge

Di sini, teks dipasangkan dengan gambar. Melihat ekspresi '/document/merged_content', kesalahan di jalur "organisasi" dan "lokasi" untuk keterampilan #1 terlihat. Alih-alih menggunakan '/document/content', ini harus menggunakan '/document/merged_content' untuk input "teks".

  1. Salin ekspresi untuk output "mergedText" dan tutup jendela Evaluator Ekspresi.
  2. Pilih keterampilan #1 dalam Grafik Keterampilan.
  3. Pilih tab Pengaturan Keterampilan di panel detail keterampilan yang tepat.
  4. Buka Evaluator Ekspresi </> untuk "teks" input.
  5. Tempelkan ekspresi baru ke dalam kotak. Klik Evaluasi.
  6. Input yang benar dengan teks yang ditambahkan akan ditampilkan. Klik Terapkan untuk memperbarui Pengaturan Keterampilan.
  7. Klik Simpan di panel detail keterampilan yang tepat.
  8. Klik Jalankan di menu jendela sesi. Ini akan memulai eksekusi set keterampilan lain menggunakan dokumen.

Setelah pengindeks selesai berjalan, kesalahan masih ada. Kembali ke keterampilan #1 dan selidiki. Input ke keterampilan diperbaiki ke 'merged_content' dari 'content'. Apa saja output untuk entitas ini dalam keterampilan?

  1. Pilih tab Pengayaan AI.

  2. Pilih Grafik Keterampilan, lalu klik keterampilan #1.

  3. Navigasikan Pengaturan Keterampilan untuk menemukan "output".

  4. Buka Evaluator Ekspresi </> untuk entitas "organisasi".

    Output untuk entitas organisasi

Mengevaluasi hasil ekspresi memberikan hasil yang benar. Keterampilan berupaya mengidentifikasi nilai yang benar untuk entitas, "organisasi". Namun, pemetaan output di jalur entitas masih menghasilkan kesalahan. Dalam membandingkan jalur output dalam keterampilan dengan jalur output dalam kesalahan, keterampilan yang menjadi induk output, organisasi, dan lokasi di bawah simpul /document/content. Sementara pemetaan bidang output mengharapkan hasilnya akan menjadi turunan di bawah simpul /document/merged_content. Di langkah sebelumnya, input berubah dari '/document/content' menjadi '/document/merged_content'. Konteks dalam pengaturan keterampilan perlu diubah untuk memastikan output dihasilkan dengan konteks yang tepat.

  1. Pilih tab Pengayaan AI.

  2. Pilih Grafik Keterampilan, lalu klik keterampilan #1.

  3. Navigasikan Pengaturan Keterampilan untuk menemukan "konteks".

  4. Klik dua kali pengaturan untuk "konteks" dan edit untuk membaca '/document/merged_content'.

  5. Klik Simpan di panel detail keterampilan yang tepat.

  6. Klik Jalankan di menu jendela sesi. Ini akan memulai eksekusi set keterampilan lain menggunakan dokumen.

    Koreksi konteks dalam pengaturan keterampilan

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.

  1. Klik Buat perubahan di menu Sesi debug utama.
  2. Klik OK untuk mengonfirmasi bahwa Anda ingin memperbarui set keterampilan Anda.
  3. Tutup Sesi debug, lalu pilih tab Pengindeks.
  4. Buka 'clinical-trials-idxr'.
  5. Klik Reset.
  6. Klik Jalankan. Klik OK untuk mengonfirmasi.

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:

  1. Di halaman Gambaran Umum pencarian, pilih tab Indeks.
  2. Buka indeks 'clinical-trials' dan di tab Penjelajah pencarian, masukkan string kueri ini: $select=metadata_storage_path, organizations, locations&$count=true untuk menampilkan bidang untuk dokumen tertentu (diidentifikasi oleh bidang metadata_storage_path unik).
  3. Klik 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 berjalan dapat menghabiskan uang Anda. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh set sumber daya.

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

Jika menggunakan layanan gratis, ingatlah bahwa Anda dibatasi pada 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: