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

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

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

Ниже приведены ответы на распространенные вопросы о задачах, которые не указаны в предыдущем списке.

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

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

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

Prerequisites

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".

  

• Если вы предпочитаете запускать справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, подумайте о запуске Azure CLI в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, войдите в Azure CLI с помощью команды az login . Чтобы завершить процесс аутентификации, следуйте шагам, отображаемым в вашем терминале. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".

  • Когда вас попросят, установите расширение Azure CLI при первом использовании. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

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

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

Список услуг в подписке

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

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

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 AI Search.

Subgroups:
    admin-key                    : Manage Azure AI Search admin keys.
    offering                     : Manage Azure AI Search offerings.
    private-endpoint-connection  : Manage Azure AI Search private endpoint connections.
    private-link-resource        : Manage Azure AI Search private link resources.
    query-key                    : Manage Azure AI Search query keys.
    service                      : Manage Service.
    shared-private-link-resource : Manage Azure AI Search shared private link resources.
    usage                        : Manage Usage.

В каждой подгруппе доступны несколько команд. Доступные команды для 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-адреса IPv4 или диапазоны CIDR в аргумент ip-rules, как показано ниже. Правила должны быть разделены запятыми (,) или точкой с запятой (;).

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

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

Частные конечные точки для поиска AI 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 см. в этом кратком руководстве по Приватный канал.

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

Кроме создания подключения к частной конечной точке, можно также выполнить с подключением операции showupdate и 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> 

Создание службы с конфиденциальными вычислениями

Конфиденциальные вычисления — это необязательный тип вычислений для защиты от использования данных. При настройке служба поиска развертывается на конфиденциальных виртуальных машинах (DCasv5 или DCesv5) вместо стандартных виртуальных машин. Этот тип вычислений также предусматривает дополнительную плату в размере 10% за платные уровни. Дополнительные сведения см. на странице цен.

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

Тип вычислений устанавливается на всё время существования вашей службы поиска. Чтобы долговременно настроить конфиденциальные вычисления, задайте compute-type свойство confidential в новой сервисной системе.

az search service create \
  --name <search-service-name> \
  --resource-group <search-service-resource-group-name> \
  --location <search-service-region> \
  --sku basic \
  --compute-type confidential

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

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

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

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

Служба создает значения для ключей 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", можно найти здесь вместе со связанными значениями ID группы.

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

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

Дальнейшие шаги

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

• Создайте индекс поиска ИИ Azure в портале Azure
• Настройка индексатора для загрузки данных из других служб
• Запрос индекса поиска искусственного интеллекта Azure, с помощью обозревателя поиска в портале Azure
• Использование службы "Поиск ИИ Azure" в .NET