Aggiornare o ricompilare un indice in Azure AI Search

Articolo
10/16/2024

Questo articolo illustra come aggiornare un indice esistente in Azure AI Search con modifiche dello schema o modifiche al contenuto tramite l'indicizzazione incrementale. Vengono illustrate le circostanze in cui sono necessarie le ricompilazioni e vengono fornite raccomandazioni per attenuare gli effetti delle ricompilazioni sulle richieste di query in corso.

Durante lo sviluppo attivo, è comune eliminare e ricompilare gli indici quando si esegue l'iterazione sulla progettazione degli indici. La maggior parte degli sviluppatori lavora con un piccolo campione rappresentativo dei dati in modo da rendere più veloce la reindicizzazione.

Per le modifiche dello schema nelle applicazioni già in produzione, è consigliabile creare e testare un nuovo indice che viene eseguito affiancato a un indice esistente. Usare un alias di indice per scambiare il nuovo indice evitando di modificare il codice dell'applicazione.

Aggiornare il contenuto

L'indicizzazione incrementale e la sincronizzazione di un indice rispetto alle modifiche apportate ai dati di origine sono fondamentali per la maggior parte delle applicazioni di ricerca. In questa sezione viene illustrato il flusso di lavoro per l'aggiornamento del contenuto dei campi in un indice di ricerca.

Usare le stesse tecniche per il caricamento di documenti: Documenti - Indice (REST) o un'API equivalente negli SDK di Azure. Per altre informazioni sulle tecniche di indicizzazione, vedere Caricare documenti.

Impostare il parametro @search.action per determinare l'effetto sui documenti esistenti:

Azione	Effetto
eliminare	Rimuove l'intero documento dall'indice. Per rimuovere un singolo campo, usare invece Unisci, impostando il campo in questione su Null. I documenti e i campi eliminati non liberano immediatamente spazio nell'indice. Ogni pochi minuti, un processo in background esegue l'eliminazione fisica. Sia che si usi il portale o un'API per restituire le statistiche dell'indice, è possibile prevedere un piccolo ritardo prima che l'eliminazione venga riflessa nel portale e tramite le API.
merge	Aggiorna il documento già esistente e omette il documento che non può essere trovato. Unisci sostituisce i valori esistenti. Per questo motivo, assicurarsi di verificare la presenza di campi della raccolta che contengono più valori, ad esempio campi di tipo `Collection(Edm.String)`. Ad esempio, se un campo `tags` inizia con un valore di `["budget"]` e si esegue Unisci con `["economy", "pool"]`, il valore finale del campo `tags` sarà `["economy", "pool"]`. Non sarà `["budget", "economy", "pool"]`.
mergeOrUpload	Si comporta come Unisci se il documento esiste già e Carica se il documento è nuovo. Questa è l'azione più comune per gli aggiornamenti incrementali.
upload	Simile a un "upsert" in cui il documento viene inserito se nuovo e aggiornato o sostituito se esistente. Se il documento non contiene valori richiesti dall'indice, il valore del campo del documento viene impostato su Null.

Pubblicare l'aggiornamento.

Le query continuano a essere eseguite, ma se si aggiornano o si rimuovono campi esistenti, è possibile prevedere risultati misti e una maggiore incidenza della limitazione delle richieste.

Suggerimenti per l'indicizzazione incrementale

Gli indicizzatori automatizzano l'indicizzazione incrementale. Se è possibile usare un indicizzatore e se l'origine dati supporta il rilevamento delle modifiche, è possibile eseguire l'indicizzatore in una pianificazione ricorrente per aggiungere, aggiornare o sovrascrivere il contenuto ricercabile in modo che venga sincronizzato con i dati esterni.
Se si effettuano chiamate di indice direttamente tramite l'API push, usare mergeOrUpload come azione di ricerca.
Il payload deve includere le chiavi o gli identificatori di ogni documento da aggiungere, aggiornare o eliminare.
Se l'indice include campi vettoriali e si imposta la proprietà stored su false, assicurarsi di fornire il vettore nell'aggiornamento parziale del documento, anche se il valore è invariato. Un effetto collaterale dell'impostazione di stored su false è che i vettori vengono rilasciati in un'operazione di reindicizzazione. Se si specifica il vettore nel payload dei documenti, si impedisce che ciò accada.
Per aggiornare il contenuto di campi semplici e sottocampi in tipi complessi, elencare solo i campi da modificare. Ad esempio, se è necessario aggiornare solo un campo descrizione, il payload deve essere costituito dalla chiave del documento e dalla descrizione modificata. L'omissione di altri campi mantiene i relativi valori esistenti.
Per unire le modifiche inline nella raccolta di stringhe, specificare l'intero valore. Richiamare l'esempio di campo tags dalla sezione precedente. I nuovi valori sovrascrivono i valori precedenti per un intero campo e non esiste un'unione all'interno del contenuto di un campo.

