Panduan pemecahan masalah pengindeks untuk Pencarian Azure AI

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.

Praktik terbaik

Ini adalah beberapa praktik dan rekomendasi terbaik saat bekerja dengan pengindeks:

Pengindeks dirancang untuk berjalan sesuai jadwal

• Untuk pengindeksan yang andal, konfigurasikan pengindeks Anda agar berjalan sesuai jadwal reguler. Eksekusi terjadwal secara otomatis mengambil dokumen apa pun yang terlewatkan dalam eksekusi sebelumnya karena kesalahan sementara, gangguan jaringan, atau masalah layanan sementara. Pendekatan ini membantu menjaga konsistensi data dan meminimalkan kebutuhan intervensi manual.
• Untuk sumber data besar, enumerasi dan pengindeksan awal dapat memakan waktu berjam-jam atau bahkan ber hari. Menjalankan pengindeks Anda sesuai jadwal memungkinkan kemajuan berlanjut dan kesalahan dicoba kembali secara otomatis. Hindari hanya mengandalkan eksekusi pengindeks manual atau sesuai permintaan, karena opsi ini tidak memberikan keandalan atau pemulihan kesalahan sementara yang sama.

Pengindeks menyediakan usaha terbaik dalam pengindeksan dari waktu ke waktu

• Pengindeks bawaan memproses dokumen yang tidak mengalami kesalahan permanen dan akan mencoba lagi pada eksekusi terjadwal berikutnya. Mereka menawarkan cara yang nyaman, kode rendah atau tanpa kode untuk mengindeks data untuk skenario umum, memungkinkan pengembangan yang lebih cepat dan pemeliharaan yang lebih mudah. Saat pengindeks menjalankan kumpulan keterampilan, setiap proses memiliki batas waktu eksekusi yang tetap. Pengindeks yang berjalan di lingkungan eksekusi multipenyewa memiliki waktu proses maksimum dua jam. Batas ini adalah kasus yang paling umum, digunakan jika skillset tidak memerlukan tautan privat bersama. Pengindeks yang dikonfigurasi untuk menggunakan tautan privat bersama berjalan di lingkungan eksekusi privat dengan durasi maksimum 24 jam. Untuk tabel lengkap, lihat Batas pengindeks. Jika pemrosesan skillset per dokumen membuat pengindeks tidak dapat menyelesaikan prosesnya sebelum batas waktu, pengindeks akan berhenti dan membiarkan dokumen yang tersisa tidak diproses. Pemrosesan lengkap tidak dijamin ketika volume dokumen, ukuran file, kompleksitas keterampilan, atau lingkungan eksekusi mencegah pengindeks menyelesaikan dalam waktu proses maksimumnya. Pemartisian sumber data Anda dapat mengurangi risiko ini tetapi tidak menghilangkannya, terutama jika Anda kemudian menambahkan file dalam volume besar ke partisi. Perilaku ini diharapkan. Untuk strategi mengelola himpunan data besar dan mendukung pemulihan bertambah bertahap, lihat Mengindeks himpunan data besar dan Menjadwalkan pengindeks. Jika solusi Anda memerlukan kontrol ketat saat pengindeks memproses dokumen, gunakan alternatif Push API dalam artikel ini.
• Jika solusi Anda memerlukan kontrol ketat atas garis waktu pengindeksan, gunakan API Push, seperti REST API Indeks Dokumen atau metode IndexDocuments (Azure SDK untuk .NET). Opsi ini memberi Anda kontrol penuh atas alur pengindeksan.
• Pengindeks kadang-kadang bisa kehabisan jadwal. Meskipun kondisi ini jarang terjadi dan ada mekanisme pemulihan otomatis, pemulihan mungkin membutuhkan waktu. Perilaku ini diharapkan.

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 endpoint pribadi menggunakan tautan pribadi bersama.

Kesalahan saat menyambungkan ke sumber daya Microsoft Foundry pada koneksi privat

Jika Anda mendapatkan kode kesalahan 403 dengan pesan berikut, Anda mungkin memiliki masalah dengan bagaimana titik akhir sumber daya ditentukan dalam set keterampilan:

• "A Virtual Network is configured for this resource. Please use the correct endpoint for making requests. Check https://aka.ms/cogsvc-vnet for more details."

