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

Интеграция поиска ИИ .NET AspireAzure

  • Статья

включает в себя: интеграцию хостинга и Client интеграцию

Интеграция .NET AspireAzure AI Search Documents позволяет подключаться к службам Azure AI Search (ранее Azure Cognitive Search) из ваших приложений .NET. Azure Поиск ИИ — это готовая для использования на предприятии система поиска информации для разнородного контента, который вы загружаете в поисковый индекс и предоставляете пользователям возможность доступа через запросы и приложения. Он поставляется с комплексным набором передовых технологий поиска, созданных для высокопроизводительных приложений в любом масштабе.

Хостинг-интеграция

Интеграция .NET AspireAzure для поиска ИИ представляет ресурс Azure поиска ИИ в виде типа AzureSearchResource. Чтобы получить доступ к этому типу и API для их использования в хосте приложения проекта, установите пакет NuGet 📦Aspire.Hosting.Azure.Search.

dotnet add package Aspire.Hosting.Azure.Search

Для получения дополнительной информации см. dotnet add package или управление зависимостями пакетов в приложениях .NET.

Добавьте ресурс Azure для поиска с использованием ИИ

Чтобы добавить AzureSearchResource в хост-проект приложения, вызовите метод AddAzureSearch, указав имя.

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.AddAzureSearch("search");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(search);

// After adding all resources, run the app...

Код выше добавляет ресурс поиска ИИ Azure с именем search в проект узла приложения. Метод WithReference передает сведения о подключении в проект ExampleProject.

Это важно

При вызове AddAzureSearchон неявно вызывает AddAzureProvisioning(IDistributedApplicationBuilder), что добавляет поддержку для динамической генерации ресурсов типа Azure во время запуска приложения. Приложение должно конфигурировать соответствующую подписку и местоположение. Дополнительные сведения см. в разделе "Локальное развертывание: конфигурация"

Сгенерирован шаблон развертывания Bicep

Если вы не знакомы с Bicep, это предметно-ориентированный язык для описания ресурсов Azure. При использовании .NET.NET Aspireвам не нужно писать Bicep вручную; вместо этого подготовительные API создают Bicep за вас. При публикации приложения сгенерированный файл Bicep выводится рядом с файлом манифеста. Когда вы добавляете ресурс Azure AI Search, автоматически создается Bicep для настройки службы поиска с предустановленными значениями.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalType string

param principalId string

resource search 'Microsoft.Search/searchServices@2023-11-01' = {
  name: take('search-${uniqueString(resourceGroup().id)}', 60)
  location: location
  properties: {
    hostingMode: 'default'
    disableLocalAuth: true
    partitionCount: 1
    replicaCount: 1
  }
  sku: {
    name: 'basic'
  }
  tags: {
    'aspire-resource-name': 'search'
  }
}

resource search_SearchIndexDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7')
    principalType: principalType
  }
  scope: search
}

resource search_SearchServiceContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0')
    principalType: principalType
  }
  scope: search
}

output connectionString string = 'Endpoint=https://${search.name}.search.windows.net'

Предыдущий модуль Bicep конфигурирует службу поиска на основе ИИ Azure со следующими настройками по умолчанию:

  • location: параметр расположения группы ресурсов по умолчанию используется для resourceGroup().location.
  • principalType: основной типовой параметр ресурса поиска ИИ Azure.
  • principalId: основной параметр идентификатора ресурса ИИ-поиска Azure.
  • search: ресурс, представляющий службу поиска Azure Искусственного интеллекта.
    • properties: свойства службы поиска с использованием ИИ Azure:
      • hostingMode: установлено значение default.
      • disableLocalAuth: установлено значение true.
      • partitionCount: установлено значение 1.
      • replicaCount: установлено значение 1.
    • sku: по умолчанию basic.
  • search_SearchIndexDataContributor: Назначение роли участника, обеспечивающего данные для индекса поиска ИИ Azure. Дополнительные сведения см. в Поисковый индекс Участник данных.
  • search_SearchServiceContributor: Назначение роли участника в службе поиска ИИ Azure. Дополнительные сведения см. в разделе Участник службы поиска.
  • connectionString: строка подключения для службы ИИ-поиска Azure, используемая для подключения к этой службе. Строка подключения создается с помощью свойства Endpoint службы поиска Azure ИИ.

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

