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, jikatags
bidang dimulai dengan nilai["budget"]
dan Anda menjalankan penggabungan dengan["economy", "pool"]
, nilaitags
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.
Catatan
Tidak ada jaminan pengurutan yang tindakannya dalam isi permintaan dijalankan terlebih dahulu. Tidak disarankan untuk memiliki beberapa tindakan "gabungkan" yang terkait dengan dokumen yang sama dalam satu isi permintaan. Jika ada beberapa tindakan "gabungkan" yang diperlukan untuk dokumen yang sama, lakukan penggabungan sisi klien sebelum memperbarui dokumen dalam indeks pencarian.
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.
Kode status | Makna | Dapat Dicoba Lagi | Catatan |
---|---|---|---|
200 | Dokumen berhasil diubah atau dihapus. | n/a | Operasi penghapusan adalah tidak dapat diubah. Artinya, bahkan jika kunci dokumen tidak ada dalam indeks, mencoba operasi penghapusan dengan kunci tersebut menghasilkan kode status 200. |
201 | Dokumen berhasil dibuat. | n/a | |
400 | Terjadi kesalahan dalam dokumen yang mencegahnya diindeks. | No | Pesan kesalahan dalam respons menunjukkan apa yang salah dengan dokumen. |
404 | Dokumen tidak dapat digabungkan karena kunci yang diberikan tidak ada dalam indeks. | No | Kesalahan ini tidak terjadi untuk unggahan karena mereka membuat dokumen baru, dan tidak terjadi untuk penghapusan karena idempogen. |
409 | Konflik versi terdeteksi saat mencoba mengindeks dokumen. | Ya | Hal ini bisa terjadi ketika Anda mencoba mengindeks dokumen yang sama lebih dari satu kali secara bersamaan. |
422 | Indeks sementara tidak tersedia karena diperbarui dengan bendera 'allowIndexDowntime' diatur ke 'true'. | Ya | |
503 | Layanan pencarian Anda untuk sementara tidak tersedia, mungkin karena beban berat. | Ya | Dalam kasus ini, kode Anda harus menunggu sebelum mencoba lagi atau Anda berisiko memperpanjang tidak tersedianya layanan. |
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.
Catatan
Saat Anda mengunggah DateTimeOffset
nilai dengan informasi zona waktu ke indeks Anda, Azure AI Search menormalkan nilai-nilai ini ke UTC. Misalnya, 2024-01-13T14:03:00-08:00 disimpan sebagai 2024-01-13T22:03:00Z. Jika Anda perlu menyimpan informasi zona waktu, tambahkan kolom tambahan ke indeks Anda untuk titik data ini.
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 pengaturanstored
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 adaindexAnalyzer
- 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:
Dapatkan definisi indeks.
Revisi skema dengan pembaruan dari daftar sebelumnya.
Perbarui skema indeks pada layanan pencarian.
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.
Tindakan | Deskripsi |
---|---|
Menghapus bidang | Untuk secara fisik menghapus semua jejak bidang, Anda harus membangun ulang indeks. Ketika pembangunan ulang langsung tidak praktis, Anda dapat memodifikasi kode aplikasi untuk mengalihkan akses dari bidang usang atau menggunakan searchFields dan memilih parameter kueri untuk memilih bidang mana yang dicari dan dikembalikan. Secara fisik, definisi bidang dan konten tetap berada dalam indeks hingga pembangunan kembali berikutnya, ketika Anda menerapkan skema yang menghilangkan bidang yang dimaksud. |
Mengubah definisi bidang | Revisi ke nama bidang, jenis data, atau atribut indeks tertentu (dapat dicari, dapat difilter, dapat diurutkan, dapat difaset) memerlukan pembangunan ulang penuh. |
Menetapkan penganalisis ke suatu bidang | Penganalisis didefinisikan dalam indeks, ditetapkan ke bidang, lalu dipanggil selama pengindeksan untuk mengindeks cara token dibuat. Anda dapat menambahkan definisi penganalisis baru ke indeks kapan saja, tetapi Anda hanya dapat menetapkan penganalisis saat bidang telah dibuat. Hal ini berlaku baik untuk properti penganalisis dan indexAnalyzer. Properti searchAnalyzer adalah pengecualian (Anda dapat menetapkan properti ini ke bidang yang ada). |
Memperbarui atau menghapus definisi penganalisis dalam indeks | Anda tidak dapat menghapus atau mengubah konfigurasi penganalisis yang ada (penganalisis, tokenizer, filter token, atau filter karakter) dalam indeks kecuali Anda membangun kembali seluruh indeks. |
Menambahkan bidang ke pemberi saran | Jika bidang sudah ada dan Anda ingin menambahkannya ke konstruksi Pemberi Saran, bangun ulang indeks. |
Mengalihkan tingkatan | Peningkatan di tempat tidak didukung. Jika Anda memerlukan lebih banyak kapasitas, buat layanan baru dan bangun ulang indeks Anda dari awal. Untuk membantu mengotomatiskan proses ini, Anda dapat menggunakan kode sampel index-backup-restore di repositori sampel Azure AI Search .NET ini. Aplikasi ini mencadangkan indeks Anda ke serangkaian file JSON, lalu membuat ulang indeks dalam layanan pencarian yang Anda tentukan. |
Urutan operasi adalah:
Dapatkan definisi indeks jika Anda memerlukannya untuk referensi di masa mendatang, atau untuk digunakan sebagai dasar untuk versi baru.
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.
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.
Posting indeks yang direvisi, di mana isi permintaan menyertakan definisi dan konfigurasi bidang yang diubah atau dimodifikasi.
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.
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.
Periksa nilai bidang kunci dokumen:
search=*&$select=HotelId
. String sederhana mudah, tetapi jika indeks menggunakan bidang berkode base-64, atau jika dokumen pencarian dihasilkan dariparsingMode
pengaturan, Anda mungkin bekerja dengan nilai yang tidak Anda kenal.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
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" } ] }