Memperbarui atau membangun ulang indeks di Azure AI Search

Artikel ini menjelaskan cara memperbarui indeks yang sudah ada di Azure AI Search dengan perubahan skema atau perubahan konten melalui pengindeksan bertahas. Ini menjelaskan keadaan di mana pembangunan ulang diperlukan, dan memberikan rekomendasi untuk mengurangi efek pembangunan kembali pada permintaan kueri yang sedang berlangsung.

Selama pengembangan aktif, adalah umum untuk menghilangkan dan membangun kembali indeks saat Anda melakukan iterasi melalui desain indeks. Sebagian besar pengembang bekerja dengan sampel representatif kecil dari data mereka sehingga pengindeksaian ulang berjalan lebih cepat.

Untuk perubahan skema pada aplikasi yang sudah dalam produksi, sebaiknya buat dan uji indeks baru yang berjalan berdampingan dengan indeks yang ada. Gunakan alias indeks untuk bertukar dalam indeks baru sehingga Anda dapat menghindari perubahan kode aplikasi Anda.

Memperbarui konten

Pengindeksan bertahap dan menyinkronkan indeks terhadap perubahan data sumber sangat mendasar untuk sebagian besar aplikasi pencarian. Bagian ini menjelaskan alur kerja untuk memperbarui konten bidang dalam indeks pencarian melalui REST API, tetapi Azure SDK menyediakan fungsionalitas yang setara.

Isi permintaan berisi satu atau beberapa dokumen yang akan diindeks. Dokumen diidentifikasi oleh kunci peka huruf besar/kecil yang unik. Setiap dokumen dikaitkan dengan tindakan: "upload", "delete", "merge", atau "mergeOrUpload". Permintaan pengunggahan harus menyertakan data dokumen sebagai sekumpulan pasangan kunci/nilai.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

• Pertama, gunakan API untuk memuat dokumen, seperti Dokumen - Indeks (REST) atau API yang setara di Azure SDK. Untuk informasi selengkapnya tentang teknik pengindeksan, lihat Memuat dokumen.

• Untuk pembaruan besar, batching (hingga 1.000 dokumen per batch, atau sekitar 16 MB per batch, batas mana pun yang lebih dulu) direkomendasikan dan secara signifikan meningkatkan performa pengindeksan.