Di seguito è riportato un esempio di API REST che illustra questi suggerimenti:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Modificare uno schema indice

Lo schema dell'indice definisce le strutture di dati fisiche create nel servizio di ricerca, in modo che non siano disponibili molte modifiche da apportare allo schema senza incorrere in una ricompilazione completa. Nell'elenco seguente vengono enumerate le modifiche dello schema che possono essere introdotte facilmente in un indice esistente. In genere, l'elenco include nuovi campi e funzionalità usati durante l'esecuzione della query.

Aggiungi un nuovo campo
Impostare l'attributo retrievable su un campo esistente
Aggiornare searchAnalyzer in un campo con un indexAnalyzeresistente
Aggiungere una nuova definizione dell'analizzatore in un indice (che può essere applicato ai nuovi campi)
Aggiungere, aggiornare o eliminare i profili di punteggio
Aggiungere, aggiornare o eliminare le impostazioni di CORS
Aggiungere, aggiornare o eliminare synonymMaps
Aggiungere, aggiornare o eliminare configurazioni semantiche

L'ordine delle operazioni è:

Ottenere la definizione dell'indice.
Rivedere lo schema con gli aggiornamenti dell'elenco precedente.
Aggiornare lo schema dell'indice nel servizio di ricerca.
Aggiornare il contenuto dell'indice in modo che corrisponda allo schema modificato se è stato aggiunto un nuovo campo. Per tutte le altre modifiche, il contenuto indicizzato esistente viene usato così come è.

Quando si aggiorna uno schema di indice per includere un nuovo campo, ai documenti esistenti nell'indice viene assegnato un valore Null per tale campo. Nel processo di indicizzazione successivo, i valori dei dati di origine esterni sostituiscono i valori Null aggiunti da Azure AI Search.

Non dovrebbero verificarsi interruzioni di query durante gli aggiornamenti, ma i risultati delle query varieranno man mano che gli aggiornamenti avranno effetto.

Rimuovere e ricompilare un indice

Alcune modifiche richiedono un'eliminazione e la ricompilazione dell'indice, sostituendo un indice corrente con uno nuovo.

Azione	Descrizione
Eliminare un campo	Per rimuovere fisicamente tutte le tracce di un campo è necessario ricompilare l'indice. Quando una ricompilazione immediata non è pratica, è possibile modificare il codice dell'applicazione per reindirizzare l'accesso da un campo obsoleto o usare searchFields e selezionare i parametri di query per scegliere quali campi vengono cercati e restituiti. Fisicamente la definizione del campo e i contenuti rimangono nell'indice fino alla successiva ricompilazione, quando si applica uno schema che omette il campo in questione.
Modificare la definizione di un campo	Le revisioni di un nome di campo, di un tipo di dati o di attributi di indice specifici (ricercabili, filtrabili, ordinabili, con facet) richiedono una ricompilazione completa.
Assegnare un analizzatore a un campo	Gli analizzatori vengono definiti in un indice, assegnati ai campi e quindi richiamati durante l'indicizzazione per informare su come vengono creati i token. È possibile aggiungere una nuova definizione di analizzatore a un indice in qualsiasi momento, ma è possibile assegnare un analizzatore solo quando il campo viene creato. Questo vale per entrambe le proprietà analyzer e indexAnalyzer. La proprietà searchAnalyzer è un'eccezione perché è possibile assegnare questa proprietà a un campo esistente.
Aggiornare o eliminare una definizione di analizzatore in un indice	Non è possibile eliminare o modificare una configurazione dell'analizzatore esistente (analizzatore, tokenizer, filtro token o filtro char) nell'indice a meno che non si ricompili l'intero indice.
Aggiungere un campo a uno strumento suggerimenti	Se esiste già un campo e si vuole aggiungerlo a un costrutto Componenti per il suggerimento e ricompilare l'indice.
Cambiare i livelli	Gli aggiornamenti sul posto non sono supportati. Se è necessaria una maggiore capacità, creare un nuovo servizio e ricompilare gli indici da zero. Per automatizzare questo processo, è possibile usare il codice di esempio index-backup-restore in questo repository di esempio .NET di Azure AI Search. Questa app esegue il backup dell'indice in una serie di file JSON e quindi ricrea l'indice in un servizio di ricerca specificato.

L'ordine delle operazioni è:

Ottenere una definizione di indice nel caso in cui sia necessaria per riferimento futuro o per usarla come base per una nuova versione.
Prendere in considerazione l'uso di una soluzione di backup e ripristino per mantenere una copia del contenuto dell'indice. Sono disponibili soluzioni in C# e in Python. È consigliabile usare la versione di Python perché è più aggiornata.

Se si ha la capacità nel servizio di ricerca, mantenere l'indice esistente durante la creazione e il test di quello nuovo.
Eliminare l'indice esistente. Le query destinate all'indice vengono eliminate immediatamente. Tenere presente che l'eliminazione di un indice è irreversibile, eliminando l'archiviazione fisica per la raccolta di campi e altri costrutti.
Pubblicare un indice modificato, in cui il corpo della richiesta include definizioni e configurazioni di campo cambiate o modificate.
Caricare l'indice con i documenti da un'origine esterna. I documenti vengono indicizzati usando le definizioni dei campi e le configurazioni del nuovo schema.

Quando si crea l'indice, l'archiviazione fisica viene allocata per ogni campo nello schema dell'indice, con un indice invertito creato per ogni campo ricercabile e un indice vettoriale creato per ogni campo vettoriale. I campi non ricercabili possono essere usati nei filtri o nelle espressioni, ma non hanno indici invertiti e non supportano la ricerca full-text o fuzzy. In una ricompilazione dell'indice, questi indici invertiti e gli indici vettoriali vengono eliminati e ricreati in base allo schema di indice specificato.

Bilanciamento dei carichi di lavoro

L'indicizzazione non viene eseguita in background, ma il servizio di ricerca bilancerà tutti i processi di indicizzazione con le query in corso. Durante l'indicizzazione, è possibile monitorare le richieste di query nel portale per assicurarsi che le query vengano completate in modo tempestivo.

Se l'indicizzazione dei carichi di lavoro introduce livelli inaccettabili di latenza delle query, eseguire analisi delle prestazioni ed esaminare questi suggerimenti sulle prestazioni per una potenziale mitigazione.

Verifica della presenza di aggiornamenti

È possibile iniziare a eseguire query su un indice subito dopo il caricamento del primo documento. Se si conosce l'ID di un documento, l'API REST di ricerca documenti restituisce il documento specifico. Per un test su più larga scala, è possibile aspettare che l'indice venga caricato completamente e quindi usare le query per verificare il contesto che ci si aspetta di vedere.

È possibile usare Esplora ricerche o un Client REST per verificare la disponibilità di contenuti aggiornati.

Se è stato aggiunto o rinominato un campo, usare $$select per restituire tale campo: search=*&$select=document-id,my-new-field,some-old-field&$count=true.

Il portale di Azure fornisce la dimensione dell'indice e la dimensione dell'indice vettoriale. È possibile controllare questi valori dopo l'aggiornamento di un indice, ma ricordarsi di aspettarsi un piccolo ritardo durante l'elaborazione della modifica e tenere conto delle frequenze di aggiornamento del portale, che possono essere di pochi minuti.

Eliminare documenti orfani

Azure AI Search supporta le operazioni a livello di documento in modo da poter cercare, aggiornare ed eliminare un documento specifico in isolamento. L'esempio seguente mostra come eliminare un documento.

L'eliminazione di un documento non libera immediatamente spazio nell'indice. Ogni pochi minuti, un processo in background esegue l'eliminazione fisica. Indipendentemente dal fatto che si usi il portale o un'API per restituire le statistiche sugli indici, è possibile prevedere un piccolo ritardo prima che l'eliminazione si rifletta nel portale e nelle metriche dell'API.

Identificare quale campo è la chiave del documento. Nel portale è possibile visualizzare i campi di ogni indice. Le chiavi del documento sono campi stringa e sono contrassegnate con un'icona a forma di chiave per renderle più facili da individuare.
Controllare i valori del campo chiave del documento: search=*&$select=HotelId. Una stringa semplice è lineare, ma se l'indice usa un campo con codifica base 64 o se i documenti di ricerca sono stati generati da un'impostazione di parsingMode, è possibile usare valori con cui non si ha familiarità.
Cerca il documento per verificare il valore dell'ID documento e per esaminarne il contenuto prima di eliminarlo. Specificare la chiave o l'ID documento nella richiesta. Negli esempi seguenti viene illustrata una stringa semplice per l'indice di esempio Hotel e una stringa con codifica base 64 per la chiave metadata_storage_path dell'indice cog-search-demo.
```
GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01
```
```
GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
```

Eliminare il documento usando un @search.action di eliminazione per rimuoverlo dall'indice di ricerca.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
Content-Type: application/json   
api-key: [admin key] 
{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "1111"  
    }  
  ]  
}

Condividi tramite