Compartilhar via

.NET Aspire Azure integração de pesquisa de IA

  • Artigo

Inclui: integração de hospedagem e Client integração

A integração .NET AspireAzure de Documentos de Pesquisa de IA permite que você se conecte aos serviços de Azure AI Search (anteriormente conhecidos como Azure Cognitive Search) a partir de seus aplicativos .NET. Azure Pesquisa de IA é um sistema de recuperação de informações pronto para uso corporativo, para o seu conteúdo heterogêneo que você ingere em um índice de pesquisa e apresenta aos usuários por meio de consultas e aplicativos. Ele é oferecido com um conjunto abrangente de tecnologias de pesquisa avançada, criadas para aplicativos de alto desempenho em qualquer escala.

Integração de hospedagem

A integração de hospedagem do .NET AspireAzure modela o recurso Azure de pesquisa de IA como o tipo AzureSearchResource. Para acessar esse tipo e as APIs para expressá-lo dentro do projeto host do seu aplicativo , instale o pacote NuGet .Hosting..Search.

dotnet add package Aspire.Hosting.Azure.Search

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicações .NET.

Adicionar um recurso de pesquisa de IA Azure

Para adicionar um AzureSearchResource ao projeto de host do aplicativo, chame o método AddAzureSearch fornecendo um nome:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

O código anterior adiciona um recurso de pesquisa de IA Azure chamado search ao projeto de host do aplicativo. O método WithReference passa as informações de conexão para o projeto ExampleProject.

Importante

Quando você chama AddAzureSearch, ele chama implicitamente AddAzureProvisioning(IDistributedApplicationBuilder)— o que adiciona suporte para gerar recursos Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração

Provisionamento gerado por script Bicep

Se você ainda não conhece o Bicep, trata-se de uma linguagem de domínio específico para definir recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, em vez disso, as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é exibido juntamente ao arquivo de manifesto. Quando você adiciona um recurso de Busca de IA Azure, o Bicep é gerado para provisionar o serviço de busca com os padrões apropriados.

@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'

O Bicep anterior é um módulo que provisiona um recurso de serviço de Pesquisa de IA Azure com os seguintes padrões:

  • location: o parâmetro de localização do grupo de recursos, o padrão é resourceGroup().location.
  • principalType: o parâmetro de tipo principal do recurso Azure AI Search.
  • principalId: o parâmetro de ID principal do recurso Azure AI Search.
  • search: recurso que representa o serviço Azure AI Search.
    • properties: as propriedades do serviço Azure AI Search:
      • hostingMode: está definido como default.
      • disableLocalAuth: está definido como true.
      • partitionCount: está definido como 1.
      • replicaCount: está definido como 1.
    • sku: é definido como basic.
  • search_SearchIndexDataContributor: Atribuição de função para o papel de colaborador de dados do índice Azure AI Search. Para obter mais informações, consulte o Colaborador de Dados do Índice de Pesquisa .
  • search_SearchServiceContributor: a atribuição de papel para o colaborador do serviço Azure AI Search. Para obter mais informações, consulte Colaborador do Serviço de Pesquisa.
  • connectionString: a string de conexão do serviço Azure AI Search, que é usada para se conectar ao serviço. A cadeia de conexão é gerada usando a propriedade Endpoint do serviço Azure AI Search.

O Bicep gerado é um ponto de partida e pode ser personalizado para atender aos seus requisitos específicos.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite a personalização do Bicep gerado ao oferecer uma API fluente para configurar os recursos do Azure utilizando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar as partições e réplicas do serviço de pesquisa, entre outros aspectos:

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");
    });

O código anterior:

Há muitas outras opções de configuração disponíveis para personalizar o recurso Azure pesquisa de IA. Para obter mais informações, consulte a Azure.Provisioning personalização.

Conectar-se a um serviço de pesquisa de IA Azure existente

Você pode ter um serviço de pesquisa de IA Azure existente ao qual deseja se conectar. Você pode encadear uma chamada para anotar que seu AzureSearchResource é um recurso existente:

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

Para obter mais informações sobre como tratar recursos de pesquisa de IA Azure como recursos existentes, consulte Usar recursos Azure existentes.

Como alternativa, em vez de representar um recurso de pesquisa de IA Azure, você pode adicionar uma cadeia de conexão ao host do aplicativo. Que é uma abordagem de tipo fraco que se baseia apenas em um valor string. Para adicionar uma conexão a um serviço de Pesquisa de IA Azure existente, chame o método 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...

Observação

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Em .NET.NET Aspire nomenclatura, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário, na seção ConnectionStrings:

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

Para obter mais informações, consulte Adicionar recursos existentes com cadeias de conexãoAzure.

Verificações de integridade das integrações de hospedagem

No momento, a integração de hospedagem do Azure AI Search não implementa nenhuma verificação de integridade. Essa limitação está sujeita a alterações em versões futuras. Como sempre, fique à vontade para abrir um problema se você tiver sugestões ou comentários.

integração Client

Para começar a usar a integração do cliente .NET AspireAzure AI Search Documents, instale o pacote NuGet 📦Aspire.Azure.Search.Documents no projeto de consumo do cliente, ou seja, o projeto do aplicativo que utiliza o cliente Azure AI Search Documents.

dotnet add package Aspire.Azure.Search.Documents

Adicionar um cliente de índice Azure AI Search

No arquivo Program.cs do projeto que utiliza o cliente, chame o método de extensão AddAzureSearchClient em qualquer IHostApplicationBuilder para registrar um SearchIndexClient para que possa ser usado por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureSearchClient(connectionName: "search");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Azure AI Search no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar um recurso de pesquisa de IA Azure.

Depois de adicionar o SearchIndexClient, você pode recuperar a instância do cliente usando a injeção de dependência. Por exemplo, para recuperar a instância do cliente de um serviço de exemplo:

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

Você também pode recuperar um SearchClient que pode ser usado para consulta, chamando o método 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;
    }
}

Para obter mais informações, consulte:

Adicionar o cliente de índice AI Search com chave Azure

Pode haver situações em que você deseja registrar várias instâncias de SearchIndexClient com nomes de conexão diferentes. Para registrar clientes de pesquisa de IA com chave Azure, chame o método AddKeyedAzureSearchClient.

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

Importante

Ao usar serviços baseados em chave, espera-se que o recurso de pesquisa de IA Azure tenha configurado duas conexões nomeadas, uma para o images e outra para o documents.

Em seguida, você pode recuperar as instâncias do cliente usando a injeção de dependência. Por exemplo, para recuperar os clientes de um serviço:

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

Para obter mais informações, consulte Serviços chaveados no .NET.

Configuração

A biblioteca de Documentos de Pesquisa de IA .NET AspireAzure fornece várias opções para configurar a conexão de Pesquisa de IA Azure com base nos requisitos e convenções do seu projeto. É necessário fornecer um Endpoint ou um ConnectionString.

Usar uma string de conexão

Uma conexão pode ser estabelecida a partir da guia Chaves e ponto final com o formato Endpoint={endpoint};Key={key};. Você pode fornecer o nome da cadeia de conexão ao chamar builder.AddAzureSearchClient():

builder.AddAzureSearchClient("searchConnectionName");

A cadeia de conexão é recuperada da seção de configuração ConnectionStrings. Há suporte para dois formatos de conexão:

Ponto de extremidade da conta

A abordagem recomendada é usar um Endpoint, que funciona com a propriedade AzureSearchSettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, o DefaultAzureCredential será usado.

{
  "ConnectionStrings": {
    "search": "https://{search_service}.search.windows.net/"
  }
}
Cadeia de conexão

Como alternativa, uma cadeia de conexão com chave pode ser usada, no entanto; não é a abordagem recomendada:

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

Usar provedores de configuração

A biblioteca de pesquisa de IA do .NET AspireAzure dá suporte a Microsoft.Extensions.Configuration. Ele carrega o AzureSearchSettings e o SearchClientOptions da configuração usando a chave Aspire:Azure:Search:Documents. Exemplo appsettings.json que configura algumas das opções:

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

Para o esquema completo de integração do cliente Azure de Documentos de Busca por IA JSON, consulte Aspire.Azure.Search.Documents/ConfigurationSchema.json.

Usar delegados embutidos

Você também pode passar o delegado Action<AzureSearchSettings> configureSettings para configurar algumas ou todas as opções diretamente na linha, por exemplo, para desabilitar o rastreamento a partir do código:

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

Você também pode configurar o SearchClientOptions usando o parâmetro Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder opcional do método AddAzureSearchClient. Por exemplo, para definir a ID do cliente para este cliente:

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

Client verificações de saúde de integração

Por padrão, .NET.NET Aspireintegrações de clientes têm verificações de saúde habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também habilitam endpoints para verificação de saúde. Para obter mais informações, consulte:

A integração .NET AspireAzure AI Search Documents implementa uma única verificação de integridade que chama o método GetServiceStatisticsAsync no SearchIndexClient para verificar se o serviço está disponível.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração .NET AspireAzure AI Search Documents usa as seguintes categorias de log:

  • Azure
  • Azure.Core
  • Azure.Identity

Rastreamento

A integração .NET AspireAzure AI Search Documents gera atividades de rastreamento usando OpenTelemetry ao se interagir com o serviço de pesquisa.

Consulte também