Guida introduttiva: Creare un indice di ricerca in Ricerca di intelligenza artificiale di Azure con REST

Informazioni su come usare le API REST di ricerca per creare, caricare ed eseguire query su un indice di ricerca in Ricerca di intelligenza artificiale di Azure.

L'articolo usa l'app Postman. Scaricare e importare una raccolta Postman o creare richieste manualmente usando le istruzioni contenute in questo articolo.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Prerequisiti

Copiare una chiave e un URL

Le chiamate REST richiedono l'endpoint di servizio e una chiave API per ogni richiesta. È possibile ottenere questi valori dalla portale di Azure.

  1. Accedere al portale di Azure, passare alla pagina Panoramica e copiare l'URL. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.

  2. In Impostazioni> Chiavi copiare una chiave di amministratore. Amministrazione chiavi vengono usate per aggiungere, modificare ed eliminare oggetti. Sono disponibili due chiavi di amministrazione intercambiabili. Copiarne uno.

    Screenshot of the URL and API keys in the Azure portal.

Una chiave API valida stabilisce un trust, per ogni richiesta, tra l'applicazione che invia la richiesta e il servizio di ricerca che la gestisce.

Impostare le variabili di raccolta

Postman fornisce variabili di raccolta, racchiuse tra parentesi quadre in una richiesta, per riutilizzare la stessa stringa in ogni richiesta. Le variabili di raccolta vengono usate per i valori specifici del cliente, ad esempio {{service-name}} nell'URI o {{admin-key}} nell'intestazione della richiesta.

Un URI con più variabili è simile al seguente:

https://{{service-name}}.search.windows.net/indexes/{{index-name}}?api-version={{api-version}}

Un'intestazione di richiesta per le chiamate di Ricerca intelligenza artificiale di Azure deve essere Content-Type impostata su application/jsone un api-key set su una chiave API del servizio di ricerca. In questo argomento di avvio rapido l'oggetto api-key nell'intestazione della richiesta viene specificato come variabile.

  1. Aprire l'app Postman e importare la raccolta di esempi o crearne una nuova.

  2. Selezionare il menu di accesso della raccolta, selezionare Modifica e specificare il nome del servizio di ricerca e una chiave API amministratore.

    Screenshot of the Postman collection variable page.

Creare un indice

Usare Create Index (REST) per specificare uno schema. L'endpoint include la /indexes raccolta e hotels-quickstart per il nome dell'indice.

  1. Impostare il verbo su PUT.

  2. Copiare questo URL https://{{service-name}}.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01.

  3. In Intestazioni impostare su Content-Typeapplication/json e su api-key{{admin-key}}.

  4. In Corpo incollare nella definizione dell'indice (json copiabile viene fornito nella sezione successiva). Assicurarsi che la selezione del corpo della richiesta sia non elaborata e che il tipo sia json

  5. Selezionare Invia.

    Screenshot of the PUT create index request.

Definizione di indice

La raccolta campi (fields) definisce la struttura del documento. Ogni documento deve avere questi campi e ogni campo deve avere un tipo di dati EDM. Nella ricerca full-text vengono usati campi stringa. Se si vuole che i dati numerici siano ricercabili, assicurarsi che il tipo di dati sia Edm.String. Altri tipi di dati, ad Edm.Int32 esempio, sono filtrabili, ordinabili, visualizzabili e recuperabili, ma non ricercabili full-text.

Gli attributi nel campo determinano le azioni consentite. Le API REST consentono molte azioni per impostazione predefinita. Ad esempio, tutte le stringhe sono ricercabili e recuperabili per impostazione predefinita. Per le API REST, potrebbe essere necessario solo gli attributi se è necessario disattivare un comportamento.