• Atur @search.action parameter pada API untuk menentukan efek pada dokumen yang ada.

  Perbuatan	Efek
  hapus	Menghapus seluruh dokumen dari indeks. Jika Anda ingin menghapus bidang individual, gunakan gabungkan sebagai gantinya, atur bidang yang bersangkutan ke null. Dokumen dan bidang yang dihapus tidak segera mengosongkan ruang dalam indeks. Setiap beberapa menit, proses latar belakang melakukan penghapusan fisik. Baik Anda menggunakan portal Azure atau API untuk mengembalikan statistik indeks, Anda dapat mengharapkan penundaan kecil sebelum penghapusan tercermin dalam portal Azure dan melalui API.
  gabungkan	Memperbarui dokumen yang sudah ada, dan gagal dokumen yang tidak dapat ditemukan. Gabung menggantikan nilai yang ada. Untuk alasan ini, pastikan untuk memeriksa bidang koleksi yang berisi beberapa nilai, seperti bidang jenis Collection(Edm.String). Misalnya, jika tags bidang dimulai dengan nilai ["budget"] dan Anda menjalankan penggabungan dengan ["economy", "pool"], nilai tags akhir bidang adalah ["economy", "pool"]. Ini tidak akan menjadi ["budget", "economy", "pool"]. Perilaku yang sama berlaku untuk koleksi kompleks. Jika dokumen berisi bidang koleksi kompleks bernama Kamar dengan nilai [{ "Type": "Budget Room", "BaseRate": 75.0 }], dan Anda menjalankan penggabungan dengan nilai [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], nilai akhir bidang Ruang akan menjadi [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Ini tidak akan menambahkan atau menggabungkan nilai baru dan yang sudah ada.
  mergeOrUpload	Berulah seperti gabungkan jika dokumen ada, dan unggah jika dokumen baru. Ini adalah tindakan paling umum untuk pembaruan inkremental.
  unggah	Mirip dengan "upsert" di mana dokumen disisipkan jika dokumen baru, dan diperbarui atau diganti jika ada. Jika dokumen kehilangan nilai yang diperlukan indeks, nilai bidang dokumen diatur ke null.

Kueri terus berjalan selama pengindeksan, tetapi jika Anda memperbarui atau menghapus bidang yang ada, Anda dapat mengharapkan hasil campuran dan insiden pembatasan yang lebih tinggi.

Respons

Kode status 200 dikembalikan untuk respons yang berhasil, yang berarti bahwa semua item telah disimpan dengan durably dan akan mulai diindeks. Pengindeksan berjalan di latar belakang dan membuat dokumen baru tersedia (yaitu, dapat dikueri dan dapat dicari) beberapa detik setelah operasi pengindeksan selesai. Penundaan spesifik tergantung pada beban pada layanan.

Pengindeksan yang berhasil ditunjukkan oleh properti status yang diatur ke true untuk semua item, serta statusCode properti yang diatur ke 201 (untuk dokumen yang baru diunggah) atau 200 (untuk dokumen yang digabungkan atau dihapus):

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

Kode status 207 dikembalikan ketika setidaknya satu item tidak berhasil diindeks. Item yang belum diindeks memiliki bidang status yang diatur ke false. Properti errorMessage dan statusCode menunjukkan alasan kesalahan pengindeksan:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

Properti errorMessage menunjukkan alasan kesalahan pengindeksan jika memungkinkan.

Tabel berikut menjelaskan berbagai kode status per dokumen yang dapat dikembalikan dalam respons. Beberapa kode status menunjukkan masalah dengan permintaan itu sendiri, sementara yang lain menunjukkan kondisi kesalahan sementara. Yang terakhir Anda harus mencoba kembali setelah penundaan.

Jika kode klien Anda sering mengalami respons 207, salah satu alasan yang mungkin adalah sistem sedang dimuat. Anda dapat mengonfirmasi ini dengan memeriksa properti statusCode untuk 503. Jika statusCode adalah 503, sebaiknya batasi permintaan pengindeksan. Jika tidak, jika lalu lintas pengindeksan tidak mereda, sistem dapat mulai menolak semua permintaan dengan kesalahan 503.

Kode status 429 menunjukkan bahwa Anda telah melebihi kuota Anda pada jumlah dokumen per indeks. Anda harus membuat indeks baru atau meningkatkan untuk batas kapasitas yang lebih tinggi.

Tips untuk pengindeksan inkremental

• Pengindeks mengotomatiskan pengindeksan inkremental. Jika Anda dapat menggunakan pengindeks, dan jika sumber data mendukung pelacakan perubahan, Anda dapat menjalankan pengindeks pada jadwal berulang untuk menambahkan, memperbarui, atau menimpa konten yang dapat dicari sehingga disinkronkan ke data eksternal Anda.

• Jika Anda melakukan panggilan indeks langsung melalui API push, gunakan mergeOrUpload sebagai tindakan pencarian.

• Payload harus menyertakan kunci atau pengidentifikasi setiap dokumen yang ingin Anda tambahkan, perbarui, atau hapus.

• Jika indeks Anda menyertakan bidang vektor dan Anda mengatur stored properti ke false, pastikan Anda memberikan vektor dalam pembaruan dokumen parsial Anda, bahkan jika nilainya tidak berubah. Efek samping pengaturan stored ke false adalah bahwa vektor dihilangkan pada operasi pengindeksan ulang. Menyediakan vektor dalam payload dokumen mencegah hal ini terjadi.

• Untuk memperbarui konten bidang dan subbidang sederhana dalam jenis kompleks, cantumkan hanya bidang yang ingin Anda ubah. Misalnya, jika Anda hanya perlu memperbarui bidang deskripsi, payload harus terdiri dari kunci dokumen dan deskripsi yang dimodifikasi. Menghilangkan bidang lain mempertahankan nilai yang ada.

• Untuk menggabungkan perubahan sebaris ke dalam koleksi string, berikan seluruh nilai. tags Ingat contoh bidang dari bagian sebelumnya. Nilai baru menimpa nilai lama untuk seluruh bidang, dan tidak ada penggabungan dalam konten bidang.

Berikut adalah contoh REST API yang menunjukkan tips berikut:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Memperbarui skema indeks

Skema indeks menentukan struktur data fisik yang dibuat pada layanan pencarian, sehingga tidak ada banyak perubahan skema yang dapat Anda buat tanpa menimbulkan pembangunan ulang penuh.

Pembaruan tanpa pembangunan ulang

Daftar berikut menghitung perubahan skema yang dapat diperkenalkan dengan mulus ke dalam indeks yang ada. Umumnya, daftar menyertakan bidang dan fungsionalitas baru yang digunakan selama eksekusi kueri.

• Menambahkan bidang baru
• retrievable Mengatur atribut pada bidang yang ada
• Pembaruan searchAnalyzer pada bidang yang sudah ada indexAnalyzer
• Menambahkan definisi penganalisis baru dalam indeks (yang dapat diterapkan ke bidang baru)
• Menambahkan, memperbarui, atau menghapus profil penilaian
• Menambahkan, memperbarui, atau menghapus synonymMaps
• Menambahkan, memperbarui, atau menghapus konfigurasi semantik
• Menambahkan, memperbarui, atau menghapus pengaturan CORS

Urutan operasi adalah:

1. Dapatkan definisi indeks.

2. Revisi skema dengan pembaruan dari daftar sebelumnya.

3. Perbarui skema indeks pada layanan pencarian.

4. Perbarui konten indeks agar sesuai dengan skema yang direvisi jika Anda menambahkan bidang baru. Untuk semua perubahan lainnya, konten terindeks yang ada digunakan apa adanya.

Saat Anda memperbarui skema indeks untuk menyertakan bidang baru, dokumen yang ada dalam indeks diberi nilai null untuk bidang tersebut. Pada pekerjaan pengindeksan berikutnya, nilai dari data sumber eksternal menggantikan null yang ditambahkan oleh Azure AI Search.

Seharusnya tidak ada gangguan kueri selama pembaruan, tetapi hasil kueri akan bervariasi saat pembaruan berlaku.

Pembaruan yang memerlukan pembangunan kembali

Beberapa modifikasi memerlukan penurunan dan pembangunan ulang indeks, mengganti indeks saat ini dengan yang baru.

Urutan operasi adalah:

1. Dapatkan definisi indeks jika Anda memerlukannya untuk referensi di masa mendatang, atau untuk digunakan sebagai dasar untuk versi baru.

2. Pertimbangkan untuk menggunakan solusi pencadangan dan pemulihan untuk mempertahankan salinan konten indeks. Ada solusi di C# dan di Python. Kami merekomendasikan versi Python karena versi ini lebih terbaru.

   Jika Anda memiliki kapasitas pada layanan pencarian Anda, pertahankan indeks yang ada saat membuat dan menguji yang baru.

3. Hilangkan indeks yang ada. Kueri yang menargetkan indeks segera dihilangkan. Ingatlah bahwa indeks yang dihapus tidak dapat dikembalikan, ini menghancurkan penyimpanan fisik untuk kumpulan bidang dan konstruk lainnya.

4. Posting indeks yang direvisi, di mana isi permintaan menyertakan definisi dan konfigurasi bidang yang diubah atau dimodifikasi.

5. Muat indeks dengan dokumen dari sumber eksternal. Dokumen diindeks menggunakan definisi bidang dan konfigurasi skema baru.

Saat Anda membuat indeks, penyimpanan fisik dialokasikan untuk setiap bidang dalam skema indeks, dengan indeks terbalik yang dibuat untuk setiap bidang yang dapat dicari dan indeks vektor yang dibuat untuk setiap bidang vektor. Bidang yang tidak dapat dicari dapat digunakan dalam filter atau ekspresi, tetapi tidak memiliki indeks terbalik dan tidak dapat dicari teks lengkap atau fuzzy. Pada pembangunan ulang indeks, indeks terbalik dan indeks vektor ini dihapus dan dibuat ulang berdasarkan skema indeks yang Anda berikan.

Untuk meminimalkan gangguan pada kode aplikasi, pertimbangkan untuk membuat alias indeks. Kode aplikasi mereferensikan alias, tetapi Anda dapat memperbarui nama indeks yang ditunjuk oleh alias.

Menyeimbangkan beban kerja

Pengindeksan tidak berjalan di latar belakang, tetapi layanan pencarian akan menyeimbangkan pekerjaan pengindeksan apa pun terhadap kueri yang sedang berlangsung. Selama pengindeksan, Anda dapat memantau permintaan kueri di portal Azure untuk memastikan kueri selesai tepat waktu.

Jika beban kerja pengindeksan memperkenalkan tingkat latensi kueri yang tidak dapat diterima, lakukan analisis performa dan tinjau tips performa ini untuk potensi mitigasi.

Memeriksa pembaruan

Anda dapat segera mulai mengkueri indeks setelah dokumen pertama dimuat. Jika Anda mengetahui ID dokumen, API REST Lookup Document mengembalikan dokumen tersebut. Untuk pengujian yang lebih luas, Anda harus menunggu sampai indeks dimuat sepenuhnya, lalu gunakan kueri untuk memverifikasi konteks yang ingin Anda lihat.

Anda dapat menggunakan Penjelajah Pencarian atau klien REST untuk memeriksa konten yang diperbarui.

Jika Anda menambahkan atau mengganti nama bidang, gunakan pilih untuk mengembalikan bidang tersebut:

"search": "*",
"select": "document-id, my-new-field, some-old-field",
"count": true

portal Azure menyediakan ukuran indeks dan ukuran indeks vektor. Anda dapat memeriksa nilai-nilai ini setelah memperbarui indeks, tetapi ingatlah untuk mengharapkan penundaan kecil saat layanan memproses perubahan dan untuk memperhitungkan laju refresh portal, yang bisa beberapa menit.

Menghapus dokumen yatim piatu

Azure AI Search mendukung operasi tingkat dokumen sehingga Anda dapat mencari, memperbarui, dan menghapus dokumen tertentu dalam isolasi. Contoh berikut menunjukkan cara menghapus dokumen.

Menghapus dokumen tidak segera mengosongkan ruang dalam indeks. Setiap beberapa menit, proses latar belakang melakukan penghapusan fisik. Baik Anda menggunakan portal Azure atau API untuk mengembalikan statistik indeks, Anda dapat mengharapkan penundaan kecil sebelum penghapusan tercermin dalam metrik portal Azure dan API.

1. Identifikasi bidang mana yang merupakan kunci dokumen. Di portal Azure, Anda dapat melihat bidang dari setiap indeks. Kunci dokumen adalah bidang string dan ditandai dengan ikon kunci untuk membuatnya lebih mudah dilihat.

2. Periksa nilai bidang kunci dokumen: search=*&$select=HotelId. String sederhana mudah, tetapi jika indeks menggunakan bidang berkode base-64, atau jika dokumen pencarian dihasilkan dari parsingMode pengaturan, Anda mungkin bekerja dengan nilai yang tidak Anda kenal.

3. Cari dokumen untuk memverifikasi nilai ID dokumen dan meninjau kontennya sebelum menghapusnya. Tentukan ID kunci atau dokumen dalam permintaan. Contoh berikut mengilustrasikan string sederhana untuk indeks sampel Hotel dan string yang dikodekan base-64 untuk kunci metadata_storage_path indeks cog-search-demo.

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01
   

   GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
   

4. Hapus dokumen menggunakan penghapusan @search.action untuk menghapusnya dari indeks pencarian.

   POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
   Content-Type: application/json   
   api-key: [admin key] 
   {  
     "value": [  
       {  
         "@search.action": "delete",  
         "id": "1111"  
       }  
     ]  
   }
   

Lihat juga

• Ringkasan pengindeks
• Mengindeks himpunan data besar dalam skala
• Pengindeksan di portal Azure
• Pengindeks Azure SQL Database
• Pengindeks Azure Cosmos DB for NoSQL
• Pengindeks blob Azure
• Pengindeks tabel Azure
• Keamanan di Azure AI Search