Configurare una cache di arricchimento

Important

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 del set di competenze in modo da poter modificare i passaggi di arricchimento downstream senza una ricompilazione completa 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 determina quali parti dell'albero del documento devono essere aggiornate in base alle modifiche apportate al set di competenze o alla definizione dell'indicizzatore. L'output elaborato esistente viene mantenuto e riutilizzato laddove possibile.

Il contenuto memorizzato nella cache viene inserito in Archiviazione di Azure usando una stringa di connessione specificata. Questi oggetti vengono creati quando si esegue l'indicizzatore. Deve essere considerato un componente interno gestito dal servizio di ricerca e non deve essere modificato.

• Contenitore denominato ms-az-search-indexercache-<alpha-numeric-string>
• Tabelle chiamate MsAzSearchIndexerCacheIndex<alpha-numeric-string>

Prerequisites

• 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 di indicizzatori e set di competenze. Iniziare con la panoramica dell'indicizzatore e quindi passare ai set di competenze per informazioni sulle pipeline di arricchimento.

Limitations

Caution

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

Permissions

Un'identità di ricerca dell'intelligenza artificiale di Azure richiede l'accesso in scrittura all'archiviazione di Azure.

• Collaboratore ai dati di Storage Blob
• Contributore dati di Storage Table

La sintassi della stringa di connessione determina se viene usata un'identità assegnata dal sistema o assegnata dall'utente. Per ulteriori informazioni, vedere Connettere ad Azure Storage usando un'identità gestita.

Impostare la proprietà della cache

Utilizzare questa procedura sia per gli indicizzatori nuovi che per gli indicizzatori esistenti.

Nella definizione dell'indicizzatore impostare cache con:

• (Obbligatorio) storageConnectionString impostare su una stringa di connessione di Archiviazione di Azure.
• (Facoltativo) enableReprocessing (true per impostazione predefinita). Impostarlo su false per sospendere temporaneamente l'arricchimento incrementale e tornare a true in un secondo momento.

Portale di Azure

1. A sinistra selezionare Indicizzatori.

2. Selezionare Aggiungi indicizzatore per creare un nuovo indicizzatore o aprirne uno esistente in modalità di modifica JSON.

3. Abilitare l'arricchimento incrementale, impostare l'account di archiviazione della cache di arricchimento e salvare l'indicizzatore.

   

4. Reimpostare l'indicizzatore se esiste già.

5. Eseguire l'indicizzatore. Questa ricompilazione completa una tantum consente di eseguire il seeding della cache. Dopo il caricamento, il riutilizzo incrementale viene applicato alle esecuzioni successive.

REST

È consigliabile eseguire un indicizzatore GET se si sta modificando un indicizzatore esistente.

1. Usare l'API di anteprima più recente per creare o aggiornare l'indicizzatore.

   PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2025-11-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": []
       }
   

2. Reimpostare l'indicizzatore se esiste già.

3. Eseguire l'indicizzatore. Questa ricompilazione completa una tantum consente di eseguire il seeding della cache. Dopo il caricamento, il riutilizzo incrementale viene applicato alle esecuzioni successive.

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

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

Verificare la presenza di output memorizzati nella cache

1. Accedere al portale di Azure e trovare l'account di archiviazione di Azure.

2. Usare Storage Browser per esaminare contenitori e tabelle.

   • Il nome del contenitore è ms-az-search-indexercache-<some-alphanumeric-string>.

   • I nomi delle tabelle sono MsAzSearchIndexerCacheIndex<alpha-numeric-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 il conteggio 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 l'immagine elaborata in precedenza e il contenuto OCR dalla cache ed elaborare solo le modifiche correlate al testo dalle modifiche apportate. È possibile prevedere un minor numero di documenti nei conteggi di esecuzione dell'indicizzatore, tempi di esecuzione più brevi e costi inferiori.

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.

Passo successivo

L'arricchimento incrementale è applicabile agli indicizzatori che contengono set di competenze, fornendo contenuto riutilizzabile sia per gli indici che per gli archivi conoscenze. Il collegamento seguente fornisce altre informazioni sulla gestione della cache.

• Gestire una cache di arricchimento