Управление служба ИИ Azure с помощью Azure CLI

Статья
09/01/2024

Вы можете запускать команды и скрипты Azure CLI в Windows, macOS, Linux или в Azure Cloud Shell для создания и настройки поиска ИИ Azure.

Используйте модуль az search для выполнения следующих задач:

Вывод списка служб поиска в подписке
получение сведений о службе;
Создание или удаление службы
создание службы с частной конечной точкой;
Повторное создание ключей API администратора
создание или удаление ключей API запросов;
Увеличение или уменьшение масштаба с помощью реплик и секций
создание общего ресурса приватного канала.

Иногда возникают вопросы о задачах, не приведенных в списке выше.

Невозможно изменить имя сервера, регион или уровень программно или на портале. Нужные ресурсы выделяются при создании службы. Следовательно, при изменении базового оборудования (расположения или типа узла) потребуется новая служба.

Вы не можете использовать средства или API для передачи содержимого, например индекса, из одной службы в другую. В службе программное создание содержимого осуществляется через REST API службы поиска или пакет SDK, например пакет SDK Azure для .NET. Хотя для миграции содержимого нет выделенных команд, можно написать скрипт, вызывающий REST API или клиентская библиотека для создания и загрузки индексов в новой службе.

Функции администрирования предварительной версии обычно недоступны в модуле az search . Если вы хотите использовать функцию предварительной версии, используйте REST API управления и предварительную версию API.

Необходимые компоненты

Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.
Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
- Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.
- Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.
- Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Версии Azure CLI перечислены на сайте GitHub.

Модуль az search расширяет Azure CLI с полным четностью к стабильным версиям REST API службы "Управление поиском".

Вывод списка служб в подписке

Ниже приведены команды Az Resource, которые возвращают сведения о ресурсах и службах, уже подготовленных в вашей подписке. Если вы не уверены, сколько служб поиска уже создано, эти команды позволят вам получить эту информацию, не заходя на портал.

Первая команда возвращает все службы поиска.

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

В списке служб можно получить сведения о конкретном ресурсе.

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

Вывод списка всех команд az search

Сведения о подгруппах и командах, доступных в модуле az search, можно просмотреть в интерфейсе командной строки. Кроме того, можно ознакомиться с документацией.

Чтобы просмотреть подгруппы, доступные в az search, выполните следующую команду.

az search --help

Ответ должен выглядеть примерно так:

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"

В каждой подгруппе доступно несколько команд. Чтобы просмотреть доступные команды для подгруппы service, выполните следующую команду:

az search service --help

Можно также просмотреть аргументы, доступные для конкретной команды.

az search service create --help

Получение сведений о службе поиска

Если известно, что группа ресурсов содержит службу поиска, выполните команду az search service show, чтобы вернуть определение службы, включая имя, регион, уровень, реплику и число разделов. Для этой команды укажите группу ресурсов, содержащую службу поиска.

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

создание или удаление службы;

Чтобы создать новую службу поиска, используйте команду 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

Результаты должны выглядеть следующим образом.

