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

Статья
04/05/2024

Командлеты и скрипты PowerShell можно запускать в Windows, Linux или в Azure Cloud Shell, чтобы создать и настроить поиск ИИ Azure.

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

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

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

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

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

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

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

Проверка версий и загрузка модулей

Примеры в этой статье являются интерактивными и требуют повышенных разрешений. Требуются локальные PowerShell и Azure PowerShell (модуль Az ).

Проверка версии PowerShell

Установите последнюю версию PowerShell , если у вас ее нет.

$PSVersionTable.PSVersion

Загрузка Azure PowerShell

Если вы не уверены, установлен ли модуль Az, выполните следующую команду, чтобы проверить это.

Get-InstalledModule -Name Az

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

Import-Module -Name Az

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

Connect-AzAccount

Если у вас несколько подписок Azure, необходимо указать одну из них. Чтобы просмотреть список текущих подписок, выполните следующую команду.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Чтобы указать подписку, выполните указанную ниже команду. В приведенном ниже примере имя подписки — ContosoSubscription.

Select-AzSubscription -SubscriptionName ContosoSubscription

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

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

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

Get-AzResource -ResourceType Microsoft.Search/searchServices | ft

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

Get-AzResource -ResourceName <service-name>

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

Name              : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType      : Microsoft.Search/searchServices
Location          : westus
ResourceId        : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

Импорт `Az.Search`

Команды из Az.Search недоступны, пока не загрузите модуль.

Install-Module -Name Az.Search -Scope CurrentUser

Вывод списка всех `Az.Search` команд

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

Get-Command -Module Az.Search

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

CommandType     Name                                               Version     Source                                                                
-----------     ----                                               -------     ------                                                                
Cmdlet          Get-AzSearchAdminKeyPair                           0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchPrivateEndpointConnection              0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchPrivateLinkResource                    0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchQueryKey                               0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchService                                0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchSharedPrivateLinkResource              0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchAdminKey                               0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchQueryKey                               0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchService                                0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchSharedPrivateLinkResource              0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchPrivateEndpointConnection           0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchQueryKey                            0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchService                             0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchSharedPrivateLinkResource           0.10.0      Az.Search                                                             
Cmdlet          Set-AzSearchPrivateEndpointConnection              0.10.0      Az.Search                                                             
Cmdlet          Set-AzSearchService                                0.10.0      Az.Search                                                             
Cmdlet          Set-AzSearchSharedPrivateLinkResource              0.10.0      Az.Search

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

Update-Module -Name Az.Search

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

После импорта модуля Az.Search и определения группы ресурсов, содержащей вашу службу поиска, выполните командлет Get-AzSearchService, чтобы получить определение службы, включая имя, регион, уровень, а также число реплик и секций. Для этой команды укажите группу ресурсов, содержащую службу поиска.

Get-AzSearchService -ResourceGroupName <resource-group-name>

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

Name              : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType      : Microsoft.Search/searchServices
Location          : West US
Sku               : Standard
ReplicaCount      : 1
PartitionCount    : 1
HostingMode       : Default
ResourceId        : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

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

Командлет New-AzSearchService используется для создания службы поиска.

New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default

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

ResourceGroupName : demo-westus
Name              : my-demo-searchapp
Id                : /subscriptions/<alphanumeric-subscription-ID>/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location          : West US
Sku               : Standard
ReplicaCount      : 3
PartitionCount    : 3
HostingMode       : Default
Tags

Remove-AzSearchService используется для удаления службы и ее данных.

Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>

Вам будет предложено подтвердить действие.

Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

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

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

$ipRules = @([pscustomobject]@{Value="55.5.63.73"},
		[pscustomobject]@{Value="52.228.215.197"},
		[pscustomobject]@{Value="101.37.221.205"})

 New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard `
                      -Location "West US" `
                      -PartitionCount 3 -ReplicaCount 3 `
                      -HostingMode Default `
                      -IPRuleList $ipRules

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

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

New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard `
                      -Location "West US" `
                      -PartitionCount 3 -ReplicaCount 3 `
                      -HostingMode Default `
                      -IdentityType SystemAssigned

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

Для создания службы S3HD используется сочетание -Sku и -HostingMode используется. Задайте для -Sku значение Standard3 и для -HostingMode — HighDensity.

New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard3 `
                      -Location "West US" `
                      -PartitionCount 1 -ReplicaCount 3 `
                      -HostingMode HighDensity

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

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

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

Сначала разверните службу поиска, задав для параметра PublicNetworkAccess значение Disabled.

$searchService = New-AzSearchService `
    -ResourceGroupName <search-service-resource-group-name> `
    -Name <search-service-name> `
    -Sku Standard `
    -Location "West US" `
    -PartitionCount 1 -ReplicaCount 1 `
    -HostingMode Default `
    -PublicNetworkAccess Disabled

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

# Create the subnet
$subnetConfig = New-AzVirtualNetworkSubnetConfig `
    -Name <subnet-name> `
    -AddressPrefix 10.1.0.0/24 `
    -PrivateEndpointNetworkPolicies Disabled 

# Create the virtual network
$virtualNetwork = New-AzVirtualNetwork `
    -ResourceGroupName <vm-resource-group-name> `
    -Location "West US" `
    -Name <virtual-network-name> `
    -AddressPrefix 10.1.0.0/16 `
    -Subnet $subnetConfig

# Create the private network connection
$privateLinkConnection = New-AzPrivateLinkServiceConnection `
    -Name <private-link-name> `
    -PrivateLinkServiceId $searchService.Id `
    -GroupId searchService

# Create the private endpoint
$privateEndpoint = New-AzPrivateEndpoint `
    -Name <private-endpoint-name> `
    -ResourceGroupName <private-endpoint-resource-group-name> `
    -Location "West US" `
    -Subnet $virtualNetwork.subnets[0] `
    -PrivateLinkServiceConnection $privateLinkConnection

Наконец, создайте частную зону DNS.

## Create private dns zone
$zone = New-AzPrivateDnsZone `
    -ResourceGroupName <private-dns-resource-group-name> `
    -Name "privatelink.search.windows.net"

## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
    -ResourceGroupName <private-dns-link-resource-group-name> `
    -ZoneName "privatelink.search.windows.net" `
    -Name "myLink" `
    -VirtualNetworkId $virtualNetwork.Id

## Create DNS configuration 
$config = New-AzPrivateDnsZoneConfig `
    -Name "privatelink.search.windows.net" `
    -PrivateDnsZoneId $zone.ResourceId

## Create DNS zone group
New-AzPrivateDnsZoneGroup `
    -ResourceGroupName <private-dns-zone-resource-group-name> `
    -PrivateEndpointName <private-endpoint-name> `
    -Name 'myZoneGroup' `
    -PrivateDnsZoneConfig $config

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

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

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

Командлет Get-AzSearchPrivateEndpointConnection используется для получения подключения к частной конечной точке и просмотра его состояния.

Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>

Командлет Set-AzSearchPrivateEndpointConnection используется для обновления подключения. В следующем примере задается подключение к частной конечной точке для отклонения:

Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected  -Description "Rejected"

Командлет Remove-AzSearchPrivateEndpointConnection используется для удаления подключения к частной конечной точке.

 Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>

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

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

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

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

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

New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary

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

Primary                    Secondary
-------                    ---------
<alphanumeric-guid>        <alphanumeric-guid>

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

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

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

New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>

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

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

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

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

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

Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6

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

ResourceGroupName : demo-westus
Name              : my-demo-searchapp
Location          : West US
Sku               : Standard
ReplicaCount      : 6
PartitionCount    : 6
HostingMode       : Default
Id                : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

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

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

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

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

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

New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-serviceresource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId <group-id> -RequestMessage "Please approve"

Командлет Get-AzSearchSharedPrivateLinkResource позволяет получить общие ресурсы приватного канала и просмотреть их состояние.

Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>

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

Approve-AzPrivateEndpointConnection `
    -Name <spl-name> `
    -ServiceName <search-service-name> `
    -ResourceGroupName <search-service-resource-group-name> `
    -Description = "Approved"

Командлет Remove-AzSearchSharedPrivateLinkResource используется для удаления общего ресурса приватного канала.

$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob

$job | Get-Job

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

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

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

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

Проверка версий и загрузка модулей

Проверка версии PowerShell

Загрузка Azure PowerShell

Подключение к Azure с помощью маркера входа в браузер

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

Импорт Az.Search

Вывод списка всех Az.Search команд

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительные ресурсы

Импорт `Az.Search`

Вывод списка всех `Az.Search` команд