Gestire una cache di arricchimento (anteprima)

Note

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

Importante

Le funzionalità, le funzionalità o le proprietà contrassegnate (anteprima) non sono coperte da un contratto di servizio, non sono consigliate per i carichi di lavoro di produzione e potrebbero cambiare o essere vincolate prima che diventino disponibili a livello generale. Le condizioni di anteprima Azure AI Search si applicano a tutte le funzionalità di anteprima, indipendente o parte di una funzionalità disponibile a livello generale.

Una cache di arricchimento (anteprima) è una funzionalità facoltativa che archivia il contenuto arricchito creato durante l'esecuzione del set di competenze. Mantiene il contenuto tra le esecuzioni in modo che solo le competenze e i documenti modificati richiedano la rielaborazione. Non è un backup degli output del set di competenze, dello stato dell'indicizzatore o dei documenti indicizzati.

La cache di arricchimento viene creata in Archiviazione di Azure. La cache contiene l'output del cracking di documenti, oltre agli output di ogni competenza per ogni documento. Anche se la memorizzazione nella cache è fatturabile (usa Archiviazione di Azure), il costo complessivo dell'arricchimento viene ridotto perché i costi di archiviazione sono inferiori all'estrazione delle immagini e all'elaborazione di intelligenza artificiale.

Se si configura una cache di arricchimento, questo articolo illustra come gestire gli aggiornamenti delle competenze e dell'origine dati in modo da ottenere la massima utilità dagli arricchimenti memorizzati nella cache.

Prerequisiti

Limitazioni

Attenzione

Se si usa l'indicizzatore SharePoint (anteprima), evitare l'arricchimento incrementale. In determinate circostanze, la cache diventa non valida. Per ricaricarlo, eseguire una reimpostazione dell'indicizzatore e la ricompilazione completa.

Le origini dati di grandi dimensioni presentano una limitazione aggiuntiva della cache.

Attenzione

Per le origini dati di grandi dimensioni, una cache di arricchimento può aumentare la rielaborazione complessiva quando si verificano skill a esecuzione prolungata, interruzioni ripetute o errori frequenti delle skill. L'indicizzatore privilegia la correttezza rispetto alla minimizzazione della rielaborazione, quindi un accumulo nella cache dovuto a interruzioni ripetute incrementa i ritentativi.

Per eseguire il ripristino da un backlog della cache in crescita, partizionare l'origine dati in contenitori o cartelle virtuali più piccole. Quindi utilizzare indicizzatori paralleli che puntano allo stesso indice. Per annullare l'associazione della cache, impostare la cache proprietà su null nell'indicizzatore.

Configurazione della cache

Fisicamente, la cache viene archiviata in un contenitore BLOB e in tabelle nell'account Archiviazione di Azure, una per indicizzatore. A ogni indicizzatore viene assegnato un identificatore di cache univoco e non modificabile che corrisponde al contenitore in uso.

La cache viene creata quando si specifica la cache proprietà ed è possibile eseguire l'indicizzatore. È possibile memorizzare nella cache solo il contenuto arricchito. Se l'indicizzatore non ha un set di competenze collegato, la memorizzazione nella cache non si applica.