{
  "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 удаляет службу и ее данные.

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

Создание службы с правилами для IP-адресов

В зависимости от требований безопасности может потребоваться создать службу поиска с настроенным брандмауэром IP-адресов. Для этого передайте аргументу ip-rules общедоступные IP-адреса (v4) или диапазоны CIDR, как показано ниже. Правила должны быть разделены запятыми (,) или точкой с запятой (;).

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"

Создание службы с управляемым удостоверением, назначаемым системой

В некоторых случаях, например при использовании управляемого удостоверения для подключения к источнику данных, необходимо включить управляемое удостоверение, назначенное системой. Для этого к команде следует добавить аргумент --identity-type SystemAssigned.

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

Создание службы с частной конечной точкой

Частные конечные точки для поиска ИИ Azure позволяют клиенту в виртуальной сети безопасно получать доступ к данным в индексе поиска по Приватный канал. Частная конечная точка использует для службы поиска IP-адрес из диапазона адресов виртуальной сети. Сетевой трафик между клиентом и службой поиска передается через виртуальную сеть и приватный канал в магистральной сети Майкрософт, что позволяет избежать рисков, связанных с использованием общедоступного Интернета. Дополнительные сведения см. в документации по созданию частной конечной точки для поиска ИИ Azure.

В следующем примере показано, как создать службу поиска с частной конечной точкой.

Сначала разверните службу поиска, задав для параметра PublicNetworkAccess значение 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

Затем создайте виртуальную сеть и частную конечную точку.

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

Наконец, создайте частную зону 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"

Дополнительные сведения о создании частных конечных точек в Azure CLI см. в этом Приватный канал кратком руководстве.

Управление подключениями к частным конечным точкам

Кроме создания подключения к частной конечной точке, можно также выполнить с подключением операции show update и delete.

Чтобы получить подключение к частной конечной точке и просмотреть ее состояние, используйте команду 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>

Чтобы обновить подключение, используйте команду az search private-endpoint-connection update. В следующем примере задается подключение к частной конечной точке для отклонения:

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"

Чтобы удалить подключение к частной конечной точке, используйте команду 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>

Повторное создание ключей администратора

Чтобы перенести API-ключи администрирования, используйте команду az search admin-key renew. Для каждой службы создаются два ключа администрирования, обеспечивающие доступ с проверкой подлинности. Эти ключи требуются для каждого запроса. Оба ключа администрирования функционально эквивалентны. Они предоставляют службе поиска полный доступ на запись с возможностью получения любых сведений, а также создания и удаления любого объекта. Так как ключа два, то при замене одного из них можно использовать другой.

Одновременно можно создать только один ключ, указав тип ключа primary или secondary. При использовании непрерывной службы не забудьте обновить весь код клиента, чтобы использовать дополнительный ключ при смене основного ключа. Старайтесь не изменять ключи, пока выполняются какие-либо операции.

Как можно ожидать, если повторно создать ключи и не обновить код клиента, запросы, использующие старый ключ, будут завершаться ошибкой. Повторное создание всех новых ключей не постоянно блокирует вас из службы, и вы по-прежнему можете получить доступ к службе через портал. После повторного создания основного и дополнительного ключей можно обновить код клиента, чтобы использовать новые ключи, и операции будут возобновлены.

Значения API-ключей создаются службой. Вы не можете предоставить пользовательский ключ для использования службы "Поиск ИИ Azure". Аналогичным образом, для ключей API администрирования нет определяемого пользователем имени. Ссылки на ключ — это фиксированные строки: primary или secondary.

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

Результаты должны выглядеть следующим образом. Возвращаются оба ключа, хотя изменить можно только один ключ за раз.

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

Создание или удаление ключей запросов

Чтобы создать ключи API запросов для доступа только для чтения из клиентских приложений в индекс поиска ИИ Azure, используйте az search query-key create. Ключи запросов используются для проверки подлинности в определенном индексе для получения результатов поиска. Ключи запросов не предоставляют доступ только для чтения к другим элементам службы, таким как индекс, источник данных или индексатор.

Вы не можете указать ключ для использования поиска ИИ Azure. API-ключи создаются службой.

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

Масштабирование реплик и разделов

Чтобы увеличить или уменьшить реплики и разделы, используйте команду az search service update. Добавление реплик или разделов увеличивает сумму счета, который содержит фиксированные и переменные платежи. Если у вас есть временная потребность в большей мощности обработки, можно увеличить реплики и секции для обработки рабочей нагрузки. Плитки в области мониторинга на странице "Обзор" портала отображают задержку запросов, число запросов в секунду и регулирование. С их помощью можно определить, достаточно ли текущей производительности.

Добавление или удаление ресурсов может занять некоторое время. Корректировки производительности выполняются в фоновом режиме, что позволяет продолжать обработку имеющихся рабочих нагрузок. Дополнительная емкость используется для входящих запросов сразу после его готовности без дополнительной настройки.

Снижение производительности может нарушить работу. Чтобы избежать удаления запросов, перед уменьшением производительности рекомендуется остановить все операции индексирования и задания индексатора. Если это нецелесообразно, можно рассмотреть реализацию более постепенного снижения производительности, удаляя по одной реплике и разделу за раз, пока не будут достигнуты новые целевые уровни.

После отправки команды нет способа завершить его в середине. Перед изменением счетчиков необходимо дождаться завершения команды.

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

Кроме обновления числа реплик и разделов, можно обновить ip-rules, public-access и identity-type.

создание общего ресурса приватного канала.

Частные конечные точки защищенных ресурсов, созданных с помощью API поиска ИИ Azure, называются общими ресурсами приватного канала. Это связано с тем, что вы предоставляете доступ к ресурсу, например учетную запись хранения, интегрированную с службой Приватный канал Azure.

Если вы используете индексатор для индексирования данных в службе "Поиск ИИ Azure", а источник данных находится в частной сети, вы можете создать подключение к исходящим частным конечным точкам для доступа к данным.

Полный список ресурсов Azure, для которых можно создать исходящие частные конечные точки из службы "Поиск ИИ Azure", можно найти здесь вместе со связанными значениями идентификатора группы.

Чтобы создать общий ресурс приватного канала, используйте команду az search shared-private-link-resource create. Помните, что для источника данных может потребоваться определенная конфигурация перед выполнением этой команды.

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"

Чтобы получить общие ресурсы приватного канала и просмотреть их состояние, используйте команду 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>

Прежде чем его можно будет использовать, необходимо утвердить подключение со следующей командой. Идентификатор подключения к частной конечной точке должен быть получен из дочернего ресурса. В этом случае мы получаем идентификатор подключения из az storage.

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

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

Чтобы удалить общий ресурс приватного канала, выполните команду 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>

Дополнительные сведения о настройке общих ресурсов приватного канала см. в статье о подключении индексатора через частную конечную точку.

Следующие шаги

Создайте индекс, а затем запросите индекс с помощью портала, интерфейсов REST API или пакета SDK для .NET.

Поделиться через