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

Artikel ini menjelaskan cara menambahkan caching ke alur kerja skillset sehingga Anda dapat memodifikasi langkah-langkah pengayaan hilir tanpa harus membangun ulang secara keseluruhan setiap kali. Cache pengayaan (pratinjau) memerlukan REST API pratinjau. Secara default, set keterampilan bersifat stateless, dan mengubah bagian mana pun dari komposisinya memerlukan pengindeksan ulang secara penuh. Dengan cache pengayaan, pengindeks menentukan bagian mana dari pohon dokumen yang harus di-refresh berdasarkan skillset atau perubahan definisi pengindeks. Pengindeks mempertahankan dan menggunakan kembali output yang diproses yang ada jika memungkinkan.

Anda menempatkan konten cache di Azure Storage dengan menggunakan string koneksi yang Anda sediakan. Pengindeks membuat objek ini saat dijalankan. Pertimbangkan cache pengayaan komponen internal yang dikelola oleh layanan pencarian yang tidak boleh Anda ubah.

Penting

Cache pengayaan bukan cadangan output skillset, status pengindeks, atau dokumen terindeks. Ini tidak melacak pemrosesan dokumen mana yang selesai. Untuk sumber data berukuran besar, tinjau bagian Batasan sebelum mengaktifkan cache.

Kontainer bernama ms-az-search-indexercache-<alpha-numeric-string>
Tabel-tabel yang bernama MsAzSearchIndexerCacheIndex<alpha-numeric-string>

Prasyarat

Azure Storage untuk menyimpan pengayaan cache. Akun penyimpanan harus serba guna v2.
Untuk pengindeksan blob saja, jika Anda memerlukan penghapusan dokumen yang disinkronkan dari cache dan indeks saat blob dihapus dari sumber data Anda, aktifkan kebijakan penghapusan di pengindeks. Tanpa kebijakan ini, penghapusan dokumen dari cache tidak didukung.

Anda harus terbiasa dengan menyiapkan pengindeks dan kumpulan skill. Mulailah dengan gambaran umum pengindeks lalu lanjutkan ke set keterampilan untuk mempelajari tentang alur pengayaan.

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. Perilaku ini diharapkan, bukan bug.

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. Lihat Mengindeks himpunan data besar untuk panduan tentang pola partisi.

Perizinan

Identitas Pencarian Azure AI memerlukan akses tulis ke Azure Storage:

Kontributor Penyimpanan Data Blob
Kontributor Data pada Tabel Penyimpanan

Sintaks string koneksi menentukan apakah identitas yang ditetapkan sistem atau ditetapkan pengguna digunakan. Untuk informasi selengkapnya, lihat Hubungkan ke Azure Storage menggunakan identitas terkelola.

Mengatur properti cache

Gunakan prosedur ini untuk pengindeks baru dan yang sudah ada.

Dalam definisi pengindeks, atur cache dengan:

(Wajib) storageConnectionString diatur ke string koneksi Azure Storage.
(Opsional) enableReprocessing (true secara default). Atur ke false untuk menangguhkan pengayaan bertahap untuk sementara waktu, dan alihkan kembali ke true nanti.

portal Azure
SISANYA

Di sebelah kiri, pilih Pengindeks.
Pilih Tambahkan pengindeks untuk membuat pengindeks baru, atau buka pengindeks yang sudah ada dalam mode edit JSON.
Aktifkan pengayaan bertahap, atur akun penyimpanan cache pengayaan, dan simpan pengindeks.
Reset pengindeks jika sudah ada.
Jalankan pengindeks. Proses pembangunan ulang penuh sekali ini menginisialisasi cache. Setelah dimuat, penggunaan kembali bertahap berlaku pada eksekusi berikutnya.

Jika Anda mengedit pengindeks yang sudah ada, gunakan GET Indexer untuk mendapatkan konfigurasi saat ini.

Gunakan API pratinjau terbaru untuk Membuat atau Memperbarui Pengindeks.

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2026-08-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings": [],
        "outputFieldMappings": [],
        "parameters": []
    }

Reset pengindeks jika sudah ada.

Jalankan pengindeks. Proses pembangunan ulang penuh sekali ini menginisialisasi cache. Setelah dimuat, penggunaan kembali bertahap berlaku pada eksekusi berikutnya.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2026-08-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Jika Anda sekarang mengirim permintaan GET lain pada pengindeks, respons dari layanan menyertakan sebuah ID properti dalam objek cache. String ditambahkan ke nama kontainer yang berisi semua hasil cache dan status menengah dari setiap dokumen yang diproses oleh pengindeks ini. ID digunakan untuk memberi nama cache secara unik di penyimpanan Blob.

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

Periksa output yang di-cache

Masuk ke portal Azure dan temukan akun Azure Storage Anda.
Gunakan Browser Penyimpanan untuk meninjau kontainer dan tabel.
- Nama kontainer adalah ms-az-search-indexercache-<some-alphanumeric-string>.
- Nama tabel adalah MsAzSearchIndexerCacheIndex<alpha-numeric-string>.

Pengindeks membuat dan menggunakan cache. Kontennya tidak dapat dibaca manusia.

Untuk memverifikasi apakah cache beroperasi, ubah set keterampilan dan jalankan pengindeks, lalu bandingkan metrik sebelum dan sesudah untuk waktu eksekusi dan jumlah dokumen.

Keterampilan yang mencakup analisis gambar dan Optical Character Recognition (OCR) dari dokumen yang dipindai merupakan kasus uji yang baik. Jika Anda memodifikasi keterampilan teks hilir atau keterampilan apa pun yang tidak terkait dengan gambar, pengindeks dapat mengambil konten gambar dan OCR yang diproses sebelumnya dari cache, dan hanya memproses perubahan terkait teks dari pengeditan Anda. Anda dapat mengharapkan lebih sedikit dokumen dalam jumlah eksekusi pengindeks, waktu eksekusi yang lebih pendek, dan biaya yang lebih rendah.

Set file yang digunakan dalam tutorial cog-search-demo adalah kasus pengujian yang berguna karena berisi 14 file dari berbagai format JPG, PNG, HTML, DOCX, PPTX, dan jenis lainnya. Ubah en ke es atau bahasa lain dalam keterampilan terjemahan teks untuk pengujian bukti konsep pengayaan inkremental.

Kesalahan umum

Kesalahan berikut terjadi jika Anda lupa menentukan versi API pratinjau pada permintaan:

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

Error 400 Bad Request juga dapat terjadi jika Anda tidak memenuhi persyaratan pengindeks. Pesan kesalahan menentukan secara spesifik dependensi yang hilang.

Langkah berikutnya

Anda dapat menggunakan pengayaan inkremental pada pengindeks yang berisi set keterampilan, sehingga Anda dapat menggunakan kembali konten untuk indeks dan penyimpanan pengetahuan. Untuk mempelajari selengkapnya tentang manajemen cache, lihat artikel berikut ini:

Mengelola cache pengayaan

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-17