Memperbarui atau membangun ulang indeks di Pencarian Azure AI

Artikel ini menjelaskan cara memperbarui indeks yang ada di Pencarian Azure AI dengan perubahan skema atau perubahan konten melalui pengindeksan inkremental.

Prasyarat

• Layanan Pencarian Azure AI (tingkat apa pun). Buat layanan atau definisikan yang sudah ada.

• Indeks pencarian yang sudah ada dengan dokumen. Artikel ini mengasumsikan Anda sudah membuat indeks dan memuat dokumen.

• Izin untuk memperbarui atau membangun ulang indeks:

  • Autentikasi berbasis kunci: Kunci API admin untuk layanan pencarian Anda.
  • Autentikasi berbasis peran: Peran Kontributor Data Indeks Pencarian untuk pembaruan dokumen, atau Kontributor Layanan Pencarian untuk perubahan skema.

• Untuk pengembangan SDK, instal pustaka klien Azure Search:

  • Python: azure-search-documents
  • .NET: Azure. Search.Documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Memperbarui konten

Pengindeksan bertahap dan menyinkronkan indeks terhadap perubahan data sumber sangat mendasar untuk sebagian besar aplikasi pencarian. Bagian ini menjelaskan alur kerja untuk menambahkan, menghapus, atau menimpa konten indeks pencarian melalui REST API, namun Azure SDK menyediakan fungsionalitas yang setara.

Isi permintaan berisi satu atau beberapa dokumen yang akan diindeks. Dalam permintaan, setiap dokumen dalam indeks adalah:

• Diidentifikasi oleh kunci unik yang sensitif terhadap huruf besar/kecil.
• Terkait dengan tindakan: "upload", "delete", "merge", atau "mergeOrUpload".
• Diisi dengan sekumpulan pasangan nama/nilai untuk setiap bidang yang Anda tambahkan atau perbarui.

{  
  "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 (name/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

Referensi:Dokumen - Indeks

• Pertama, gunakan API untuk memuat dokumen, seperti Documents - Index (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, tergantung batas mana yang tercapai lebih dulu) direkomendasikan dan secara signifikan meningkatkan performa pengindeksan.

• Atur @search.action parameter pada API untuk menentukan efek pada dokumen yang ada. Gunakan mergeOrUpload untuk pembaruan inkremental (paling umum), delete untuk menghapus dokumen, atau merge untuk pembaruan bidang parsial pada dokumen yang sudah ada.

  Tindakan	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 di portal Azure dan melalui API. Untuk informasi selengkapnya, lihat Menghapus dokumen dalam indeks pencarian.
  gabung	Memperbarui dokumen yang sudah ada, dan gagal dokumen yang tidak dapat ditemukan. Penggabungan mengganti nilai yang ada. Untuk alasan ini, pastikan untuk memeriksa bidang koleksi yang berisi beberapa nilai, seperti bidang jenis Collection(Edm.String). Misalnya, jika bidang tags dimulai dengan nilai ["budget"] dan Anda menjalankan penggabungan dengan ["economy", "pool"], nilai akhir dari bidang tags 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.
  gabungkanAtauUnggah	Bertindak seperti penggabungan jika dokumen tersebut ada, dan unggah jika dokumen tersebut baru. Ini adalah tindakan paling umum untuk pembaruan inkremental.
  pengunggahan	Mirip dengan "upsert" di mana dokumen ditambahkan jika dokumen belum ada, dan diperbarui atau diganti jika sudah 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.

Respon

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 ini, Anda harus mencoba lagi setelah penundaan.

Jika kode klien Anda sering mendapatkan respons 207, salah satu alasan yang mungkin adalah sistem sedang mengalami beban. 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 pada jumlah dokumen per indeks. Anda harus meningkatkan batas kapasitas ke level yang lebih tinggi atau membuat indeks baru.

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 pencarian sehingga konten tersebut disinkronkan dengan 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. Memasukkan vektor ke 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. Ingat contoh bidang tags 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=2026-04-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=2026-04-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=2026-04-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Referensi:Dokumen - Indeks, Dokumen Pencarian

Contoh SDK

Contoh berikut menunjukkan cara memperbarui dokumen menggunakan Azure SDK.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-admin-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Update documents using merge_or_upload
documents = [
    {
        "HotelId": "1",
        "Description": "Updated description for the hotel.",
        "Tags": ["updated", "renovated"]
    }
]

result = client.merge_or_upload_documents(documents=documents)
print(f"Updated {len(result)} document(s)")

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Update documents using MergeOrUpload
var batch = IndexDocumentsBatch.MergeOrUpload(
    new[]
    {
        new Hotel { HotelId = "1", Description = "Updated description.", Tags = new[] { "updated", "renovated" } }
    });

IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(batch);
Console.WriteLine($"Updated {result.Results.Count} document(s)");

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 deskripsi indeks
• Menambahkan bidang baru
• retrievable Mengatur atribut pada bidang yang ada
• Memperbarui searchAnalyzer pada kolom 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 peta sinonim
• 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 as-is.

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 Pencarian Azure AI.

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 dalam 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 menghapus indeks tidak dapat dibatalkan, menghancurkan penyimpanan fisik untuk koleksi bidang dan struktur 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 menggunakan pencarian teks lengkap atau pencarian 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.

Menambahkan deskripsi indeks

Indeks memiliki description properti yang dapat Anda tentukan dan gunakan saat sistem harus mengakses beberapa indeks dan membuat keputusan berdasarkan deskripsi. Pertimbangkan server Protokol Konteks Model (MCP) yang harus memilih indeks yang benar pada waktu proses. Keputusan dapat didasarkan pada deskripsi daripada pada nama indeks saja.

Deskripsi indeks adalah pembaruan skema, dan Anda dapat menambahkannya tanpa harus membangun kembali seluruh indeks.

• Panjang string maksimum 4.000 karakter.
• Konten harus dapat dibaca manusia, di Unicode. Kasus penggunaan Anda harus menentukan bahasa mana yang akan digunakan.

Anda dapat menambahkan deskripsi indeks melalui portal Azure, REST API stabil terbaru, atau paket Azure SDK yang menyediakan fitur tersebut.

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 monitor 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.

Periksa pembaruan

Anda dapat mulai mengkueri indeks segera setelah dokumen pertama dimuat. Jika Anda mengetahui ID dokumen, REST API Dokumen Pencarian mengembalikan dokumen tertentu. Untuk pengujian yang lebih luas, Anda harus menunggu hingga indeks dimuat sepenuhnya, lalu menggunakan 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.

Mengatasi masalah pengindeksan ulang

Tabel berikut ini mencantumkan masalah umum saat memperbarui atau membangun ulang indeks dan cara mengatasinya.

Lihat juga

• Gambaran umum pengindeks
• Menghapus dokumen dari indeks pencarian
• Mengindeks himpunan data besar dalam skala besar
• Pengindeksan pada portal Azure
• Azure SQL Database pengindeks
• Azure Cosmos DB untuk pengindeks NoSQL
• Azure pengindeks blob
• Pengindeks Tabel Azure
• Perlindungan data, privasi, dan bawaan