Gestire i servizio di ricerca di intelligenza artificiale di Azure con l'interfaccia della riga di comando di Azure

  • Articolo

È possibile eseguire comandi e script dell'interfaccia della riga di comando di Azure in Windows, macOS, Linux o in Azure Cloud Shell per creare e configurare Ricerca di intelligenza artificiale di Azure.

Usare il modulo az search per eseguire le attività seguenti:

In alcuni casi, vengono poste domande sulle attività non presenti nell'elenco precedente.

Non è possibile modificare un nome del server, un'area o un livello a livello di codice o nel portale. Le risorse dedicate vengono allocate quando viene creato un servizio. Di conseguenza, la modifica dell'hardware sottostante (posizione o tipo di nodo) richiede un nuovo servizio.

Non è possibile usare strumenti o API per trasferire contenuto, ad esempio un indice, da un servizio a un altro. All'interno di un servizio, la creazione di contenuto a livello di codice è tramite l'API REST del servizio di ricerca o un SDK, ad esempio Azure SDK per .NET. Anche se non sono disponibili comandi dedicati per la migrazione del contenuto, è possibile scrivere script che chiamano l'API REST o una libreria client per creare e caricare indici in un nuovo servizio.

Le funzionalità di amministrazione dell'anteprima non sono in genere disponibili nel modulo az search . Se si vuole usare una funzionalità di anteprima, usare l'API REST di gestione e una versione dell'API di anteprima.

Prerequisiti

Le versioni dell'interfaccia della riga di comando di Azure sono elencate in GitHub.

Il modulo az search estende l'interfaccia della riga di comando di Azure con parità completa alle versioni stabili delle API REST di gestione della ricerca.

Elencare i servizi in una sottoscrizione

I comandi seguenti provengono da az resource, restituendo informazioni sulle risorse e i servizi esistenti di cui è già stato effettuato il provisioning nella sottoscrizione. Se non si conosce il numero di servizi di ricerca già creati, questi comandi restituiscono tali informazioni, salvando un viaggio nel portale.

Il primo comando restituisce tutti i servizi di ricerca.

az resource list --resource-type Microsoft.Search/searchServices --output table

Nell'elenco dei servizi restituire informazioni su una risorsa specifica.

az resource list --name <search-service-name>

Elencare tutti i comandi az search

È possibile visualizzare informazioni sui sottogruppi e i comandi disponibili in az search dall'interfaccia della riga di comando. In alternativa, è possibile esaminare la documentazione.

Per visualizzare i sottogruppi disponibili in az search, eseguire il comando seguente.

az search --help

La risposta dovrebbe essere simile all'output seguente.

Group
    az search : Manage Azure Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

All'interno di ogni sottogruppo sono disponibili più comandi. È possibile visualizzare i comandi disponibili per il service sottogruppo eseguendo la riga seguente.

az search service --help

È anche possibile visualizzare gli argomenti disponibili per un comando specifico.

az search service create --help

Ottenere informazioni sul servizio di ricerca

Se si conosce il gruppo di risorse contenente il servizio di ricerca, eseguire az search service show per restituire la definizione del servizio, tra cui nome, area, livello e numero di repliche e partizioni. Per questo comando, specificare il gruppo di risorse che contiene il servizio di ricerca.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

Creare o eliminare un servizio

Per creare un nuovo servizio di ricerca, usare il comando az search service create .

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

I risultati dovrebbero essere simili all'output seguente:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete rimuove il servizio e i relativi dati.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

Creare un servizio con regole IP

A seconda dei requisiti di sicurezza, potrebbe essere necessario creare un servizio di ricerca con un firewall IP configurato. A tale scopo, passare gli indirizzi IP pubblici (v4) o gli intervalli CIDR all'argomento ip-rules , come illustrato di seguito. Le regole devono essere separate da una virgola (,) o da un punto e virgola (;).

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

Creare un servizio con un'identità gestita assegnata dal sistema

In alcuni casi, ad esempio quando si usa l'identità gestita per connettersi a un'origine dati, è necessario attivare l'identità gestita assegnata dal sistema. A tale scopo, aggiungere --identity-type SystemAssigned al comando .

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

Creare un servizio con un endpoint privato

Gli endpoint privati per Ricerca intelligenza artificiale di Azure consentono a un client in una rete virtuale di accedere in modo sicuro ai dati in un indice di ricerca in un collegamento privato. L'endpoint privato usa un indirizzo IP dallo spazio di indirizzi della rete virtuale per il servizio di ricerca. Il traffico di rete tra il client e il servizio di ricerca attraversa la rete virtuale e un collegamento privato nella rete backbone Microsoft, eliminando l'esposizione dalla rete Internet pubblica. Per altre informazioni, vedere la documentazione sulla creazione di un endpoint privato per Ricerca di intelligenza artificiale di Azure.

Nell'esempio seguente viene illustrato come creare un servizio di ricerca con un endpoint privato.

Prima di tutto, distribuire un servizio di ricerca con PublicNetworkAccess impostato su Disabled.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

Creare quindi una rete virtuale e l'endpoint privato.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>

Infine, creare una zona DNS privata.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

Per altre informazioni sulla creazione di endpoint privati nell'interfaccia della riga di comando di Azure, vedere questa guida introduttiva collegamento privato.

Gestire le connessioni endpoint privato

Oltre a creare una connessione endpoint privato, è anche showpossibile , updatee delete la connessione.

Per recuperare una connessione endpoint privato e visualizzarne lo stato, usare az search private-endpoint-connection show.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Per aggiornare la connessione, usare az search private-endpoint-connection update. Nell'esempio seguente viene impostata una connessione endpoint privato su rifiutata:

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

