Abilitare la memorizzazione nella cache per l'arricchimento incrementale in Azure AI Search

Articolo
12/10/2024

Importante

Questa funzionalità è disponibile in anteprima pubblica in Condizioni supplementari per l'utilizzo. Le API REST in anteprima supportano questa funzionalità.

Questo articolo illustra come aggiungere la memorizzazione nella cache a una pipeline di arricchimento in modo da poter modificare i passaggi di arricchimento downstream senza dover ricompilare ogni volta. Per impostazione predefinita, un set di competenze è senza stato e la modifica di qualsiasi parte della sua composizione richiede una riesecuzione completa dell'indicizzatore. Con una cache di arricchimento, l'indicizzatore può determinare quali parti dell'albero del documento devono essere aggiornate in base alle modifiche rilevate nelle definizioni del set di competenze o dell'indicizzatore. L'output elaborato esistente viene mantenuto e riutilizzato laddove possibile.

Il contenuto memorizzato nella cache viene inserito in Archiviazione di Azure usando le informazioni sull'account fornite. Il contenitore, denominato ms-az-search-indexercache-<alpha-numerc-string>, viene creato quando si esegue l'indicizzatore. Deve essere considerato un componente interno gestito dal servizio di ricerca e non deve essere modificato.

Prerequisiti

Archiviazione di Azure per l'archiviazione degli arricchimenti memorizzati nella cache. L'account di archiviazione deve essere per utilizzo generico v2.
Solo per l'indicizzazione BLOB, se è necessaria la rimozione sincronizzata dei documenti dalla cache e dall'indice quando i BLOB vengono eliminati dall'origine dati, abilitare un criterio di eliminazione nell'indicizzatore. Senza questo criterio, l'eliminazione di documenti dalla cache non è supportata.

È necessario avere familiarità con la configurazione degli indicizzatori. Iniziare con la panoramica dell'indicizzatore e quindi passare ai set di competenze per informazioni sulle pipeline di arricchimento. Per altre informazioni sui concetti chiave, vedere Arricchimento incrementale.

Attenzione

Se si usa l'indicizzatore SharePoint Online (anteprima), è consigliabile evitare l'arricchimento incrementale. In determinate circostanze, la cache diventa non valida, richiedendo una reimpostazione ed esecuzione dell'indicizzatore, se si sceglie di ricaricarla.

Abilitare nei nuovi indicizzatori

È possibile usare il portale di Azure, le API di anteprima o gli SDK beta di Azure per abilitare una cache di arricchimento in un indicizzatore.

Azure portal
REST

A sinistra selezionare Indicizzatori e quindi selezionare Aggiungi indicizzatore.
Specificare un nome dell'indicizzatore e un indice, un'origine dati e un set di competenze esistente.
Abilitare la memorizzazione nella cache incrementale e impostare l'account di archiviazione di Azure.

Nei nuovi indicizzatori, aggiungere la proprietà "cache" nel payload della definizione dell'indicizzatore quando si chiama Crea o Aggiorna indicizzatore.

È possibile usare le versioni dell'API 2021-04-30-anteprima e successive. È consigliabile usare l'anteprima più recente per Creare o Aggiornare l'indicizzatore (2024-05-01-anteprima).

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": []
    }

Abilitare sugli indicizzatori esistenti

Per gli indicizzatori esistenti che dispongono già di un set di competenze, seguire questa procedura per aggiungere la memorizzazione nella cache. Come operazione una tantum, reimpostare ed eseguire di nuovo l'indicizzatore completo per caricare la cache.

Passaggio 1: Ottenere la definizione dell'indicizzatore

Iniziare con un indicizzatore di lavoro valido con questi componenti: origine dati, set di competenze, indice. Usando un client API, inviare una richiesta OTTIENI indicizzatore per recuperare l'indicizzatore. Quando si usa la versione dell'API di anteprima per l'OTTIENI indicizzatore, alla definizione viene aggiunta automaticamente una proprietà "cache" impostata su null.

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]

Passaggio 2: Impostare la proprietà della cache

Nella definizione dell'indice modificare "cache" per includere le proprietà obbligatorie e facoltative seguenti:

(Obbligatorio) storageConnectionString deve essere impostato su una stringa di connessione di Archiviazione di Azure.
(Facoltativo) enableReprocessing Proprietà booleana (true per impostazione predefinita), indica che l'arricchimento incrementale è abilitato. Impostare su false se si vuole sospendere l'elaborazione incrementale mentre altre operazioni a elevato utilizzo di risorse, ad esempio l'indicizzazione di nuovi documenti, sono in corso e quindi tornare a true in un secondo momento.

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": []
    }

Passaggio 3: Reimpostare l'indicizzatore

La reimpostazione dell'indicizzatore è necessaria quando si configura l'arricchimento incrementale per gli indicizzatori esistenti per garantire che tutti i documenti siano in uno stato coerente. È possibile usare il portale di Azure o un client API per questa attività.

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]

Passaggio 4: Salvare l'indicizzatore

Aggiornare l'indicizzatore con una richiesta METTI, in cui il corpo della richiesta include "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
        }
    }

Se si esegue ora un'altra richiesta OTTIENI sull'indicizzatore, la risposta del servizio include una ID proprietà nell'oggetto cache. La stringa viene aggiunta al nome del contenitore contenente tutti i risultati memorizzati nella cache e lo stato intermedio di ogni documento elaborato da questo indicizzatore. L'ID viene usato per denominare in modo univoco la cache nell'archivio BLOB.

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

Passaggio 5: Eseguire l'indicizzatore

Per eseguire l'indicizzatore, è possibile usare il portale di Azure o l'API. Nell'portale di Azure selezionare l'indicizzatore dall'elenco degli indicizzatori e selezionare Esegui. Un vantaggio dell'uso del portale di Azure è che è possibile monitorare lo stato dell'indicizzatore, prendere nota della durata del processo e il numero di documenti elaborati. Le pagine del portale vengono aggiornate ogni pochi minuti.

In alternativa, è possibile usare REST per eseguire l'indicizzatore:

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]

Nota

Una reimpostazione e una nuova esecuzione dell'indicizzatore comporta una ricompilazione completa in modo che il contenuto possa essere memorizzato nella cache. Tutti gli arricchimenti cognitivi verranno rieseguiti in tutti i documenti. Il riutilizzo del contenuto arricchito dalla cache inizia dopo il caricamento della cache.

Verificare la presenza di output memorizzati nella cache

Trovare la cache in Archiviazione di Azure, in Contenitore BLOB. Il nome del contenitore è ms-az-search-indexercache-<some-alphanumeric-string>.

Una cache viene creata e usata da un indicizzatore. Il contenuto non è leggibile.

Per verificare se la cache è operativa, modificare un set di competenze ed eseguire l'indicizzatore, quindi confrontare le metriche prima e dopo per il tempo di esecuzione e i conteggi dei documenti.

I set di competenze che includono l'analisi delle immagini e il riconoscimento ottico dei caratteri (OCR) dei documenti analizzati rendono validi test case. Se si modifica una competenza di testo downstream o qualsiasi competenza non correlata all'immagine, l'indicizzatore può recuperare tutto il contenuto OCR e l'immagine elaborati in precedenza dalla cache, aggiornando ed elaborando solo le modifiche correlate al testo indicate dalle modifiche apportate. È possibile prevedere un minor numero di documenti nel conteggio dei documenti di esecuzione dell'indicizzatore, tempi di esecuzione più brevi e meno addebiti per la fattura.

Il set di file usato nelle esercitazioni cog-search-demo è un test case utile perché contiene 14 file di vari formati JPG, PNG, HTML, DOCX, PPTX e altri tipi. Passare en a es o a un'altra lingua nella competenza di traduzione testuale per il test di verifica dell'arricchimento incrementale.

Errori comuni

L'errore seguente si verifica se si dimentica di specificare una versione dell'API di anteprima nella richiesta:

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

Se manca un requisito dell'indicizzatore, si verificherà anche un errore 400 Richiesta non valida. Il messaggio di errore specifica eventuali dipendenze mancanti.

Passaggi successivi

L'arricchimento incrementale è applicabile agli indicizzatori che contengono set di competenze, fornendo contenuto riutilizzabile sia per gli indici che per gli archivi conoscenze. I collegamenti seguenti forniscono altre informazioni sulla memorizzazione nella cache e sui set di competenze.

Condividi tramite