Mengaktifkan penembolokan untuk pengayaan inkremental di Azure AI Search

Artikel
09/01/2024

Penting

Fitur ini berada di pratinjau publik dalam ketentuan penggunaan tambahan. PRATINJAU REST API mendukung fitur ini.

Artikel ini menjelaskan cara menambahkan penembolokan ke alur pengayaan sehingga Anda dapat memodifikasi langkah pengayaan hilir tanpa harus membangun kembali setiap saat. Secara default, set keterampilan tidak bernegara, dan mengubah bagian mana pun dari komposisinya membutuhkan tayangan ulang penuh dari pengindeks. Dengan cache pengayaan, pengindeks dapat menentukan bagian pohon dokumen mana yang harus di-refresh berdasarkan perubahan yang terdeteksi dalam definisi skillset atau pengindeks. Output yang diproses yang ada dipertahankan dan digunakan kembali sedapat mungkin.

Konten yang ditembolokan ditempatkan di Microsoft Azure Storage menggunakan informasi akun yang Anda sediakan. Kontainer, bernama ms-az-search-indexercache-<alpha-numerc-string>, dibuat saat Anda menjalankan pengindeks. Ini harus dianggap sebagai komponen internal yang dikelola oleh layanan pencarian Anda dan tidak boleh dimodifikasi.

Prasyarat

Azure Storage untuk menyimpan pengayaan cache. Akun penyimpanan harus berjenis general purpose 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. Mulailah dengan gambaran umum pengindeks lalu lanjutkan ke set keterampilan untuk mempelajari tentang alur pengayaan. Untuk latar belakang lebih lanjut tentang konsep utama, lihat pengayaan bertambah bertahap.

Perhatian

Jika Anda menggunakan pengindeks SharePoint Online (Pratinjau), Anda harus menghindari pengayaan inkremental. Dalam keadaan tertentu, cache menjadi tidak valid, mengharuskan pengindeks mengatur ulang dan menjalankan, jika Anda memilih untuk memuat ulang.

Mengaktifkan di pengindeks baru

Anda dapat menggunakan portal Azure, PRATINJAU API, atau SDK Azure beta diperlukan untuk mengaktifkan cache pengayaan pada pengindeks.

Portal Azure
REST

Di sebelah kiri, pilih Pengindeks, lalu pilih Tambahkan pengindeks.
Berikan nama pengindeks dan indeks, sumber data, dan set keterampilan yang ada.
Aktifkan penembolokan bertahap dan atur akun Azure Storage.

Pada pengindeks baru, tambahkan properti "cache" di payload definisi pengindeks saat memanggil Buat atau Perbarui Pengindeks.

Anda dapat menggunakan pratinjau API versi 2021-04-30-preview dan yang lebih baru. Kami merekomendasikan pratinjau terbaru untuk Buat atau Perbarui Pengindeks (pratinjau 2024-05-01).

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "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": []
    }

Mengaktifkan di pengindeks yang sudah ada

Untuk pengindeks yang sudah ada yang sudah memiliki set keterampilan, gunakan langkah berikut untuk menambahkan penembolokan. Sebagai operasi satu kali, atur ulang dan jalankan kembali pengindeks secara penuh untuk memuat cache.

Langkah 1: Dapatkan definisi pengindeks

Mulailah dengan pengindeks yang valid dan berfungsi yang memiliki komponen ini: sumber data, set keterampilan, indeks. Menggunakan klien API, kirim permintaan Pengindeks GET untuk mengambil pengindeks. Ketika Anda menggunakan versi API pratinjau ke GET pengindeks, properti "chace" yang diatur ke null ditambahkan ke definisi secara otomatis.

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

Langkah 2: Atur properti cache

Dalam definisi indeks, ubah "cache" untuk menyertakan properti berikut yang diperlukan dan opsional:

(Diperlukan) storageConnectionString harus diatur ke string koneksi Azure Storage.
(Opsional) Properti boolean enableReprocessing (truesecara default), menunjukkan bahwa pengayaan bertambah bertahap diaktifkan. Atur ke false jika Anda ingin menangguhkan pemrosesan bertambah bertahap sementara operasi intensif sumber daya lainnya, seperti mengindeks dokumen baru, sedang berlangsung dan kemudian membaliknya kembali ke true nanti.

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "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": []
    }

Langkah 3: Mereset pengindeks

Reset pengindeks diperlukan saat menyiapkan pengayaan bertambah bertahap untuk pengindeks yang ada guna memastikan semua dokumen dalam keadaan konsisten. Anda dapat menggunakan portal atau klien API untuk tugas ini.

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

Langkah 4: Simpan pengindeks

Perbarui Pengindeks dengan permintaan PUT, di mana isi permintaan menyertakan "cache".

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

Jika Anda sekarang mengeluarkan permintaan GET lain pada pengindeks, respons dari layanan menyertakan ID properti di objek cache. Untai (karakter) alfanumerik ditambahkan ke nama kontainer yang berisi semua hasil ditembolokan 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"
    }

Langkah 5: Jalankan pengindeks

Untuk menjalankan pengindeks, Anda dapat menggunakan portal atau API. Di portal, dari daftar pengindeks, pilih pengindeks dan pilih Jalankan. Salah satu keuntungan menggunakan portal adalah Anda dapat memantau status pengindeks, mencatat durasi pekerjaan, dan berapa banyak dokumen yang diproses. Halaman portal di-refresh setiap beberapa menit.

Atau, Anda dapat menggunakan REST untuk menjalankan pengindeks:

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

Catatan

Reset dan tayangan ulang pengindeks menghasilkan pembangunan ulang penuh sehingga konten dapat di-tembolokan. Semua pengayaan kognitif akan diulang pada semua dokumen. Menggunakan kembali konten yang diperkaya dari cache dimulai setelah cache dimuat.

Memeriksa output yang di-chace

Temukan cache di Azure Storage, di bagian kontainer Blob. Nama kontainer adalah ms-az-search-indexercache-<some-alphanumeric-string>.

Cache dibuat dan digunakan oleh pengindeks. Kontennya tidak dapat dibaca manusia.

Untuk memverifikasi apakah cache beroperasi, memodifikasi set keterampilan dan menjalankan pengindeks, kemudian membandingkan metrik sebelum dan sesudah untuk waktu eksekusi dan jumlah dokumen.

Set keterampilan yang mencakup analisis gambar dan Pengenalan Karakter Optik (OCR) dari dokumen yang dipindai membuat kasus uji yang baik. Jika Anda memodifikasi keterampilan teks hilir atau keterampilan apa pun yang tidak terkait dengan gambar, pengindeks dapat mengambil semua konten gambar dan OCR yang diproses sebelumnya dari cache, memperbarui dan memproses hanya perubahan terkait teks yang ditunjukkan oleh pengeditan Anda. Anda dapat mengharapkan untuk melihat lebih sedikit dokumen dalam jumlah dokumen yang dieksekusi pengindeks, waktu eksekusi yang lebih singkat, dan lebih sedikit biaya pada tagihan Anda.

Set file yang digunakan dalam tutorial cog-search-demo adalah kasus uji 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 bertambah bertahap.

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

Kesalahan 400 Permintaan Buruk juga akan terjadi jika Anda kehilangan persyaratan pengindeks. Pesan kesalahan menentukan dependensi yang hilang.

Langkah berikutnya

Pengayaan bertambah bertahap berlaku pada pengindeks yang mengandung set keterampilan, menyediakan konten yang dapat digunakan kembali untuk indeks dan penyimpanan pengetahuan. Tautan berikut memberikan informasi lebih lanjut tentang penembolokan dan set keterampilan.

Bagikan melalui