Per eliminare la connessione all'endpoint privato, usare az search private-endpoint-connection delete.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Riscrivere una chiave amministratore

Per eseguire il rollover delle chiavi API di amministrazione, usare az search admin-key renew. Vengono create due chiavi di amministrazione con ogni servizio per l'accesso autenticato. Le chiavi sono necessarie per ogni richiesta. Entrambe le chiavi di amministrazione sono equivalenti a livello funzionale, concedendo l'accesso in scrittura completo a un servizio di ricerca con la possibilità di recuperare qualsiasi informazione o creare ed eliminare qualsiasi oggetto. Esistono due chiavi in modo che sia possibile usare una durante la sostituzione dell'altra.

È possibile rigenerare solo uno alla volta, specificato come chiave primary o secondary . Per un servizio senza interruzioni, ricordarsi di aggiornare tutto il codice client per usare una chiave secondaria durante il rollover della chiave primaria. Evitare di modificare le chiavi mentre le operazioni sono in esecuzione.

Come previsto, se si rigenerano chiavi senza aggiornare il codice client, le richieste che usano la chiave precedente avranno esito negativo. La rigenerazione di tutte le nuove chiavi non blocca definitivamente l'utente dal servizio ed è comunque possibile accedere al servizio tramite il portale. Dopo aver rigenerato le chiavi primarie e secondarie, è possibile aggiornare il codice client per usare le nuove chiavi e le nuove operazioni riprenderanno di conseguenza.

I valori per le chiavi API vengono generati dal servizio. Non è possibile fornire una chiave personalizzata per Ricerca di intelligenza artificiale di Azure da usare. Analogamente, non esiste un nome definito dall'utente per le chiavi API di amministrazione. I riferimenti alla chiave sono stringhe fisse, primary o secondary.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

I risultati dovrebbero essere simili all'output seguente. Entrambe le chiavi vengono restituite anche se si modifica solo una alla volta.

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

Creare o eliminare chiavi di query

Per creare chiavi API di query per l'accesso in sola lettura dalle app client a un indice di Ricerca intelligenza artificiale di Azure, usare az search query-key create. Le chiavi di query vengono usate per eseguire l'autenticazione in un indice specifico per il recupero dei risultati della ricerca. Le chiavi di query non concedono l'accesso in sola lettura ad altri elementi nel servizio, ad esempio un indice, un'origine dati o un indicizzatore.

Non è possibile fornire una chiave per Ricerca di intelligenza artificiale di Azure da usare. Le chiavi API vengono generate dal servizio.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

Ridimensionare repliche e partizioni

Per aumentare o ridurre le repliche e le partizioni, usare az search service update. L'aumento delle repliche o delle partizioni aggiunge alla fattura, con addebiti fissi e variabili. Se è necessaria una maggiore potenza di elaborazione, è possibile aumentare le repliche e le partizioni per gestire il carico di lavoro. L'area di monitoraggio nella pagina Del portale di panoramica include riquadri sulla latenza delle query, sulle query al secondo e sulla limitazione, che indica se la capacità corrente è adeguata.

L'aggiunta o la rimozione dell'origine può richiedere del tempo. Le modifiche alla capacità si verificano in background, consentendo ai carichi di lavoro esistenti di continuare. La capacità aggiuntiva viene usata per le richieste in ingresso non appena è pronta, senza alcuna configurazione aggiuntiva necessaria.

La rimozione della capacità può comportare interruzioni. È consigliabile arrestare tutti i processi di indicizzazione e indicizzatore prima di ridurre la capacità per evitare richieste eliminate. Se ciò non è fattibile, è possibile ridurre la capacità in modo incrementale, una replica e una partizione alla volta, fino al raggiungimento dei nuovi livelli di destinazione.

Dopo aver inviato il comando, non è possibile terminarlo a metà strada. È necessario attendere il completamento del comando prima di rivedere i conteggi.

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

Oltre ad aggiornare i conteggi delle repliche e delle partizioni, è anche possibile aggiornare ip-rules, public-accesse identity-type.

Gli endpoint privati delle risorse protette create tramite le API di Ricerca di intelligenza artificiale di Azure vengono definiti risorse di collegamento privato condiviso. Ciò è dovuto al fatto che si sta "condividendo" l'accesso a una risorsa, ad esempio un account di archiviazione integrato con il servizio collegamento privato di Azure.

Se si usa un indicizzatore per indicizzare i dati in Ricerca di intelligenza artificiale di Azure e l'origine dati si trova in una rete privata, è possibile creare una connessione endpoint privato in uscita per raggiungere i dati.

Un elenco completo delle risorse di Azure per cui è possibile creare endpoint privati in uscita da Ricerca intelligenza artificiale di Azure è disponibile qui insieme ai valori di ID gruppo correlati.

Per creare la risorsa di collegamento privato condiviso, usare az search shared-private-link-resource create. Tenere presente che alcune configurazioni potrebbero essere necessarie per l'origine dati prima di eseguire questo comando.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve"

Per recuperare le risorse di collegamento privato condiviso e visualizzare il relativo stato, usare az search shared-private-link-resource list.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

È necessario approvare la connessione con il comando seguente prima di poterla usare. L'ID della connessione all'endpoint privato deve essere recuperato dalla risorsa figlio. In questo caso, si ottiene l'ID connessione da az storage.

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

Per eliminare la risorsa di collegamento privato condiviso, usare az search shared-private-link-resource delete.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Per altre informazioni sulla configurazione delle risorse di collegamento privato condiviso, vedere Stabilire connessioni indicizzate tramite un endpoint privato.

Passaggi successivi

Compilare un indice, eseguire query su un indice usando il portale, le API REST o .NET SDK.