Partilhar via

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

Inclui:Integração de hospedagem incluída Integração de hospedagem —&— Client integração incluídaClient 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

Bicep gerado pelo processo de provisionamento

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

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

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

output name string = search.name

O Bicep anterior é um módulo que provisiona um recurso de serviço de IA para pesquisa. Além disso, as atribuições de função são criadas para o Azure recurso em um módulo separado:

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

param search_outputs_name string

param principalType string

param principalId string

resource search 'Microsoft.Search/searchServices@2023-11-01' existing = {
  name: search_outputs_name
}

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
}

O Bicep gerado é um ponto de partida e é influenciado por alterações na infraestrutura de provisionamento em C#. As alterações feitas diretamente no ficheiro Bicep serão sobrescritas, portanto, efetue alterações através das APIs de provisionamento em C# para garantir que sejam refletidas nos ficheiros gerados.

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, é possível configurar as partições dos serviços 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...

Importante

Ao chamar os métodos RunAsExisting, PublishAsExisting ou AsExisting para trabalhar com recursos que já estão presentes na sua assinatura Azure, deve adicionar determinados valores de configuração ao Host da Aplicação para garantir que .NET Aspire possa localizá-los. Os valores de configuração necessários incluem SubscriptionId, AllowResourceGroupCreation, ResourceGroup e Location. Se não os definir, irão aparecer erros de "Configuração ausente" no .NET.NET Aspire dashboard. Para obter mais informações sobre como defini-los, consulte Configuração.

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

Observação

Como alternativa, em vez de representar um recurso Azure AI Search, você pode adicionar uma cadeia de conexão ao host do aplicativo. Essa abordagem é fracamente tipada e não funciona com atribuições de função ou personalizações de infraestrutura. 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 configurados com chave 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 AI Search Documents .NET AspireAzure implementa uma única verificação de integridade que realiza uma chamada ao método GetServiceStatisticsAsync no SearchIndexClient para verificar a disponibilidade do serviço.

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