Nell'esempio seguente viene illustrato un indicizzatore con memorizzazione nella cache abilitata. Per istruzioni dettagliate, vedere Configurare la memorizzazione nella cache degli arricchimenti.

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-08-01-preview
    {
        "name": "myIndexerName",
        "targetIndexName": "myIndex",
        "dataSourceName": "myDatasource",
        "skillsetName": "mySkillset",
        "cache" : {
            "storageConnectionString" : "<Your storage account connection string>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Gestione della cache

L'indicizzatore gestisce il ciclo di vita della cache. Se si elimina un indicizzatore, si elimina anche la cache. Se si imposta la proprietà dellcache'indicizzatore su null o si modifica il stringa di connessione, la cache esistente viene eliminata durante l'esecuzione successiva dell'indicizzatore.

Sebbene l'arricchimento incrementale sia progettato per rilevare e rispondere alle modifiche senza alcun intervento da parte dell'utente, è possibile impostare parametri per richiamare comportamenti specifici:

Assegnare priorità ai nuovi documenti

La cache proprietà include un enableReprocessing parametro che controlla se il contenuto memorizzato nella cache viene rielaborato. Se è impostato su true (impostazione predefinita), l'indicizzatore rielabora i documenti memorizzati nella cache quando viene eseguito di nuovo, se sono interessati da un aggiornamento della skill.

Se false, l'indicizzatore non rielabora i documenti esistenti, che assegna priorità al nuovo contenuto. Impostare enableReprocessing su false solo temporaneamente. Mantenendolo vero la maggior parte del tempo, garantisce che sia i documenti nuovi che esistenti rimangano validi per la definizione corrente del set di competenze.

Ignorare la valutazione del set di competenze

La modifica di una competenza in genere va a portata di mano con la rielaborazione di tale competenza. Tuttavia, alcune modifiche apportate a una competenza non dovrebbero attivare la rielaborazione. Ad esempio, la distribuzione di una competenza personalizzata in una nuova posizione o con una nuova chiave di accesso. Queste modifiche sono in genere di carattere periferico e non influiscono sulla sostanza dell'output della competenza.

Se si sa che una modifica alla competenza è superficiale, eseguire l'override della valutazione delle competenze impostando il disableCacheReprocessingChangeDetection parametro su true:

  1. Chiamare Update Skillset e modificare la definizione del set di competenze.
  2. Aggiungere il disableCacheReprocessingChangeDetection=true parametro nella richiesta.
  3. Inviare la modifica.

Quando si imposta questo parametro, vengono confermati solo gli aggiornamenti alla definizione del set di competenze. La modifica non viene valutata per gli effetti sulla cache esistente. Usa una versione di anteprima dell'API, "2020-06-30-Preview" o successiva. Usare l'API di anteprima più recente.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2026-08-01-preview&disableCacheReprocessingChangeDetection

Ignorare i controlli di convalida dell'origine dati

La maggior parte delle modifiche apportate a una definizione di origine dati invalida la cache. Tuttavia, per gli scenari in cui si sa che una modifica non deve invalidare la cache, ad esempio la modifica di un stringa di connessione o la rotazione della chiave nell'account di archiviazione, aggiungere il parametro ignoreResetRequirement nell'aggiornamento dell'origine data. Impostare questo parametro su true per consentire l'esecuzione del commit, senza attivare una condizione di reimpostazione che comporterebbe la ricompilazione e il popolamento di tutti gli oggetti da zero.

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-08-01-preview&ignoreResetRequirement

Forzare la valutazione del set di competenze

Lo scopo della cache è evitare l'elaborazione non necessaria. Si supponga tuttavia di apportare una modifica a una competenza che l'indicizzatore non rileva (ad esempio, la modifica di un elemento nel codice esterno, ad esempio una competenza personalizzata).

In questo caso, usare l'API Reimposta competenze per forzare la rielaborazione di una determinata competenza, incluse le competenze downstream che hanno una dipendenza dall'output di tale competenza. Questa API accetta una richiesta POST con un elenco di competenze che devono essere invalidate e contrassegnate per la rielaborazione. Dopo la reimpostazione delle abilità, procedere con una richiesta Esegui indicizzatore per richiamare l'elaborazione della pipeline.

Ri-memorizzare nella cache documenti specifici

Se si reimposta un indicizzatore, tutti i documenti nel corpus di ricerca vengono rielaborati.

Negli scenari in cui è necessario rielaborare solo alcuni documenti, usare Reimposta documenti (anteprima) per forzare la rielaborazione di documenti specifici. Quando si reimposta un documento, l'indicizzatore invalida la cache per il documento. L'indicizzatore quindi rielabora il documento leggendolo dall'origine dati. Per altre informazioni, vedere Eseguire o reimpostare indicizzatori, competenze e documenti.

Per reimpostare documenti specifici, includere nella richiesta un elenco di chiavi dei documenti come riportate nell'indice di ricerca. Se la chiave corrisponde a un campo nell'origine dati esterna, utilizzare il valore dell'indice di ricerca.

A seconda della modalità di chiamata dell'API, la richiesta aggiunge, sovrascrive o accoda l'elenco di chiavi:

  • La chiamata all'API più volte con chiavi diverse aggiunge le nuove chiavi all'elenco di chiavi del documento da reimpostare.

  • Chiamare l'API con il parametro di stringa di query overwrite impostato su true si sovrascrive l'elenco corrente delle chiavi del documento da reimpostare con il payload della richiesta.

  • La chiamata all'API aggiunge le chiavi del documento alla coda di lavoro eseguita dall'indicizzatore. La prossima volta che l'indicizzatore viene eseguito, secondo la pianificazione o su richiesta, assegna la priorità all'elaborazione delle chiavi di documento reimpostate prima di qualsiasi altra modifica proveniente dall'origine dati.

L'esempio seguente illustra una richiesta di reimpostazione del documento:

POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2026-08-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

Modifiche che invalidano la cache

Quando si abilita una cache, l'indicizzatore verifica la presenza di modifiche nella composizione della pipeline per decidere quale contenuto può riutilizzare e quale contenuto deve essere rielaborato. Questa sezione elenca le modifiche che invalidano la cache, seguite dalle modifiche che attivano l'elaborazione incrementale.

Una modifica invalidante è una delle posizioni in cui l'intera cache non è valida. Ad esempio, l'aggiornamento dell'origine dati è una modifica invalidante. Ecco l'elenco completo delle modifiche apportate a qualsiasi parte della pipeline dell'indicizzatore che invalida la cache:

  • Modifica del tipo di origine dati
  • Modifica del contenitore dell'origine dati
  • Modifica delle credenziali dell'origine dati
  • Modifica dei criteri di rilevamento delle modifiche dell'origine dati
  • Modifica dei criteri di rilevamento dell'eliminazione dell'origine dati
  • Modifica dei mapping dei campi dell'indicizzatore
  • Modifica dei parametri dell'indicizzatore:
    • Modalità di analisi
    • Estensioni escluse
    • Estensioni di file indicizzate
    • Indicizzare i metadati di archiviazione solo per documenti sovradimensionati
    • Intestazioni di testo delimitate
    • Delimitatore di testo delimitato
    • Radice documento
    • Azione immagine (modifiche alla modalità di estrazione delle immagini)

Modifiche che attivano l'elaborazione incrementale

L'elaborazione incrementale valuta la definizione del set di competenze e determina le competenze da rieseguire. Aggiorna in modo selettivo le parti interessate dell'albero del documento. Ecco l'elenco completo delle modifiche che comportano l'arricchimento incrementale:

  • Modifica del tipo di competenza (aggiornamento del tipo OData della competenza)
  • Aggiornamento di parametri specifici della competenza, ad esempio un URL, impostazioni predefinite o altri parametri
  • Modifica degli output delle competenze, ad esempio quando la competenza restituisce output aggiuntivi o diversi
  • Modifica degli input delle competenze che comportano un diverso concatenamento di ereditarietà o competenze
  • Invalidamento di qualsiasi competenza a monte, se si aggiorna una competenza che fornisce un input a questa competenza
  • Aggiornare la posizione di proiezione dell'archivio di conoscenza, operazione che comporta una nuova proiezione dei documenti
  • Modifica delle proiezioni dell'archivio conoscenze, che comporta la rielaborazione dei documenti
  • Modifica delle mappature dei campi di output in un indicizzatore, che comporta la riproiezione dei documenti nell'indice

API usate per la memorizzazione nella cache

Le API di anteprima forniscono proprietà aggiuntive sugli indicizzatori. Usare l'API di anteprima più recente.

Usare la versione generalmente disponibile per i set di competenze e le fonti di dati. Oltre alla documentazione di riferimento, vedere Configurare la memorizzazione nella cache per l'arricchimento incrementale per informazioni dettagliate sull'ordine delle operazioni.

  • Ultimo aggiornamento: