Panduan pemecahan masalah pengindeks untuk Azure AI Search

Terkadang, pengindeks mengalami masalah yang tidak menghasilkan kesalahan atau yang terjadi pada layanan Azure lainnya, seperti selama autentikasi atau saat menyambungkan. Artikel ini berfokus pada pemecahan masalah pengindeks ketika tidak ada pesan untuk memandu Anda. Ini juga menyediakan pemecahan masalah untuk kesalahan yang berasal dari sumber daya non-pencarian yang digunakan selama pengindeksan.

Catatan

Jika Anda memiliki kesalahan Pencarian Azure AI untuk diselidiki, lihat Memecahkan masalah kesalahan dan peringatan pengindeks umum sebagai gantinya.

Memecahkan masalah koneksi ke sumber daya terbatas

Untuk sumber data di bawah keamanan jaringan Azure, pengindeks dibatasi dalam cara mereka membuat koneksi. Saat ini, pengindeks dapat mengakses sumber data terbatas di belakang firewall IP atau di jaringan virtual melalui titik akhir privat menggunakan tautan privat bersama.

Aturan firewall

Azure Storage, Azure Cosmos DB, dan Azure SQL menyediakan firewall yang dapat dikonfigurasi. Tidak ada pesan kesalahan khusus saat firewall memblokir permintaan. Biasanya, kesalahan firewall bersifat umum. Kesalahan umum meliputi:

  • The remote server returned an error: (403) Forbidden
  • This request is not authorized to perform this operation
  • Credentials provided in the connection string are invalid or have expired

Terdapat 2 opsi untuk mengizinkan pengindeks mengakses sumber daya ini dalam instans semacam itu:

  • Konfigurasikan aturan masuk untuk alamat IP layanan pencarian Anda dan rentang AzureCognitiveSearchalamat IP tag layanan. Detail untuk mengonfigurasi pembatasan rentang alamat IP untuk setiap tipe sumber data dapat ditemukan dari tautan berikut:

  • Sebagai upaya terakhir atau sebagai ukuran sementara, nonaktifkan firewall dengan mengizinkan akses dari Semua Jaringan.

Batasan: Pembatasan rentang alamat IP hanya berfungsi jika layanan pencarian dan akun penyimpanan Anda berada di wilayah yang berbeda.

Selain pengambilan data, pengindeks juga mengirim permintaan keluar melalui set keterampilan dan keterampilan kustom. Untuk keterampilan kustom berdasarkan fungsi Azure, ketahuilah bahwa fungsi Azure juga memiliki batasan alamat IP. Daftar alamat IP yang diizinkan untuk eksekusi keterampilan kustom mencakup alamat IP layanan pencarian Anda dan rentang AzureCognitiveSearch alamat IP tag layanan.

Aturan kelompok keamanan jaringan (NSG)

Saat pengindeks mengakses data pada instans terkelola SQL, atau ketika Azure VM digunakan sebagai URI layanan web untuk keterampilan kustom, grup keamanan jaringan menentukan apakah permintaan diizinkan masuk.

Untuk sumber daya eksternal yang berada di jaringan virtual, konfigurasikan aturan NSG masuk untuk AzureCognitiveSearch tag layanan.

Untuk informasi selengkapnya tentang menyambungkan ke komputer virtual, lihat Mengonfigurasi koneksi ke SQL Server di Azure VM.

Kesalahan jaringan

Biasanya, kesalahan jaringan bersifat generik. Kesalahan umum meliputi:

  • A network-related or instance-specific error occurred while establishing a connection to the server
  • The server was not found or was not accessible
  • Verify that the instance name is correct and that the source is configured to allow remote connections

Saat Anda menerima salah satu kesalahan tersebut:

  • Pastikan sumber Anda dapat diakses dengan mencoba menyambungkannya secara langsung dan bukan melalui layanan pencarian
  • Periksa sumber daya Anda di portal Azure untuk setiap kesalahan atau pemadaman saat ini
  • Periksa pemadaman jaringan apa pun di Status Azure
  • Verifikasi bahwa Anda menggunakan DNS publik untuk resolusi nama dan bukan DNS Privat Azure

Pengindeksan tanpa server Azure SQL Database (kode kesalahan 40613)

Jika database SQL Anda berada di tingkat komputasi tanpa server, pastikan database berjalan (dan tidak dijeda) saat pengindeks tersambung ke database tersebut.

Jika database dijeda, masuk pertama dari layanan pencarian Anda diharapkan untuk melanjutkan database secara otomatis, tetapi sebaliknya mengembalikan kesalahan yang menyatakan bahwa database tidak tersedia, memberikan kode kesalahan 40613. Setelah database berjalan, coba lagi masuk untuk membuat konektivitas.

Kebijakan Akses Bersyarat Microsoft Entra

Saat Anda membuat pengindeks SharePoint, ada langkah yang mengharuskan Anda untuk masuk ke aplikasi Microsoft Entra Anda setelah memberikan kode perangkat. Jika Anda menerima pesan yang bertuliskan "Your sign-in was successful but your admin requires the device requesting access to be managed", pengindeks mungkin diblokir dari pustaka dokumen SharePoint oleh kebijakan Akses Bersyar.

Untuk memperbarui kebijakan dan mengizinkan akses pengindeks ke pustaka dokumen:

  1. Buka portal Azure dan cari Microsoft Entra Conditional Access.

  2. Pilih Kebijakan pada menu sebelah kiri. Jika Anda tidak memiliki akses untuk melihat halaman ini, Anda harus menemukan seseorang yang memiliki akses atau mendapatkan akses.

  3. Tentukan kebijakan mana yang memblokir pengindeks SharePoint agar tidak mengakses pustaka dokumen. Kebijakan yang mungkin memblokir pengindeks menyertakan akun pengguna yang Anda gunakan untuk mengautentikasi selama langkah pembuatan pengindeks di bagian Pengguna dan grup . Kebijakan ini juga mungkin memiliki Ketentuan yang:

    • Membatasi platform Windows.
    • Membatasi Klien Aplikasi ponsel dan desktop .
    • Konfigurasikan Perangkat status ke Ya.
  4. Setelah Anda mengonfirmasi kebijakan mana yang memblokir pengindeks, buat pengecualian untuk pengindeks. Mulailah dengan mengambil alamat IP layanan pencarian.

    Pertama, dapatkan nama domain yang sepenuhnya memenuhi syarat (FQDN) dari layanan pencarian Anda. FQDN terlihat seperti <your-search-service-name>.search.windows.net. Anda dapat menemukan FQDN di portal Azure.

    Obtain service FQDN

    Sekarang setelah Anda memiliki FQDN, dapatkan alamat IP layanan pencarian dengan melakukan nslookup (atau ) pingFQDN. Dalam contoh berikut, Anda akan menambahkan "150.0.0.1" ke aturan masuk pada firewall Azure Storage. Mungkin perlu waktu hingga 15 menit setelah pengaturan firewall diperbarui agar pengindeks layanan pencarian dapat mengakses akun Azure Storage.

    nslookup contoso.search.windows.net
    Server:  server.example.org
    Address:  10.50.10.50
    
    Non-authoritative answer:
    Name:    <name>
    Address:  150.0.0.1
    Aliases:  contoso.search.windows.net
    
  5. Dapatkan rentang alamat IP untuk lingkungan eksekusi pengindeks untuk wilayah Anda.

    Alamat IP tambahan digunakan untuk permintaan yang berasal dari lingkungan eksekusi multipenyewa pengindeks. Anda bisa mendapatkan rentang alamat IP ini dari tag layanan .

    Rentang alamat IP untuk tag layanan AzureCognitiveSearch dapat diperoleh melalui API penemuan atau file JSON yang dapat diunduh.

    Untuk latihan ini, dengan asumsi layanan pencarian adalah cloud Azure Public, file Azure Public JSON harus diunduh.

    Download JSON file

    Dari file JSON, dengan asumsi layanan pencarian berada di US Tengah Barat, daftar alamat IP untuk lingkungan eksekusi pengindeks multipenyewa tercantum di bawah ini.

        {
          "name": "AzureCognitiveSearch.WestCentralUS",
          "id": "AzureCognitiveSearch.WestCentralUS",
          "properties": {
            "changeNumber": 1,
            "region": "westcentralus",
            "platform": "Azure",
            "systemService": "AzureCognitiveSearch",
            "addressPrefixes": [
              "52.150.139.0/26",
              "52.253.133.74/32"
            ]
          }
        }
    
  6. Kembali ke halaman Akses Bersyarat pada portal Microsoft Azure, pilih Lokasi bernama dari menu di sebelah kiri, lalu pilih + lokasi rentang IP . Beri nama untuk lokasi bernama baru Anda dan tambahkan rentang IP untuk layanan pencarian dan lingkungan eksekusi pengindeks yang Anda kumpulkan pada dua langkah terakhir. 1

    • Untuk alamat IP layanan pencarian, Anda mungkin perlu menambahkan "/32" ke akhir alamat IP karena hanya menerima rentang IP yang valid.
    • Ingat bahwa untuk rentang IP lingkungan eksekusi pengindeks, Anda hanya perlu menambahkan rentang IP untuk wilayah tempat layanan pencarian Anda berada.
  7. Kecualikan lokasi Bernama baru dari kebijakan:

    1. Pilih Kebijakan pada menu sebelah kiri.
    2. Pilih kebijakan yang sedang memblokir pengindeks.
    3. Pilih Ketentuan.
    4. Pilih Lokasi.
    5. Pilih Kecualikan lalu tambahkan lokasi Bernama yang baru.
    6. Simpan perubahan.
  8. Tunggu beberapa menit sampai kebijakan selesai diperbarui dan memberlakukan aturan kebijakan baru.

  9. Coba buat pengindeks lagi:

    1. Kirim permintaan pembaruan untuk objek sumber data yang Anda buat.
    2. Mengirim ulang permintaan untuk membuat pengindeks. Gunakan kode baru untuk masuk, lalu kirim permintaan pembuatan pengindeks lain.

Pengindeksan jenis dokumen yang tidak didukung

Jika Anda mengindeks konten dari Azure Blob Storage, dan kontainer menyertakan blob jenis konten yang tidak didukung, pengindeks melewati dokumen tersebut. Dalam kasus lain, mungkin ada masalah dengan dokumen individual.

Dalam situasi ini, Anda dapat mengatur opsi konfigurasi untuk memungkinkan pemrosesan pengindeks berlanjut jika terjadi masalah dengan dokumen individual.

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2023-11-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false, "failOnUnprocessableDocument" : false } }
}

Dokumen yang hilang

Pengindeks mengekstrak dokumen atau baris dari sumber data eksternal dan membuat dokumen pencarian, yang kemudian diindeks oleh layanan pencarian. Terkadang, dokumen yang ada di sumber data gagal muncul dalam indeks pencarian. Hasil yang tidak terduga ini dapat terjadi karena alasan berikut:

  • Dokumen diperbarui setelah pengindeks berjalan. Jika pengindeks Anda sesuai jadwal, pengindeks pada akhirnya menjalankan ulang dan mengambil dokumen.
  • Pengindeks waktu habis sebelum dokumen bisa diserap. Ada batas waktu pemrosesan maksimum setelah tidak ada dokumen yang diproses . Anda dapat memeriksa status pengindeks di portal atau melalui panggilan Dapatkan Status Pengindeks (REST API).
  • Pemetaan bidang atau pengayaan AI telah mengubah dokumen dan artikulasinya di indeks pencarian berbeda dari yang Anda harapkan.
  • Nilai pelacakan perubahan salah atau prasyarat yang hilang. Jika nilai marka air tinggi Anda adalah tanggal yang diatur ke waktu mendatang, maka dokumen apa pun yang memiliki tanggal sebelumnya dilewati oleh pengindeks. Anda dapat menentukan status pelacakan perubahan pengindeks menggunakan bidang 'initialTrackingState' dan 'finalTrackingState' dalam status pengindeks. Pengindeks untuk Azure SQL dan MySQL harus memiliki indeks pada kolom tanda air tinggi dari tabel sumber, atau kueri yang digunakan oleh pengindeks mungkin kehabisan waktu.

Tip

Jika dokumen hilang, periksa kueri yang Anda gunakan untuk memastikannya tidak mengecualikan dokumen yang dimaksud. Untuk kueri dokumen tertentu, gunakan REST API Dokumen Pencarian.

Konten yang hilang dari Blob Storage