Настройка инфраструктуры подготовки

Все .NET AspireAzure ресурсы — это подклассы типа AzureProvisioningResource. Этот тип позволяет настраивать создаваемый Bicep за счет предоставления гибкого API для конфигурации ресурсов Azure с помощью API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Например, можно настроить разделы, реплики и другие параметры службы поиска.

builder.AddAzureSearch("search")
    .ConfigureInfrastructure(infra =>
    {
        var searchService = infra.GetProvisionableResources()
                                 .OfType<SearchService>()
                                 .Single();

        searchService.PartitionCount = 6;
        searchService.ReplicaCount = 3;
        searchService.SearchSkuName = SearchServiceSkuName.Standard3;
        searchService.Tags.Add("ExampleKey", "Example value");
    });

Предыдущий код:

Доступно гораздо больше параметров конфигурации для настройки поисковой функции ИИ Azure. Дополнительные сведения см. в разделе Azure.Provisioning настройки.

Подключитесь к существующей ИИ службе поиска Azure

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

var builder = DistributedApplication.CreateBuilder(args);

var existingSearchName = builder.AddParameter("existingSearchName");
var existingSearchResourceGroup = builder.AddParameter("existingSearchResourceGroup");

var search = builder.AddAzureSearch("search")
                    .AsExisting(existingSearchName, existingSearchResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(search);

// After adding all resources, run the app...

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

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

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureSearch("search")
    : builder.AddConnectionString("search");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(search);

// After adding all resources, run the app...

Примечание.

Строки подключения используются для представления широкого диапазона сведений о подключении, включая подключения к базе данных, брокеры сообщений, URI конечной точки и другие службы. В .NET.NET Aspire номенклатуре термин "строка подключения" используется для представления любой информации о подключении.

Строка подключения настраивается в конфигурации узла приложения, как правило, в разделе "Секреты пользователей" в разделе ConnectionStrings:

{
  "ConnectionStrings": {
    "search": "https://{account_name}.search.azure.com/"
  }
}

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

Проверка работоспособности хостинговой интеграции

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

интеграция Client

Чтобы приступить к работе с интеграцией клиента .NET AspireAzure AI Search Documents, установите пакет NuGet 📦Aspire.Azure.Search.Documents в проект-клиент, то есть в проект для приложения, использующего клиент Azure AI Search Documents.

dotnet add package Aspire.Azure.Search.Documents

Добавьте клиента индекса поиска AI Azure

В файле Program.cs проекта, используемого клиентом, вызовите метод расширения AddAzureSearchClient для любой IHostApplicationBuilder, чтобы зарегистрировать SearchIndexClient для использования с помощью контейнера внедрения зависимостей. Метод принимает параметр имени подключения.

builder.AddAzureSearchClient(connectionName: "search");

Подсказка

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса поиска Azure ИИ в проекте хоста приложения. Дополнительные сведения см. в статье Добавление ресурса поиска Azure ИИ.

После добавления SearchIndexClient можно получить экземпляр клиента с помощью инъекции зависимостей. Например, чтобы получить экземпляр клиента из примера сервиса:

public class ExampleService(SearchIndexClient indexClient)
{
    // Use indexClient
}

Вы также можете получить SearchClient, который можно использовать для запроса, вызвав метод GetSearchClient(String):

public class ExampleService(SearchIndexClient indexClient)
{
    public async Task<long> GetDocumentCountAsync(
        string indexName,
        CancellationToken cancellationToken)
    {
        var searchClient = indexClient.GetSearchClient(indexName);

        var documentCountResponse = await searchClient.GetDocumentCountAsync(
            cancellationToken);

        return documentCountResponse.Value;
    }
}

Дополнительные сведения см. в следующем разделе:

Добавление клиента индекса поиска ИИ с ключом Azure

Могут возникнуть ситуации, когда вам может понадобиться зарегистрировать несколько экземпляров SearchIndexClient с различными именами подключений. Чтобы зарегистрировать клиентов поиска ИИ с ключом Azure, вызовите метод AddKeyedAzureSearchClient.

builder.AddKeyedAzureSearchClient(name: "images");
builder.AddKeyedAzureSearchClient(name: "documents");

Это важно

При использовании служб с ключами ожидается, что ваш ресурс Azure для поиска ИИ настраивает два именованных подключения: одно для images и одно для documents.

Затем экземпляры клиента можно получить, используя механизм внедрения зависимостей. Например, чтобы получить клиентов из сервиса:

public class ExampleService(
    [KeyedService("images")] SearchIndexClient imagesClient,
    [KeyedService("documents")] SearchIndexClient documentsClient)
{
    // Use clients...
}

Для получения дополнительной информации см. раздел «Ключевые услуги» в .NET.

Конфигурация

Библиотека документов поиска ИИ .NET AspireAzure предоставляет несколько вариантов для настройки подключения Azure поиска ИИ в соответствии с требованиями и соглашениями вашего проекта. Необходимо предоставить либо Endpoint, либо ConnectionString.

Используйте строку подключения

Подключение можно создать на вкладке "Ключи и конечная точка" в формате Endpoint={endpoint};Key={key};. При вызове builder.AddAzureSearchClient()можно указать имя строки подключения:

builder.AddAzureSearchClient("searchConnectionName");

Строка подключения извлекается из раздела конфигурации ConnectionStrings. Поддерживаются два формата подключения:

Конечная точка учетной записи

Рекомендуется использовать Endpoint, который работает со свойством AzureSearchSettings.Credential для установления подключения. Если учетные данные не настроены, используется DefaultAzureCredential.

{
  "ConnectionStrings": {
    "search": "https://{search_service}.search.windows.net/"
  }
}
Строка подключения

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

{
  "ConnectionStrings": {
    "search": "Endpoint=https://{search_service}.search.windows.net/;Key={account_key};"
  }
}

Использование поставщиков конфигураций

Библиотека ИИ поиска .NET AspireAzure поддерживает Microsoft.Extensions.Configuration. Он загружает AzureSearchSettings и SearchClientOptions из конфигурации с помощью ключа Aspire:Azure:Search:Documents. Пример appsettings.json, который настраивает некоторые параметры:

{
  "Aspire": {
    "Azure": {
      "Search": {
        "Documents": {
          "DisableTracing": false
        }
      }
    }
  }
}

Для получения полной схемы интеграции клиента поиска ИИ см. Aspire.Azure.Search.Documents/ConfigurationSchema.json.

Использование встроенных делегатов

Вы также можете передать делегат Action<AzureSearchSettings> configureSettings для настройки некоторых или всех параметров в коде напрямую, например, чтобы отключить возможность трассировки из кода:

builder.AddAzureSearchClient(
    "searchConnectionName",
    static settings => settings.DisableTracing = true);

Вы также можете настроить SearchClientOptions с помощью необязательного параметра Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder метода AddAzureSearchClient. Например, чтобы задать идентификатор клиента для этого клиента:

builder.AddAzureSearchClient(
    "searchConnectionName",
    configureClientBuilder: builder => builder.ConfigureOptions(
        static options => options.Diagnostics.ApplicationId = "CLIENT_ID"));

Client контроль состояния интеграционных систем

По умолчанию для всех служб в .NET.NET Aspireинтеграциях клиентов включены проверки работоспособности. Аналогичным образом, во многих .NET.NET Aspireхостинг-интеграциях также доступны конечные точки для проверки работоспособности. Дополнительные сведения см. в следующем разделе:

Интеграция .NET AspireAzure поиска ИИ реализует одну проверку работоспособности, которая вызывает метод GetServiceStatisticsAsync в SearchIndexClient, чтобы убедиться, что служба доступна.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают журналирование, трассировку и метрики, которые иногда называются столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция поиска документов с ИИ .NET AspireAzure использует следующие категории журналов:

  • Azure
  • Azure.Core
  • Azure.Identity

Отслеживание

Интеграция .NET AspireAzure для поисковых документов ИИ генерирует действия трассировки с помощью OpenTelemetry при взаимодействии со службой поиска.

См. также