Abilitare la memorizzazione nella cache per l'arricchimento incrementale in Ricerca di intelligenza artificiale di Azure

Importante

Questa funzionalità è disponibile in anteprima pubblica in condizioni supplementari per l'utilizzo. L'API REST di anteprima supporta 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 dall'utente. 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.

Se non si ha 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.

Prerequisiti

Archiviazione di Azure viene usato per archiviare gli arricchimenti memorizzati nella cache. L'account di archiviazione deve essere per utilizzo generico v2.

Le API di anteprima o gli SDK beta di Azure sono necessari per abilitare la cache in un indicizzatore. Il portale attualmente non offre un'opzione per l'arricchimento nella cache.

Attenzione

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

Abilitare nei nuovi indicizzatori

Nei nuovi indicizzatori aggiungere la proprietà "cache" nel payload della definizione dell'indicizzatore quando si chiama Crea o Aggiorna indicizzatore (2021-04-30-Preview). È anche possibile usare la versione precedente dell'API di anteprima 2020-06-30-Preview.

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-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 GET Indexer per recuperare l'indicizzatore. Quando si usa la versione dell'API di anteprima per l'indicizzatore GET, 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=2021-04-30-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 un Archiviazione di Azure stringa di connessione.
• (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=2021-04-30-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 o un client API per questa attività.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Passaggio 4: Salvare l'indicizzatore

Aggiornare l'indicizzatore (2021-04-30-Preview) con una richiesta PUT, in cui il corpo della richiesta include "cache".

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-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 GET sull'indicizzatore, la risposta del servizio includerà una ID proprietà nell'oggetto cache. La stringa alfanumerica 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 verrà 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 o l'API. Nell'elenco indicizzatori del portale selezionare l'indicizzatore e fare clic su Esegui. Un vantaggio dell'uso del portale è che è possibile monitorare lo stato dell'indicizzatore, notare la 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=2020-06-30-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 sarà 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 tutti i contenuti OCR e 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.

• Arricchimento incrementale (ciclo di vita e gestione)
• Concetti e composizione del set di competenze
• Creare un set di competenze
• Esercitazione: Usare REST e intelligenza artificiale per generare contenuto ricercabile dai BLOB di Azure