Mengelola cache pengayaan (pratinjau)

Note

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Penting

Fitur, kemampuan, atau properti yang ditandai (pratinjau) tidak tercakup dalam perjanjian tingkat layanan, tidak disarankan untuk beban kerja produksi, dan mungkin berubah atau dibatasi sebelum tersedia secara umum. Ketentuan pratinjau Pencarian Azure AI berlaku untuk semua fungsionalitas pratinjau, baik itu mandiri atau bagian dari fitur yang tersedia secara umum.

cache pengayaan (pratinjau) adalah fitur opsional yang menyimpan konten hasil pengayaan yang dibuat selama eksekusi rangkaian keterampilan. Ini mempertahankan konten antara eksekusi sehingga hanya keterampilan dan dokumen yang berubah yang memerlukan pemrosesan ulang. Ini bukan cadangan output skillset, status pengindeks, atau dokumen terindeks.

Anda membuat cache pengayaan di Azure Storage. Cache berisi keluaran dari pemecahan dokumen, ditambah keluaran dari setiap fungsi untuk setiap dokumen. Meskipun caching dikenakan biaya (menggunakan Azure Storage), biaya keseluruhan pengolahan berkurang karena biaya penyimpanan lebih rendah daripada biaya ekstraksi gambar dan pemrosesan AI.

Jika Anda mengonfigurasi cache pengayaan, artikel ini menjelaskan cara mengelola pembaruan keterampilan dan sumber data sehingga Anda mendapatkan utilitas maksimum dari pengayaan yang di-cache.

Prasyarat

Keterbatasan

Perhatian

Jika Anda menggunakan pengindeks SharePoint (pratinjau), hindari pengayaan inkremental. Dalam keadaan tertentu, cache menjadi tidak valid. Untuk memuat ulang, lakukan reset pengindeks dan pembangunan ulang penuh.

Sumber data besar memiliki batasan cache tambahan.

Perhatian

Untuk sumber data berukuran besar, cache pengayaan dapat meningkatkan total pemrosesan ulang ketika skill yang berjalan lama, gangguan berulang, atau skill yang sering gagal terjadi. Pengindeks memprioritaskan kebenaran daripada meminimalkan pemrosesan ulang, sehingga backlog cache dari gangguan berulang memperkuat perilaku coba lagi.

Untuk memulihkan dari backlog cache yang berkembang, partisi sumber data menjadi kontainer atau folder virtual yang lebih kecil. Kemudian gunakan pengindeks paralel yang menunjuk ke indeks yang sama. Untuk memisahkan cache, atur cache properti ke null pada pengindeks.

Konfigurasi cache

Secara fisik, cache disimpan dalam kontainer blob dan tabel di akun Azure Storage Anda, satu per pengindeks. Setiap pengindeks diberi pengidentifikasi cache unik dan tidak dapat diubah yang sesuai dengan kontainer yang digunakannya.

Cache dibuat saat Anda menentukan cache properti dan menjalankan pengindeks. Hanya konten yang diperkaya yang dapat di-cache. Jika pengindeks Anda tidak memiliki skillset terlampir, maka caching tidak berlaku.