Kesalahan ini terjadi jika Anda mengonfigurasi tautan privat bersama untuk koneksi ke sumber daya Azure Foundry dan titik akhir tidak memiliki subdomain kustom. Subdomain kustom adalah bagian pertama dari titik akhir (misalnya, http://my-custom-subdomain.services.ai.azure.com). Domain kustom mungkin hilang jika Anda membuat sumber daya di portal Foundry alih-alih portal Microsoft Azure.

Jika sumber daya Foundry tidak berada di wilayah yang sama dengan Pencarian Azure AI, gunakan koneksi tanpa kunci untuk melampirkan sumber daya.

Kesalahan saat menggunakan tautan pribadi bersama

Jika Anda mendapatkan kode kesalahan 403 dengan pesan berikut, pengindeks mungkin tersambung melalui titik akhir publik alih-alih tautan privat bersama yang disetujui:

Unexpected error validating provided resource. {"error":{"code":"403","message":"Public access is disabled. Please configure private endpoint."}}

Kesalahan ini dapat terjadi ketika pengindeks tidak dikonfigurasi untuk menggunakan lingkungan eksekusi privat. Konfirmasikan bahwa tautan privat bersama disetujui, atur pengindeks executionEnvironment ke private, dan verifikasi bahwa koneksi menggunakan titik akhir sumber daya dan ID grup yang benar.

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

Untuk mengizinkan pengindeks mengakses sumber daya ini, gunakan salah satu opsi berikut:

• Konfigurasikan aturan penerimaan untuk alamat IP layanan pencarian Anda dan rentang alamat IP dari AzureCognitiveSearchservice tag. Untuk detail tentang mengonfigurasi pembatasan rentang alamat IP untuk setiap jenis sumber data, lihat tautan berikut:

  • Azure Storage
  • Azure Cosmos DB
  • Azure SQL

• 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 mengirimkan permintaan ke luar melalui skillset dan custom skills. Untuk keterampilan kustom berdasarkan fungsi Azure, ketahuilah bahwa fungsi Azure juga memiliki batasan alamat IP. Daftar alamat IP yang diizinkan untuk mengakses eksekusi keterampilan kustom mencakup alamat IP dari layanan pencarian Anda dan rentang alamat IP dari tag layanan AzureCognitiveSearch.

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 ini:

• Pastikan Anda dapat mengakses sumber Anda 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 apakah ada pemadaman jaringan dalam Status Azure.
• Verifikasi bahwa Anda menggunakan DNS publik untuk resolusi nama dan bukan Azure Private DNS.

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, upaya masuk pertama dari layanan pencarian Anda akan secara otomatis mengaktifkan kembali database, tetapi justru mengembalikan pesan kesalahan yang menyatakan bahwa database tidak tersedia, dengan kode kesalahan 40613. Setelah database berjalan, coba lagi masuk untuk membuat konektivitas.

Kebijakan Akses Bersyarat Microsoft Entra

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

Untuk memperbarui kebijakan dan mengizinkan akses pengindeks ke pustaka dokumen:

1. Buka portal Azure dan cari Akses Bersyarat Microsoft Entra.

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 .
   • Atur Status perangkat 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.

   

   Sekarang setelah Anda memperoleh FQDN, dapatkan alamat IP dari layanan pencarian dengan melakukan nslookup (atau ping) pada FQDN. Dalam contoh berikut, Anda 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 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 .

   Anda bisa mendapatkan rentang alamat IP untuk AzureCognitiveSearch tag layanan melalui API penemuan atau file JSON yang dapat diunduh.

   Untuk latihan ini, dengan asumsi layanan pencarian adalah cloud Azure Public, unduh file JSON Publik Azure.

   

   Dari file JSON, dengan asumsi bahwa layanan pencarian berada di West Central US, daftar alamat IP untuk lingkungan eksekusi pengindeks multitenan terdaftar.

       {
         "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 hingga kebijakan diperbarui dan aturan kebijakan baru diberlakukan.

9. Coba buat pengindeks lagi:

   1. Kirim permintaan pembaruan untuk objek sumber data yang Anda buat.
   2. Kirim ulang permintaan pembuatan 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 ada masalah dengan dokumen individual.

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-04-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 diindeks layanan pencarian. Terkadang, dokumen yang ada di sumber data gagal muncul dalam indeks pencarian. Hasil yang tidak terduga ini dapat terjadi karena alasan berikut:

• Anda memperbarui dokumen setelah pengindeks dijalankan. Jika pengindeks Anda mengikuti jadwal, pengindeks pada akhirnya akan menjalankan kembali 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 Azure atau dengan memanggil Dapatkan Status Pengindeks (REST API).
• Pemetaan bidang atau pengayaan AI mengubah dokumen dan artikulasinya dalam indeks pencarian berbeda dari yang Anda harapkan.
• Nilai pelacakan perubahan salah atau prasyarat tidak ada. Jika nilai batas atas Anda berupa tanggal yang disetel ke waktu di masa mendatang, pengindeks akan melewati dokumen apa pun yang memiliki tanggal lebih awal. Anda dapat menentukan status pelacakan perubahan pengindeks dengan menggunakan bidang initialTrackingState dan finalTrackingState di 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.

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, Anda harus mengonfigurasi pengindeks blob untuk mengekstrak konten dan metadata:

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

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

Konten yang hilang dari Azure Cosmos DB

Pencarian Azure AI memiliki dependensi implisit pada pengindeksan Azure Cosmos DB. Jika Anda menonaktifkan pengindeksan otomatis di Azure Cosmos DB, Pencarian Azure AI 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 memperlihatkan jumlah dokumen nyata, terutama dalam portal Azure.
• 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. Kondisi 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, saat berada dalam kueri definisi sumber data, Anda mungkin hanya memilih subset rekaman untuk diindeks.
• Jumlah 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. Akibatnya, 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 perlu waktu lebih lama untuk mencapai konsistensi akhir. Kondisi ini sangat umum jika salah satu kriteria berikut ini benar:

• Permintaan pengindeks sesuai permintaan dikirimkan secara berurutan dalam waktu singkat.
• Topologi sumber data mencakup beberapa replika dan partisi, seperti topologi yang dijelaskan dalam Tingkat konsistensi dalam Azure Cosmos DB.
• Sumber data adalah database Azure SQL dan kolom yang dipilih sebagai "high water mark" bertipe 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, lajukan permintaan Anda dalam interval lima menit atau lebih, dan jalankan pengindeks sesuai jadwal.

Contoh pemrosesan dokumen duplikat dengan buffer 30 detik

Garis waktu berikut menjelaskan kondisi di mana dokumen diproses dua kali. Ini mencatat setiap tindakan dan tindakan balasan. Garis waktu berikut menggambarkan masalah:

Dalam praktiknya, skenario ini hanya terjadi ketika Anda secara manual memanggil pengindeks sesuai permintaan 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.

Pengindeksan paralel

Ketika beberapa pengindeks berjalan pada saat yang sama, beberapa pengindeks biasanya masuk ke antrean dan menunggu sumber daya yang tersedia sebelum mulai berjalan. Beberapa faktor menentukan berapa banyak pengindeks yang dapat berjalan secara bersamaan. Jika pengindeks tidak menautkan ke set keterampilan, jumlah replika dan partisi dalam layanan Pencarian AI menentukan berapa banyak pengindeks yang dapat berjalan secara paralel.

Jika Anda mengaitkan pengindeks dengan kumpulan keterampilan, pengindeks tersebut akan berjalan di kluster internal AI Search. Kompleksitas kumpulan keterampilan dan apakah kumpulan keterampilan lain berjalan pada saat yang sama menentukan jumlah pengindeks yang dapat berjalan secara bersamaan. Pengindeks bawaan dengan andal mengekstrak data dari sumber, sehingga tidak ada data yang terlewatkan jika dijalankan sesuai jadwal. Namun, proses pengindeksan untuk paralelisasi dan penskalaan horizontal memerlukan beberapa waktu untuk selesai.

Mengindeks dokumen dengan label sensitivitas

Jika Anda mengatur label sensitivitas pada dokumen, Anda mungkin tidak dapat mengindeksnya. Jika Anda mendapatkan kesalahan, hapus label sebelum mengindeks.

Konten terkait

• Pemecahan masalah kesalahan dan peringatan pengindeksan umum
• Memantau pengindeksan berbasis pengindeks
• Mengindeks himpunan data besar