Zarządzanie usługa wyszukiwania sztucznej inteligencji platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure

  • Artykuł

Polecenia i skrypty interfejsu wiersza polecenia platformy Azure można uruchamiać w systemie Windows, macOS, Linux lub w usłudze Azure Cloud Shell, aby utworzyć i skonfigurować usługę Azure AI Search.

Użyj modułu az search, aby wykonać następujące zadania:

Od czasu do czasu są zadawane pytania dotyczące zadań , które nie znajdują się na powyższej liście.

Nie można programowo ani programowo zmienić nazwy serwera, regionu ani warstwy. Dedykowane zasoby są przydzielane podczas tworzenia usługi. W związku z tym zmiana podstawowego sprzętu (lokalizacji lub typu węzła) wymaga nowej usługi.

Nie można użyć narzędzi ani interfejsów API do transferu zawartości, takiej jak indeks, z jednej usługi do innej. W ramach usługi programowe tworzenie zawartości odbywa się za pomocą interfejsu API REST usługi wyszukiwania lub zestawu SDK, takiego jak zestaw Azure SDK dla platformy .NET. Chociaż nie ma dedykowanych poleceń migracji zawartości, możesz napisać skrypt wywołujący interfejs API REST lub bibliotekę klienta w celu tworzenia i ładowania indeksów w nowej usłudze.

Funkcje administracji w wersji zapoznawczej są zwykle niedostępne w module az search . Jeśli chcesz użyć funkcji w wersji zapoznawczej, użyj interfejsu API REST zarządzania i wersji zapoznawczej interfejsu API .

Wymagania wstępne

Wersje interfejsu wiersza polecenia platformy Azure są wyświetlane w witrynie GitHub.

Moduł az search rozszerza interfejs wiersza polecenia platformy Azure z pełną parzystością do stabilnych wersji interfejsów API REST zarządzania wyszukiwaniem.

Wyświetlanie listy usług w subskrypcji

Następujące polecenia pochodzą z polecenia az resource, zwracając informacje o istniejących zasobach i usługach już aprowizowanych w ramach subskrypcji. Jeśli nie wiesz, ile usług wyszukiwania zostało już utworzonych, te polecenia zwracają te informacje, zapisując podróż do portalu.

Pierwsze polecenie zwraca wszystkie usługi wyszukiwania.

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

Z listy usług zwróć informacje o określonym zasobie.

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

Wyświetl wszystkie polecenia az search

Informacje o podgrupach i poleceniach dostępnych w narzędziu az search można wyświetlić w interfejsie wiersza polecenia. Alternatywnie możesz przejrzeć dokumentację.

Aby wyświetlić podgrupy dostępne w programie az search, uruchom następujące polecenie.

az search --help

Odpowiedź powinna wyglądać podobnie do poniższych danych wyjściowych.

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"

W każdej podgrupie dostępnych jest wiele poleceń. Dostępne polecenia dla service podgrupy można wyświetlić, uruchamiając następujący wiersz.

az search service --help

Można również zobaczyć argumenty dostępne dla określonego polecenia.

az search service create --help

Pobieranie informacji o usłudze wyszukiwania

Jeśli znasz grupę zasobów zawierającą usługę wyszukiwania, uruchom polecenie az search service show , aby zwrócić definicję usługi, w tym nazwę, region, warstwę i liczbę replik i partycji. W tym poleceniu podaj grupę zasobów zawierającą usługę wyszukiwania.

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

Tworzenie lub usuwanie usługi

Aby utworzyć nową usługę wyszukiwania, użyj polecenia 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

Wyniki powinny wyglądać podobnie do następujących danych wyjściowych:

{
  "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 usuwa usługę i jej dane.

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

Tworzenie usługi z regułami adresów IP

W zależności od wymagań dotyczących zabezpieczeń możesz utworzyć usługę wyszukiwania z skonfigurowaną zaporą IP. W tym celu przekaż adresy PUBLICZNEGO adresu IP (v4) lub zakresy CIDR do argumentu ip-rules , jak pokazano poniżej. Reguły powinny być oddzielone przecinkiem (,) lub średnikiem (;).

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"

Tworzenie usługi z tożsamością zarządzaną przypisaną przez system

W niektórych przypadkach, takich jak w przypadku używania tożsamości zarządzanej do nawiązywania połączenia ze źródłem danych, należy włączyć tożsamość zarządzaną przypisaną przez system. Odbywa się to przez dodanie --identity-type SystemAssigned do polecenia .

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

Tworzenie usługi z prywatnym punktem końcowym

Prywatne punkty końcowe usługi Azure AI Search umożliwiają klientowi w sieci wirtualnej bezpieczny dostęp do danych w indeksie wyszukiwania za pośrednictwem usługi Private Link. Prywatny punkt końcowy używa adresu IP z przestrzeni adresowej sieci wirtualnej dla usługi wyszukiwania. Ruch sieciowy między klientem a usługą wyszukiwania przechodzi przez sieć wirtualną i łącze prywatne w sieci szkieletowej firmy Microsoft, eliminując narażenie z publicznego Internetu. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dotyczącą tworzenia prywatnego punktu końcowego dla usługi Azure AI Search.

W poniższym przykładzie pokazano, jak utworzyć usługę wyszukiwania z prywatnym punktem końcowym.

Najpierw wdróż usługę wyszukiwania z ustawioną PublicNetworkAccess wartością 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

Następnie utwórz sieć wirtualną i prywatny punkt końcowy.

# 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>

Na koniec utwórz prywatną strefę DNS.

## 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"

Aby uzyskać więcej informacji na temat tworzenia prywatnych punktów końcowych w interfejsie wiersza polecenia platformy Azure, zobacz ten przewodnik Szybki start dotyczący usługi Private Link.

Zarządzanie połączeniami z prywatnymi punktami końcowymi

Oprócz tworzenia połączenia prywatnego punktu końcowego można również show, updatei delete połączenia.

Aby pobrać połączenie prywatnego punktu końcowego i wyświetlić jego stan, użyj polecenia 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>

Aby zaktualizować połączenie, użyj polecenia az search private-endpoint-connection update. W poniższym przykładzie ustawiono połączenie prywatnego punktu końcowego na odrzucone:

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"

Aby usunąć połączenie prywatnego punktu końcowego, użyj polecenia 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>

Ponowne generowanie kluczy administratora

Aby przerzucić klucze interfejsu API administratora, użyj polecenia az search admin-key renew. Dwa klucze administratora są tworzone z każdą usługą w celu uwierzytelnienia dostępu. Klucze są wymagane na każdym żądaniu. Oba klucze administratora są funkcjonalnie równoważne, udzielając pełnego dostępu do zapisu w usłudze wyszukiwania z możliwością pobierania wszelkich informacji lub tworzenia i usuwania dowolnego obiektu. Istnieją dwa klucze, dzięki czemu można użyć jednego podczas zastępowania drugiego.

Można ponownie wygenerować tylko jeden raz, określony jako primary klucz lub secondary . Aby zapewnić nieprzerwaną obsługę, pamiętaj, aby zaktualizować cały kod klienta do używania klucza pomocniczego podczas przewracania klucza podstawowego. Unikaj zmieniania kluczy podczas wykonywania operacji.

Jak można się spodziewać, w przypadku ponownego generowania kluczy bez aktualizowania kodu klienta żądania używające starego klucza nie powiedzie się. Ponowne generowanie wszystkich nowych kluczy nie powoduje trwałej blokady usługi i nadal możesz uzyskać dostęp do usługi za pośrednictwem portalu. Po ponownej wygenerowaniu kluczy podstawowych i pomocniczych można odpowiednio zaktualizować kod klienta, aby używać nowych kluczy i operacji.

Wartości kluczy interfejsu API są generowane przez usługę. Nie można podać klucza niestandardowego dla usługi Azure AI Search do użycia. Podobnie nie ma zdefiniowanej przez użytkownika nazwy dla kluczy interfejsu API administratora. Odwołania do klucza są stałymi ciągami albo primarysecondary.

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

Wyniki powinny wyglądać podobnie do poniższych danych wyjściowych. Oba klucze są zwracane, mimo że zmieniasz tylko jeden naraz.

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

Tworzenie lub usuwanie kluczy zapytań

Aby utworzyć klucze interfejsu API zapytań na potrzeby dostępu tylko do odczytu z aplikacji klienckich do indeksu usługi Azure AI Search, użyj polecenia az search query-key create. Klucze zapytań służą do uwierzytelniania w określonym indeksie w celu pobierania wyników wyszukiwania. Klucze zapytań nie udzielają dostępu tylko do odczytu innym elementom usługi, takim jak indeks, źródło danych lub indeksator.

Nie można podać klucza do użycia przez usługę Azure AI Search. Klucze interfejsu API są generowane przez usługę.

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

Skalowanie replik i partycji

Aby zwiększyć lub zmniejszyć liczbę replik i partycji, użyj polecenia az search service update. Zwiększenie liczby replik lub partycji powoduje dodanie rachunku, który ma zarówno stałe, jak i zmienne opłaty. Jeśli potrzebujesz tymczasowej mocy obliczeniowej, możesz zwiększyć liczbę replik i partycji w celu obsługi obciążenia. Obszar monitorowania na stronie Portalu Przegląd zawiera kafelki dotyczące opóźnienia zapytań, zapytań na sekundę i ograniczania przepustowości wskazujących, czy bieżąca pojemność jest odpowiednia.

Może upłynąć trochę czasu, aby dodać lub usunąć zasoby. Korekty pojemności występują w tle, co umożliwia kontynuowanie istniejących obciążeń. Dodatkowa pojemność jest używana w przypadku żądań przychodzących, gdy tylko będzie gotowa, bez konieczności dodatkowej konfiguracji.

Usuwanie pojemności może być destrukcyjne. Zaleca się zatrzymanie wszystkich zadań indeksowania i indeksatora przed zmniejszeniem pojemności, aby uniknąć porzuconych żądań. Jeśli nie jest to możliwe, możesz rozważyć przyrostowe zmniejszenie pojemności, jednej repliki i partycji naraz, dopóki nie zostaną osiągnięte nowe poziomy docelowe.

Po przesłaniu polecenia nie ma możliwości zakończenia go w połowie. Przed zmianą liczby trzeba poczekać, aż polecenie zostanie zakończone.

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

Oprócz aktualizowania liczby replik i partycji można również aktualizować ip-ruleswartości , public-accessi identity-type.

Prywatne punkty końcowe zabezpieczonych zasobów, które są tworzone za pośrednictwem interfejsów API usługi Azure AI Search, są nazywane udostępnionymi zasobami łącza prywatnego. Dzieje się tak, ponieważ dostęp do zasobu jest "udostępnianie", taki jak konto magazynu zintegrowane z usługą Azure Private Link.

Jeśli używasz indeksatora do indeksowania danych w usłudze Azure AI Search, a źródło danych znajduje się w sieci prywatnej, możesz utworzyć wychodzące połączenie prywatnego punktu końcowego, aby uzyskać dostęp do danych.

Pełną listę zasobów platformy Azure, dla których można tworzyć wychodzące prywatne punkty końcowe z usługi Azure AI Search, można znaleźć tutaj wraz z powiązanymi wartościami identyfikatorów grupy.

Aby utworzyć zasób udostępnionego łącza prywatnego, użyj polecenia az search shared-private-link-resource create. Pamiętaj, że niektóre konfiguracje mogą być wymagane dla źródła danych przed uruchomieniem tego polecenia.

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"

Aby pobrać udostępnione zasoby łącza prywatnego i wyświetlić ich stan, użyj polecenia 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>

Aby można było go użyć, musisz zatwierdzić połączenie za pomocą następującego polecenia. Identyfikator połączenia prywatnego punktu końcowego musi zostać pobrany z zasobu podrzędnego. W tym przypadku uzyskujemy identyfikator połączenia z polecenia az storage.

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

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

Aby usunąć zasób udostępnionego łącza prywatnego, użyj polecenia 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>

Aby uzyskać więcej informacji na temat konfigurowania udostępnionych zasobów łącza prywatnego, zobacz Tworzenie połączeń indeksatora za pośrednictwem prywatnego punktu końcowego.

Następne kroki

Tworzenie indeksu, wykonywanie zapytań względem indeksu przy użyciu portalu, interfejsów API REST lub zestawu SDK platformy .NET.