Contoh berikut mengilustrasikan pengindeks dengan penyimpanan sementara diaktifkan. Lihat Pengaturan penyimpanan sementara pengayaan untuk instruksi lengkap.

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-08-01-preview
    {
        "name": "myIndexerName",
        "targetIndexName": "myIndex",
        "dataSourceName": "myDatasource",
        "skillsetName": "mySkillset",
        "cache" : {
            "storageConnectionString" : "<Your storage account connection string>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Manajemen cache

Pengindeks mengelola siklus hidup cache. Jika Anda menghapus pengindeks, Anda juga menghapus cache-nya. Jika Anda mengatur properti pengindeks cache ke null atau mengubah string koneksi, cache yang ada akan dihapus selama pengindeks berikutnya dijalankan.

Meskipun pengayaan inkremental dirancang untuk mendeteksi dan merespons perubahan tanpa intervensi pada bagian Anda, Anda dapat mengatur parameter untuk memanggil perilaku tertentu:

Memprioritaskan dokumen baru

Properti cache menyertakan enableReprocessing parameter yang mengontrol apakah konten yang di-cache diolah ulang. Jika true (default), pengindeks akan memproses ulang dokumen dalam cache saat Anda menjalankannya lagi jika pembaruan skill memengaruhi dokumen tersebut.

Ketika false, pengindeks tidak memproses ulang dokumen yang ada, yang memprioritaskan konten baru. Atur enableReprocessing ke false hanya untuk sementara. Memastikan keakuratan sebagian besar waktu menjamin bahwa dokumen baru dan yang sudah ada tetap valid sesuai definisi kemampuan terkini.

Mengabaikan evaluasi keterampilan

Memodifikasi keterampilan biasanya berjalan seiring dengan pemrosesan ulang keterampilan itu. Namun, beberapa perubahan pada keterampilan tidak boleh memicu pemrosesan ulang. Misalnya, menyebarkan keterampilan kustom ke lokasi baru atau dengan kunci akses baru. Perubahan ini biasanya merupakan modifikasi periferal yang tidak memengaruhi substansi output keterampilan.

Jika Anda tahu bahwa perubahan pada keterampilan bersifat dangkal, ambil alih evaluasi keterampilan dengan mengatur disableCacheReprocessingChangeDetection parameter ke true:

  1. Panggil Perbarui Skillset dan ubah definisi set keterampilan.
  2. Tambahkan disableCacheReprocessingChangeDetection=true parameter pada permintaan.
  3. Kirim perubahan.

Saat Anda mengatur parameter ini, hanya pembaruan pada definisi skillset yang diterapkan. Perubahan tidak dievaluasi untuk efek pada cache yang ada. Gunakan versi API pratinjau 2020-06-30 atau yang lebih baru. Gunakan API pratinjau terbaru.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2026-08-01-preview&disableCacheReprocessingChangeDetection

Melewati pemeriksaan validasi sumber data

Sebagian besar perubahan pada definisi sumber data membatalkan cache. Namun, untuk skenario di mana Anda tahu bahwa perubahan tidak boleh membatalkan cache - seperti mengubah string koneksi atau memutar kunci pada akun penyimpanan - tambahkan parameter ignoreResetRequirement pada perbarui sumber data. Atur parameter ini ke true untuk memungkinkan penerapan dilalui, tanpa memicu kondisi reset yang akan mengakibatkan semua objek dibangun kembali dan diisi dari awal.

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-08-01-preview&ignoreResetRequirement

Memaksakan penilaian kemampuan

Tujuan dari cache adalah untuk menghindari pemrosesan yang tidak perlu. Tetapi misalkan Anda membuat perubahan pada keterampilan yang tidak dideteksi oleh pengindeks (misalnya, mengubah sesuatu dalam kode eksternal, seperti keterampilan kustom).

Dalam hal ini, gunakan Reset Skills API untuk memaksa pemrosesan ulang keterampilan tertentu, termasuk keterampilan hilir apa pun yang memiliki dependensi pada output keterampilan tersebut. API ini menerima permintaan POST dengan daftar keterampilan yang harus divalidasi dan ditandai untuk pemrosesan ulang. Setelah mereset kemampuan, ikuti dengan melakukan permintaan Run Indexer untuk memanggil pemrosesan pipeline.

Cache ulang dokumen tertentu

Jika Anda mengatur ulang pengindeks, semua dokumen di korpus pencarian akan diproseksi ulang.

Dalam skenario di mana hanya beberapa dokumen yang perlu diolah ulang, gunakan Reset Dokumen (pratinjau) untuk memaksa pemrosesan ulang dokumen tertentu. Saat Anda mengatur ulang dokumen, pengindeks membatalkan cache untuk dokumen tersebut. Pengindeks kemudian memproses ulang dokumen dengan membacanya dari sumber data. Untuk informasi selengkapnya, lihat Menjalankan atau mengatur ulang pengindeks, keterampilan, dan dokumen.

Untuk mereset dokumen tertentu, sertakan daftar kunci dokumen sebagaimana dibaca dari indeks pencarian dalam permintaan. Jika kunci merujuk ke bidang dalam sumber data eksternal, gunakan nilai dari indeks pencarian.

Tergantung pada cara Anda memanggil API, permintaan akan menambahkan, menimpa, atau mengantrikan daftar kunci:

  • Memanggil API beberapa kali dengan kunci yang berbeda menambahkan kunci baru ke daftar kunci dokumen untuk direset.

  • Memanggil API dengan parameter string kueri overwrite yang disetel ke true akan menimpa daftar kunci dokumen saat ini yang akan direset dengan payload permintaan.

  • Memanggil API menambahkan kunci dokumen ke antrean pekerjaan yang dilakukan pengindeks. Ketika pengindeks berikutnya dipanggil, baik sebagai terjadwal atau sesuai permintaan, pengindeks memprioritaskan pemrosesan kunci dokumen reset sebelum perubahan lain dari sumber data.

Contoh berikut mengilustrasikan permintaan reset dokumen:

POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2026-08-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

Perubahan yang membatalkan cache

Saat Anda mengaktifkan cache, pengindeks memeriksa perubahan dalam komposisi alur Anda untuk memutuskan konten mana yang dapat digunakan kembali dan konten mana yang perlu diolah ulang. Bagian ini menampilkan perubahan yang membuat cache tidak valid, diikuti oleh perubahan yang memicu pemrosesan inkremental.

Perubahan yang menyebabkan invalidasi adalah perubahan yang membuat seluruh cache menjadi tidak valid. Misalnya, memperbarui sumber data Anda adalah perubahan yang tidak valid. Berikut adalah daftar lengkap perubahan pada bagian mana pun dari alur pengindeks yang membatalkan cache Anda:

  • Mengubah jenis sumber data
  • Mengubah kontainer sumber data
  • Mengubah kredensial sumber data
  • Mengubah kebijakan deteksi perubahan sumber data
  • Mengubah kebijakan deteksi penghapusan sumber data
  • Mengubah pemetaan bidang pengindeks
  • Mengubah parameter pengindeks:
    • Mode Penguraian
    • Ekstensi Nama File yang Dikecualikan
    • Ekstensi Nama File yang Diindeks
    • Metadata penyimpanan indeks hanya untuk dokumen berukuran besar
    • Header teks yang dibatasi
    • Pembatas teks yang dibatasi
    • Akar Dokumen
    • Tindakan Gambar (Perubahan pada cara gambar diekstrak)

Perubahan yang memicu pemrosesan inkremental

Pemrosesan bertahap mengevaluasi definisi set keterampilan Anda dan menentukan keterampilan mana yang akan dieksekusi ulang. Ini secara selektif memperbarui bagian pohon dokumen yang terpengaruh. Berikut adalah daftar lengkap perubahan yang mengakibatkan pengayaan inkremental:

  • Mengubah jenis keterampilan (memperbarui tipe OData keterampilan tersebut)
  • Memperbarui parameter khusus keterampilan, seperti URL, default, atau parameter lainnya
  • Mengubah output keterampilan, seperti ketika keterampilan mengembalikan output tambahan atau berbeda
  • Mengubah masukan keterampilan yang menghasilkan asal-usul atau rangkaian keterampilan yang berbeda
  • Setiap invalidasi pada keterampilan upstream, jika Anda memperbarui keterampilan yang menyediakan input untuk keterampilan ini
  • Memperbarui lokasi proyeksi penyimpanan pengetahuan, yang menghasilkan proyeksi ulang dokumen
  • Mengubah proyeksi penyimpanan pengetahuan, yang menghasilkan proyeksi ulang dokumen
  • Mengubah pemetaan bidang output pada pengindeks, yang menghasilkan proyeksi ulang dokumen ke indeks

API yang digunakan untuk caching

API Pratinjau menyediakan properti tambahan pada pengindeks. Gunakan API pratinjau terbaru.

Gunakan versi yang tersedia umum untuk kumpulan keterampilan dan sumber data. Selain dokumentasi referensi, lihat Mengonfigurasi caching untuk pengayaan inkremental untuk detail mengenai urutan operasi.

  • Terakhir diperbarui pada