Partilhar via

.NET Aspire Azure integração de Pesquisa por IA

  • Artigo

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

A integração .NET AspireAzure AI Search Documents permite que você se conecte aos serviços Azure AI Search (anteriormente Azure Cognitive Search) a partir de seus aplicativos .NET. Azure AI Search é um sistema de recuperação de informações pronto para o ambiente empresarial, que processa o seu conteúdo heterogéneo num índice de pesquisa e o disponibiliza aos utilizadores através de consultas e aplicações. Ele vem com um conjunto abrangente de tecnologias de pesquisa avançadas, construídas para aplicativos de alto desempenho em qualquer escala.

Integração de hospedagem

A integração de hospedagem do .NET AspireAzure AI Search modela o recurso Azure AI Search como o tipo AzureSearchResource. Para aceder a este tipo e às APIs para defini-los no seu projeto host de aplicação , instale o pacote NuGet 📦Aspire.Hosting.Azure.Search.

dotnet add package Aspire.Hosting.Azure.Search

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

Adicionar um recurso Azure AI Search

Para adicionar um AzureSearchResource ao seu projeto de host de 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 Azure AI Search 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)—que adiciona suporte para gerar recursos de 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 automatizado com Bicep

Se és novo no Bicep, é uma linguagem de domínio específico para a definição de recursos Azure. Com .NET.NET Aspire, você não precisa escrever o Bicep manualmente; em vez disso, as APIs de provisionamento geram o Bicep para você. Ao publicares a tua aplicação, o Bicep gerado é exibido juntamente com o ficheiro de manifesto. Quando se adiciona um recurso Azure AI Search, o Bicep é gerado para provisionar o serviço de pesquisa 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 precedente é um módulo que provisiona um recurso de serviço Azure AI Search com os seguintes valores predefinidos:

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

O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

Personalizar a infraestrutura de provisionamento

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

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á muito mais opções de configuração disponíveis para personalizar o recurso Azure AI Search. Para obter mais informações, consulte 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 Azure recursos de pesquisa de IA como recursos existentes, consulte Usar recursos de Azure existentes.

Como alternativa, em vez de representar um recurso Azure AI Search, 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. Na nomenclatura .NET.NET Aspire, 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 Azure cadeias de conexão.

Verificações de estado da integração de hospedagem

Atualmente, a integração de hospedagem do Azure AI Search não implementa qualquer verificação de integridade. Esta limitação está sujeita a alterações em versões futuras. Como sempre, sinta-se à vontade para abrir um problema se tiver alguma sugestão ou feedback.

Client Integração

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 do cliente consumidor, ou seja, o projeto para a aplicação que usa o cliente Azure AI Search Documents.

dotnet add package Aspire.Azure.Search.Documents

Adicionar um cliente para o índice de pesquisa de IA Azure

No arquivo Program.cs do seu projeto cliente, chame o método de extensão AddAzureSearchClient em qualquer IHostApplicationBuilder para registar um SearchIndexClient para uso através do contentor de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureSearchClient(connectionName: "search");

")

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

Depois de adicionares o SearchIndexClient, podes 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 mais informações, consulte:

Adicionar cliente de índice de pesquisa de IA com chave Azure

Pode haver situações em que você queira registrar várias instâncias de SearchIndexClient com nomes de conexão diferentes. Para registrar clientes chaveados Azure AI Search, chame o método AddKeyedAzureSearchClient:

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

Importante

Ao usar serviços com chave, espera-se que seu recurso Azure AI Search configure duas conexões nomeadas, uma para o images e outra para o documents.

Em seguida, podes recuperar as instâncias do cliente usando 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 em .NET.

Configuração

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

Utilize uma cadeia de conexão

Uma ligação pode ser estabelecida na 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. Dois formatos de conexão são suportados:

Ponto final 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

Alternativamente, 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 .NET AspireAzure AI Search suporta Microsoft.Extensions.Configuration. Ele carrega o AzureSearchSettings e o SearchClientOptions da configuração usando a chave Aspire:Azure:Search:Documents. Exemplo de appsettings.json que configura algumas das opções:

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

Para obter o esquema completo de integração do cliente Azure AI Search Documents JSON, consulte Aspire.Azure. Search.Documents/ConfigurationSchema.json.

Usar delegados em linha

Você também pode passar o delegado Action<AzureSearchSettings> configureSettings para configurar algumas ou todas as opções em linha, por exemplo, para desativar o rastreamento no 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 integridade habilitadas para todos os serviços. Da mesma forma, muitas .NET.NET Aspireintegrações de hospedagem também habilitam endpoints de verificação de integridade. Para 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 as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na seção de configuração .

Registo

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

  • Azure
  • Azure.Core
  • Azure.Identity

Rastreio

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

Ver também