{
    "name": "hotels-quickstart",  
    "fields": [
        {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
        {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
        {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
        {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
        {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
        {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Address", "type": "Edm.ComplexType", 
        "fields": [
        {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
        {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
        ]
     }
  ]
}

Quando si invia questa richiesta, si dovrebbe ottenere una risposta HTTP 201, che indica che l'indice è stato creato correttamente. È possibile verificare che l'indice esista nel portale.

Suggerimento

Se viene restituita una risposta HTTP 504, verificare se nell'URL è specificato HTTPS. Se viene visualizzata la risposta HTTP 400 o 404, esaminare il corpo della richiesta per verificare che le operazioni di copia e incolla sono state eseguite correttamente. Un HTTP 403 indica in genere un problema con la chiave API (una chiave non valida o un problema di sintassi con la modalità di specifica della chiave API).

Caricare i documenti

La creazione e il caricamento dell'indice sono passaggi separati. In Ricerca di intelligenza artificiale di Azure l'indice contiene tutti i dati ricercabili e le query eseguite nel servizio di ricerca. Per le chiamate REST, i dati vengono forniti come documenti JSON. Usare l'API REST Documents- Index per questa attività.

L'URL è stato esteso per includere le raccolte docs e l'operazione index.

  1. Impostare il verbo su POST.

  2. Copiare questo URL https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01.

  3. Configurare le intestazioni della richiesta come è stato fatto nel passaggio precedente.

  4. Specificare i documenti JSON (JSON copiabile viene fornito nella sezione successiva) nel corpo della richiesta.

  5. Selezionare Invia.

    Screenshot of a POST load documents request.

Documenti JSON da caricare nell'indice

Il corpo della richiesta contiene quattro documenti da aggiungere all'indice degli hotel.

{
    "value": [
    {
    "@search.action": "upload",
    "HotelId": "1",
    "HotelName": "Secret Point Motel",
    "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" ],
    "ParkingIncluded": false,
    "LastRenovationDate": "1970-01-18T00:00:00Z",
    "Rating": 3.60,
    "Address": 
        {
        "StreetAddress": "677 5th Ave",
        "City": "New York",
        "StateProvince": "NY",
        "PostalCode": "10022",
        "Country": "USA"
        } 
    },
    {
    "@search.action": "upload",
    "HotelId": "2",
    "HotelName": "Twin Dome Motel",
    "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
    "Category": "Boutique",
    "Tags": [ "pool", "free wifi", "concierge" ],
    "ParkingIncluded": false,
    "LastRenovationDate": "1979-02-18T00:00:00Z",
    "Rating": 3.60,
    "Address": 
        {
        "StreetAddress": "140 University Town Center Dr",
        "City": "Sarasota",
        "StateProvince": "FL",
        "PostalCode": "34243",
        "Country": "USA"
        } 
    },
    {
    "@search.action": "upload",
    "HotelId": "3",
    "HotelName": "Triple Landscape Hotel",
    "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
    "Category": "Resort and Spa",
    "Tags": [ "air conditioning", "bar", "continental breakfast" ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2015-09-20T00:00:00Z",
    "Rating": 4.80,
    "Address": 
        {
        "StreetAddress": "3393 Peachtree Rd",
        "City": "Atlanta",
        "StateProvince": "GA",
        "PostalCode": "30326",
        "Country": "USA"
        } 
    },
    {
    "@search.action": "upload",
    "HotelId": "4",
    "HotelName": "Sublime Cliff Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.",
    "Category": "Boutique",
    "Tags": [ "concierge", "view", "24-hour front desk service" ],
    "ParkingIncluded": true,
    "LastRenovationDate": "1960-02-06T00:00:00Z",
    "Rating": 4.60,
    "Address": 
        {
        "StreetAddress": "7400 San Pedro Ave",
        "City": "San Antonio",
        "StateProvince": "TX",
        "PostalCode": "78216",
        "Country": "USA"
        }
    }
  ]
}

Entro pochi secondi si dovrebbe visualizzare una risposta HTTP 201 nell'elenco delle sessioni. Questo indica che i documenti sono stati creati correttamente.

Se viene restituito un codice 207, significa che il caricamento di almeno uno dei documenti non è riuscito. Se viene restituito un codice 404, significa che è presente un errore di sintassi nell'intestazione o nel corpo della richiesta. Verificare di aver modificato l'endpoint per includere /docs/index.

Eseguire la ricerca in un indice

Ora che l'indice e il set di documenti sono stati caricati, è possibile sottoporli a query con l'API REST di ricerca documenti.

Usare GET o POST per eseguire query su un indice. In una chiamata GET specificare i parametri di query nell'URI. In POST specificare i parametri di query in JSON. POST è preferibile per impostare più parametri di query.

L'URL viene esteso per includere un'espressione di query, specificata usando l'operatore /docs/search .

  1. Impostare il verbo su GET.

  2. Copiare questo URL https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2023-11-01. Non esiste alcun corpo JSON per questa richiesta. Tutti i parametri si trovano nell'URI. In una richiesta GET, la versione dell'API è preceduta da un & carattere.

  3. Selezionare Invia.

    Questa query è vuota e restituisce un conteggio dei documenti nei risultati della ricerca. La richiesta e la risposta dovrebbero essere simili allo screenshot seguente per Postman dopo aver selezionato Invia. Il codice di stato dovrebbe essere 200.

    Screenshot of a GET query request.

  4. Impostare il verbo su POST.

  5. Copiare questo URL https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs/search?api-version=2023-11-01. In una richiesta POST, la versione dell'API è preceduta da un ? carattere.

  6. Copiare in questa query JSON e quindi selezionare Invia.

    {
        "search": "lake view",
        "select": "HotelId, HotelName, Tags, Description",
        "searchFields": "Description, Tags",
        "count": true
    }
    

    La richiesta e la risposta dovrebbero essere simili allo screenshot seguente. Per altri esempi di query, inclusi i filtri e l'ordinamento, vedere Esempi di query.

    Screenshot of a POST request and response in Postman.

Ottenere le proprietà dell'indice

È anche possibile usare Get Index Statistics per recuperare i conteggi dei documenti e le dimensioni dell'indice:

https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/stats?api-version=2023-11-01

L'aggiunta di /stats all'URL restituisce informazioni sull'indice. In Postman la richiesta dovrebbe essere simile alla seguente e la risposta include il numero di documenti e lo spazio usato in byte.

Screenshot of the Get Statistics request.

Pulire le risorse

Quando si lavora nella propria sottoscrizione, al termine di un progetto è buona norma determinare se le risorse create sono ancora necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare risorse singole oppure gruppi di risorse per eliminare l'intero set di risorse.

Per trovare e gestire le risorse nel portale, usare il collegamento Tutte le risorse o Gruppi di risorse nel riquadro di spostamento a sinistra.

In un servizio gratuito ricordare la limitazione di tre indici, indicizzatori e origini dati. Per non superare il limite, è possibile eliminare i singoli elementi nel portale.

Passaggi successivi

Ora che si è appreso come eseguire attività di base, provare funzionalità avanzate, ad esempio indicizzatori o pipeline di arricchimento che aggiungono trasformazioni di contenuto all'indicizzazione. È consigliabile usare l'articolo seguente: