Memperbarui atau membangun ulang indeks di Azure AI Search

Artikel
09/01/2024

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 menukar indeks baru sambil 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.

Gunakan teknik yang sama untuk memuat dokumen: Dokumen - Indeks (REST) atau API yang setara di Azure SDK. Untuk informasi selengkapnya tentang teknik pengindeksan, lihat Memuat dokumen.

Atur @search.action parameter 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 atau API untuk mengembalikan statistik indeks, Anda dapat mengharapkan penundaan kecil sebelum penghapusan tercermin di portal 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"]`.
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.

Posting pembaruan.

Kueri terus berjalan, tetapi jika Anda memperbarui atau menghapus bidang yang ada, Anda dapat mengharapkan hasil campuran dan insiden pembatasan 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 Secret Point 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 Secret Point 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 Secret Point 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}}

Mengubah 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. 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 pengaturan CORS
Menambahkan, memperbarui, atau menghapus synonymMaps
Menambahkan, memperbarui, atau menghapus konfigurasi semantik

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.

Menghapus dan membangun kembali indeks

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.

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 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 $select 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 atau API untuk mengembalikan statistik indeks, Anda dapat mengharapkan penundaan kecil sebelum penghapusan tercermin dalam metrik portal dan API.

Identifikasi bidang mana yang merupakan kunci dokumen. Di portal, Anda dapat melihat bidang 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 dari parsingMode 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"  
    }  
  ]  
}

Bagikan melalui