Pengindeks blob menemukan dan mengekstrak teks dari blob dalam kontainer. Beberapa masalah dalam mengekstrak teks meliputi:

  • Dokumen hanya berisi gambar yang dipindai. Blob PDF yang memiliki konten non-teks, seperti gambar yang dipindai (JPG), tidak menghasilkan hasil dalam alur pengindeksan blob standar. Jika Anda memiliki konten gambar dengan elemen teks, Anda dapat menggunakan OCR atau analisis gambar untuk menemukan dan mengekstrak teks.

  • Pengindeks blob dikonfigurasi hanya untuk mengindeks metadata. Untuk mengekstrak konten, pengindeks blob harus dikonfigurasi untuk mengekstrak baik konten maupun metadata:

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "dataToExtract" : "contentAndMetadata" } }
}

Konten yang hilang dari Azure Cosmos DB

Azure AI Search memiliki dependensi implisit pada pengindeksan Azure Cosmos DB. Jika Anda menonaktifkan pengindeksan otomatis di Azure Cosmos DB, Azure AI Search mengembalikan status berhasil, tetapi gagal mengindeks konten kontainer. Untuk instruksi tentang cara memeriksa pengaturan dan mengaktifkan pengindeksan, lihat Mengelola pengindeksan di Azure Cosmos DB.

Perbedaan jumlah dokumen antara sumber data dan indeks

Pengindeks mungkin menampilkan jumlah dokumen yang berbeda dari sumber data, indeks itu sendiri, atau hitungan dalam kode Anda. Berikut adalah beberapa kemungkinan alasan mengapa perilaku ini dapat terjadi:

  • Indeks dapat tertinggal dalam menunjukkan jumlah dokumen nyata, terutama di portal.
  • Pengindeks memiliki Kebijakan Dokumen yang Dihapus. Dokumen yang dihapus dihitung oleh pengindeks jika dokumen diindeks sebelum dihapus.
  • Jika kolom ID di sumber data tidak unik. Ini berlaku untuk sumber data yang memiliki konsep kolom, seperti Azure Cosmos DB.
  • Jika definisi sumber data memiliki kueri yang berbeda dari yang Anda gunakan untuk memperkirakan jumlah rekaman. Misalnya, dalam database, Anda mengkueri jumlah rekaman database, sementara dalam kueri definisi sumber data, Anda mungkin hanya memilih subkumpulan rekaman untuk diindeks.
  • Jumlah sedang diperiksa pada interval yang berbeda untuk setiap komponen alur: sumber data, pengindeks, dan indeks.
  • Sumber data memiliki file yang dipetakan ke banyak dokumen. Kondisi ini dapat terjadi saat mengindeks blob dan "parsingMode" diatur ke jsonArray dan jsonLines.

Dokumen diproses beberapa kali

Pengindeks menggunakan strategi buffering konservatif untuk memastikan bahwa setiap dokumen baru dan yang diubah dalam sumber data diambil selama pengindeksan. Dalam situasi tertentu, buffer ini dapat tumpang tindih, menyebabkan pengindeks mengindeks dokumen dua kali atau lebih sehingga jumlah dokumen yang diproses lebih dari jumlah dokumen aktual dalam sumber data. Perilaku ini tidak memengaruhi data yang disimpan dalam indeks, seperti menduplikasi dokumen, hanya saja diperlukan waktu lebih lama untuk mencapai konsistensi akhir. Kondisi ini sangat umum jika salah satu kriteria berikut ini benar:

  • Permintaan pengindeks sesuai permintaan dikeluarkan secara berurutan
  • Topologi sumber data mencakup beberapa replika dan partisi (salah satu contoh tersebut dibahas di sini)
  • Sumber data adalah database Azure SQL dan kolom yang dipilih sebagai "tanda air tinggi" berjenis datetime2

Pengindeks tidak dimaksudkan untuk dipanggil beberapa kali berturut-turut dengan cepat. Jika Anda memerlukan pembaruan dengan cepat, pendekatan yang didukung adalah mendorong pembaruan ke indeks sambil secara bersamaan memperbarui sumber data. Untuk pemrosesan sesuai permintaan, kami sarankan Anda mempercepat permintaan dalam interval lima menit atau lebih, dan menjalankan pengindeks sesuai jadwal.

Contoh pemrosesan dokumen duplikat dengan buffer 30 detik

Kondisi di mana dokumen diproses dua kali dijelaskan dalam garis waktu berikut yang mencatat setiap tindakan dan tindakan penghitung. Garis waktu berikut menggambarkan masalah:

Garis waktu (hh:mm:ss) Aktivitas Tanda Air Tinggi Pengindeksan Komentar
00:01:00 Menulis doc1 ke sumber data dengan konsistensi akhirnya null Stempel waktu dokumen adalah 00:01:00.
00:01:05 Menulis doc2 ke sumber data dengan konsistensi akhirnya null Stempel waktu dokumen adalah 00:01:05.
00:01:10 Pengindeks dimulai null
00:01:11 Kueri pengindeks untuk semua perubahan sebelum 00:01:10; replika yang diminta oleh pengindeks hanya menyadari doc2; hanya doc2 yang diambil null Pengindeks meminta semua perubahan sebelum memulai stempel waktu tetapi benar-benar menerima subset. Perilaku ini mengharuskan periode buffer lihat kembali.
00:01:12 Proses pengindeks doc2 untuk pertama kalinya null
00:01:13 Pengindeks berakhir 00:01:10 Tanda air yang tinggi diperbarui untuk memulai stempel waktu eksekusi pengindeks saat ini.
00:01:20 Pengindeks dimulai 00:01:10
00:01:21 Kueri pengindeks untuk semua perubahan antara 00:00:40 dan 00:01:20; replika yang diminta oleh pengindeks untuk menyadari doc1 dan doc2; mengambil doc1 dan doc2 00:01:10 Pengindeks meminta semua perubahan antara tanda air tinggi saat ini dikurangi buffer 30 detik, dan memulai stempel waktu eksekusi pengindeks saat ini.
00:01:22 Proses pengindeks doc1 untuk pertama kalinya 00:01:10
00:01:23 Proses pengindeks doc2 untuk kedua kalinya 00:01:10
00:01:24 Pengindeks berakhir 00:01:20 Tanda air yang tinggi diperbarui untuk memulai stempel waktu eksekusi pengindeks saat ini.
00:01:32 Pengindeks dimulai 00:01:20
00:01:33 Kueri pengindeks untuk semua perubahan antara 00:00:50 dan 00:01:32; mengambil doc1 dan doc2 00:01:20 Pengindeks meminta semua perubahan antara tanda air tinggi saat ini dikurangi buffer 30 detik, dan memulai stempel waktu eksekusi pengindeks saat ini.
00:01:34 Proses pengindeks doc1 untuk kedua kalinya 00:01:20
00:01:35 Proses pengindeks doc2 untuk ketiga kalinya 00:01:20
00:01:36 Pengindeks berakhir 00:01:32 Tanda air yang tinggi diperbarui untuk memulai stempel waktu eksekusi pengindeks saat ini.
00:01:40 Pengindeks dimulai 00:01:32
00:01:41 Kueri pengindeks untuk semua perubahan antara 00:01:02 dan 00:01:40; mengambil doc2 00:01:32 Pengindeks meminta semua perubahan antara tanda air tinggi saat ini dikurangi buffer 30 detik, dan memulai stempel waktu eksekusi pengindeks saat ini.
00:01:42 Proses pengindeks doc2 untuk keempat kalinya 00:01:32
00:01:43 Pengindeks berakhir 00:01:40 Perhatikan eksekusi pengindeks ini dimulai lebih dari 30 detik setelah penulisan terakhir ke sumber data dan juga memproses doc2. Ini adalah perilaku yang diharapkan karena jika semua eksekusi pengindeks sebelum 00:01:35 dihilangkan, ini menjadi eksekusi pertama dan satu-satunya untuk diproses doc1 dan doc2.

Dalam praktiknya, skenario ini hanya terjadi saat pengindeks sesuai permintaan dipanggil secara manual dalam hitungan menit satu sama lain, untuk sumber data tertentu. Ini dapat mengakibatkan angka yang tidak cocok (seperti pengindeks memproses total 345 dokumen sesuai dengan statistik eksekusi pengindeks, tetapi ada 340 dokumen dalam sumber data dan indeks) atau penagihan yang berpotensi meningkat jika Anda menjalankan keterampilan yang sama untuk dokumen yang sama beberapa kali. Menjalankan pengindeks menggunakan jadwal adalah rekomendasi yang dipilih.

Mengindeks dokumen dengan label sensitivitas

Jika Anda memiliki label sensitivitas yang diatur pada dokumen, Anda mungkin tidak dapat mengindeksnya. Jika Anda mendapatkan kesalahan, hapus label sebelum pengindeksan.

Baca juga