Caricare dati in un indice di ricerca in Azure AI

Questo articolo illustra come importare documenti in un indice di ricerca predefinito usando le API REST, gli SDK di Azure o il portale di Azure.

Prerequisiti

• Un servizio di Ricerca intelligenza artificiale di Azure (qualsiasi livello). Creare un servizio o trovarne uno esistente.

• Indice di ricerca esistente. Questo articolo presuppone che sia già stato creato un indice. Se è necessario creare e caricare in un unico passaggio, usare l'importazione guidata o un indicizzatore.

• Autorizzazioni per caricare i documenti:

  • Autenticazione basata su chiave: chiave API amministratore per il servizio di ricerca.
  • Autenticazione basata su ruoli: ruolo Collaboratore dati dell'indice di ricerca nel servizio di ricerca.

• Per lo sviluppo di SDK, installare la libreria client di Ricerca di Azure:

  • .NET: Azure.Search.Documents
  • Python: azure-search-documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Usare il portale di Azure

Nel portale di Azure usare l'importazione guidata per creare e caricare indici in un flusso di lavoro facile. Se si vuole caricare un indice esistente, scegliere un approccio alternativo.

1. Passare al servizio di ricerca nel portale di Azure.

2. Nella pagina Panoramica selezionare Importa dati sulla barra dei comandi per creare e popolare un indice di ricerca.

   

   Per esaminare il flusso di lavoro, seguire questi link: Guida introduttiva: creare un indice di Azure AI Search e Avvio rapido: vettorializzazione integrata.

3. Al termine della procedura guidata, usare Esplora ricerche per verificare la presenza di risultati.

Usare le API REST

Documenti - Indice è l'API REST per l'importazione di dati in un indice di ricerca.

Il corpo della richiesta contiene uno o più documenti da indicizzare. I documenti vengono identificati in modo univoco tramite una chiave con distinzione tra maiuscole e minuscole. Ogni documento è associato a un'azione: "upload", "delete", "merge" o "mergeOrUpload". Le richieste di caricamento devono includere i dati del documento come set di coppie chiave/valore.

Le API REST sono utili per test iniziali di prototipo, in cui è possibile testare flussi di lavoro di indicizzazione senza dover scrivere molto codice. Il parametro @search.action determina se i documenti vengono aggiunti completamente o parzialmente, in termini di valori nuovi o sostitutivi per campi specifici.

Guida introduttiva: La ricerca full-text con REST illustra i passaggi. L'esempio seguente è una versione modificata dell'esempio. Il valore viene tagliato per brevità e il primo valore HotelId viene modificato per evitare di sovrascrivere un documento esistente.

1. Formulare una chiamata POST che specifica il nome dell'indice, l'endpoint "docs/index" e un corpo della richiesta che include il parametro @search.action.

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2025-09-01
   Content-Type: application/json   
   api-key: [admin key] 
   {
       "value": [
       {
       "@search.action": "upload",
       "HotelId": "1111",
       "HotelName": "Stay-Kay City Hotel",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
       "Category": "Boutique",
       "Tags": [ "pool", "air conditioning", "concierge" ]
       },
       {
       "@search.action": "mergeOrUpload",
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
       "Category": "Boutique",
       "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
       }
     ]
   }
   

2. Impostare il parametro @search.action su upload per creare o sovrascrivere un documento. Impostarlo su merge o uploadOrMerge se si desidera destinare gli aggiornamenti a campi specifici all'interno del documento. L'esempio precedente mostra entrambe le azioni.

   Azione	Effetto
   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.
   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 è ["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.
   delete	Elimina rimuove il documento specificato dall'indice. Qualsiasi campo specificato in un'operazione di eliminazione, diverso dal campo chiave, viene ignorato. Se si vuole rimuovere un singolo campo da un documento, usare invece merge e impostare il campo su Null in modo esplicito. Per altre informazioni, vedere Eliminare documenti in un indice di ricerca.

   Non vi è alcuna garanzia di ordinamento circa quale azione nel corpo della richiesta venga eseguita per prima. Non è consigliabile avere più azioni di "unione" associate allo stesso documento in un singolo corpo della richiesta. Se sono necessarie più azioni di "unione" per lo stesso documento, eseguire l'unione lato client prima di aggiornare il documento nell'indice di ricerca.

   Nelle raccolte primitive, se il documento contiene un campo Tag di tipo Collection(Edm.String) con valore ["budget"], e si esegue un merge con un valore ["economy", "pool"] per Tag, il valore finale del campo Tags sarà ["economy", "pool"]. Non è ["budget", "economy", "pool"].

   Nelle raccolte complesse, se il documento contiene un campo di raccolta complesso denominato Rooms con valore [{ "Type": "Budget Room", "BaseRate": 75.0 }], e si esegue un merge con il valore [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], il valore finale del campo Rooms sarà [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Non sarà uno dei seguenti:

   • [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (aggiungi elementi)

   • [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (unire gli elementi in ordine, quindi aggiungere eventuali elementi aggiuntivi)

   Annotazioni

   Quando si caricano valori DateTimeOffset con informazioni sul fuso orario nell'indice, Ricerca di intelligenza artificiale di Azure normalizza questi valori in formato UTC. Ad esempio, 2025-01-13T14:03:00-08:00 verrà archiviato come 2025-01-13T22:03:00Z. Se è necessario archiviare le informazioni sul fuso orario, aggiungere una colonna aggiuntiva all'indice.

3. Inviare la richiesta.

   Nella tabella seguente vengono illustrati i vari codici di stato per documento che possono essere restituiti nella risposta. Alcuni codici di stato indicano problemi con la richiesta stessa, mentre altri indicano condizioni di errore temporanee. Per queste ultime è necessario riprovare dopo un breve intervallo di tempo.

   Codice di stato	Meaning	Non irreversibile	Note
   200	Il documento è stato modificato o eliminato correttamente.	non disponibile	Le operazioni di eliminazione sono idempotenti. Ovvero, anche se non esiste una chiave del documento nell'indice, il tentativo di un'operazione di eliminazione con tale chiave genera un codice di stato 200.
   201	Il documento è stato creato correttamente.	non disponibile
   400	Si è verificato un errore nel documento che ne ha impedito l'indicizzazione.	NO	Il messaggio di errore nella risposta indica l'errore del documento.
   404	Impossibile unire il documento perché la chiave specificata non esiste nell'indice.	NO	Questo errore non si verifica per i caricamenti perché creano nuovi documenti e non si verifica per le eliminazioni perché sono idempotent.
   409	È stato rilevato un conflitto di versione nel tentativo di indicizzare un documento.	Yes	Ciò può verificarsi quando si prova a indicizzare lo stesso documento più di una volta contemporaneamente.
   422	L'indice è temporaneamente non disponibile perché è stato aggiornato con il flag 'allowIndexDowntime' impostato su 'true'.	Yes
   429	Indica che è stata superata la quota per il numero di documenti per indice.	NO	È necessario creare un nuovo indice o aggiornare per limiti di capacità superiori.
   503	Il servizio di ricerca è temporaneamente non disponibile, probabilmente a causa di un sovraccarico.	Yes	In questo caso, il codice deve attendere prima di riprovare o si rischia di prolungare la non disponibilità del servizio.

   Annotazioni

   Se il codice del client riceve spesso una risposta 207, potrebbe ad esempio dipendere da un carico eccessivo del sistema. È possibile confermarlo controllando la statusCode proprietà per 503. In questo caso, è consigliabile limitare le richieste di indicizzazione. Se non si riduce il traffico di indicizzazione, è possibile che il sistema inizi a rifiutare tutte le richieste con errori 503.

4. Cercare i documenti appena aggiunti come fase di convalida:

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2025-09-01
   

Reference:Documents - Index, Documents - Get

Una richiesta di indice riuscita restituisce HTTP 200 (OK) per un batch in cui tutti i documenti hanno avuto esito positivo o HTTP 207 (multi-stato) se alcuni documenti non sono riusciti. Il corpo della risposta contiene lo stato per ogni documento:

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

Quando la chiave o l'ID del documento è nuova, null diventa il valore per qualsiasi campo non specificato nel documento. Per azioni su un documento esistente, i valori precedenti vengono sostituiti con valori aggiornati. Tutti i campi non specificati in un "merge" o "mergeUpload" rimangono intatti nell'indice di ricerca.

Usare gli Azure SDK

La programmabilità è disponibile negli SDK di Azure seguenti.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Verificare il caricamento dei dati

Dopo il caricamento dei documenti, verificare che i dati siano indicizzati correttamente.

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2025-09-01
api-key: [admin-key]

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

Funzionamento dell'importazione dei dati

Un servizio di ricerca accetta documenti JSON conformi allo schema dell'indice. Un servizio di ricerca può importare e indicizzare contenuto di testo normale e contenuto vettoriale nei documenti JSON.

• Il contenuto di testo normale viene recuperato dai campi nell'origine dati esterna, dalle proprietà dei metadati o dal contenuto arricchito generato da un set di competenze. Le competenze possono estrarre o dedurre descrizioni testuali da immagini e contenuti non strutturati.

• Il contenuto vettoriale viene recuperato da un'origine dati che lo fornisce oppure viene creato da un set di competenze che implementa la vettorializzazione integrata in un carico di lavoro dell'indicizzatore della ricerca di intelligenza artificiale di Azure.

È possibile preparare manualmente questi documenti, ma se il contenuto si trova in un'origine dati supportata, l'esecuzione di un indicizzatore o l'uso dell'importazione guidata può automatizzare il recupero dei documenti, la serializzazione JSON e l'indicizzazione.

Una volta che l'indicizzazione dei dati è stata completata, le strutture dei dati fisici dell'indice vengono bloccate. Per materiale sussidiario che illustra cosa può e non può essere modificato, vedere Aggiornare e ricompilare un indice.

L'indicizzazione non è un processo in background. Un servizio di ricerca bilancia l'indicizzazione e i carichi di lavoro delle query, ma se la latenza delle query è troppo elevata, è possibile aggiungere capacità o identificare i periodi di attività di query bassa per il caricamento di un indice.

Per altre informazioni, vedere Strategie di importazione dei dati.

Risolvere gli errori comuni