Condividi tramite

integrazione di ricerca di intelligenza artificiale .NET AspireAzure

  • Articolo

include integrazione dell'hosting e integrazione di Client

L'integrazione di ricerca documenti AI .NET AspireAzure consente di connettersi ai servizi di ricerca AI Azure (in precedenza Azure Ricerca Cognitiva) dalle applicazioni .NET. Azure AI Search è un sistema di recupero delle informazioni ottimizzato per le imprese, adatto ai tuoi contenuti eterogenei che vengono inseriti in un indice di ricerca e resi disponibili agli utenti tramite query e applicazioni. Viene fornito con un set completo di tecnologie di ricerca avanzate, compilate per applicazioni ad alte prestazioni su qualsiasi scala.

Integrazione del servizio di hosting

Il modello di integrazione dell'hosting .NET AspireAzure modella la risorsa di ricerca di intelligenza artificiale Azure come tipo AzureSearchResource. Per accedere a questo tipo e alle API per esprimerle nel progetto host dell'app, installare il pacchetto NuGet 📦Aspire.Hosting.Azure.Search.

dotnet add package Aspire.Hosting.Azure.Search

Per ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere una risorsa di ricerca di intelligenza artificiale Azure

Per aggiungere un AzureSearchResource al progetto host dell'app, chiamare il metodo AddAzureSearch specificando un nome:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Il codice precedente aggiunge una risorsa di ricerca di intelligenza artificiale Azure denominata search al progetto host dell'app. Il metodo WithReference passa le informazioni di connessione al progetto ExampleProject.

Importante

Quando chiami AddAzureSearch, chiama implicitamente AddAzureProvisioning(IDistributedApplicationBuilder), che aggiunge il supporto per la generazione dinamica delle risorse Azure durante l'avvio dell'app. L'app deve configurare l'abbonamento e la località appropriate. Per altre informazioni, vedere Provisioning locale: Configurazione

Generazione dell'approvvigionamento Bicep

Se sei nuovo a Bicep, si tratta di un linguaggio specifico per definire le risorse Azure. Con .NET.NET Aspire, non è necessario scrivere Bicep a mano; Le API di provisioning generano invece Bicep automaticamente. Quando pubblichi la tua app, il Bicep generato viene visualizzato insieme al file manifesto. Quando si aggiunge una risorsa di ricerca di intelligenza artificiale Azure, Bicep viene generato per effettuare il provisioning del servizio di ricerca con le impostazioni predefinite appropriate.

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

Il Bicep precedente è un modulo che fornisce una risorsa del servizio di ricerca di intelligenza artificiale Azure con le seguenti impostazioni predefinite:

  • location: il parametro location del gruppo di risorse, per impostazione predefinita è resourceGroup().location.
  • principalType: parametro di tipo principale della risorsa di ricerca di intelligenza artificiale Azure.
  • principalId: parametro ID principale della risorsa di ricerca di intelligenza artificiale Azure.
  • search: risorsa che rappresenta il servizio di ricerca di intelligenza artificiale Azure.
    • properties: proprietà del servizio di ricerca di intelligenza artificiale Azure:
      • hostingMode: è impostato su default.
      • disableLocalAuth: è impostato su true.
      • partitionCount: è impostato su 1.
      • replicaCount: è impostato su 1.
    • sku: il valore predefinito è basic.
  • search_SearchIndexDataContributor: assegnazione del ruolo di contributore ai dati dell'indice di ricerca dell'AI Azure. Per altre informazioni, vedere Search Index Data Contributor.
  • search_SearchServiceContributor: L’assegnazione del ruolo di collaboratore per il servizio di ricerca di intelligenza artificiale Azure. Per altre informazioni, vedere Collaboratore al servizio di ricerca.
  • connectionString: stringa di connessione per il servizio di ricerca di intelligenza artificiale Azure, che viene usata per connettersi al servizio. La stringa di connessione viene generata usando la proprietà Endpoint del servizio di ricerca di intelligenza artificiale Azure.

Il Bicep generato è un punto di partenza e può essere personalizzato per soddisfare i requisiti specifici.

Personalizzare l'infrastruttura di provisioning

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure, utilizzando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Ad esempio, è possibile configurare le partizioni del servizio di ricerca, le repliche e altro ancora:

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

Il codice precedente:

Sono disponibili molte altre opzioni di configurazione per personalizzare la risorsa di ricerca di intelligenza artificiale Azure. Per maggiori informazioni, vedere la personalizzazione Azure.Provisioning.

Connettersi a un servizio di ricerca di intelligenza artificiale Azure esistente

Potrebbe essere disponibile un servizio di ricerca di intelligenza artificiale Azure esistente a cui connettersi. È possibile concatenare una chiamata per annotare che il AzureSearchResource è una risorsa esistente:

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

Per altre informazioni sulla gestione delle risorse di ricerca di intelligenza artificiale Azure come risorse esistenti, vedere Usare risorse Azure esistenti.

In alternativa, invece di rappresentare una risorsa di ricerca di intelligenza artificiale Azure, è possibile aggiungere una stringa di connessione all'host dell'app. Si tratta di un approccio di tipo debole basato esclusivamente su un valore string. Per aggiungere una connessione a un servizio di ricerca di intelligenza artificiale Azure esistente, chiamare il metodo 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...

Nota

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker di messaggi, URI degli endpoint e altri servizi. Nella nomenclatura .NET.NET Aspire, il termine "stringa di connessione" è utilizzato per rappresentare qualsiasi tipo di informazioni di connessione.

La stringa di connessione è configurata nella configurazione dell'host dell'app, in genere in Segreti utente, nella sezione ConnectionStrings:

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

Per ulteriori informazioni, vedere Aggiungi le risorse esistenti con stringhe di connessione Azure.

Verifica dell'integrità delle integrazioni di hosting

L'integrazione dell'hosting di ricerca basato sull'intelligenza artificiale Azure attualmente non implementa alcun controllo di integrità. Questa limitazione è soggetta a modifiche nelle versioni future. Come sempre, è possibile aprire un problema se si hanno suggerimenti o commenti.

Client integrazione

Per iniziare con l'integrazione del client AI Search Documents .NET AspireAzure, installare il pacchetto NuGet 📦Aspire.Azure.Search.Documents nel progetto client dell'applicazione, ovvero il progetto per l'applicazione che utilizza il client AI Search Documents Azure.

dotnet add package Aspire.Azure.Search.Documents

Aggiungere un client di indice di ricerca di intelligenza artificiale Azure

Nel file Program.cs del progetto cliente, chiamate il metodo di estensione AddAzureSearchClient su qualsiasi IHostApplicationBuilder per registrare un SearchIndexClient da usare tramite il container per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddAzureSearchClient(connectionName: "search");

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa di ricerca di intelligenza artificiale Azure nel progetto host dell'app. Per altre informazioni, vedere Aggiungere una risorsa di ricerca di intelligenza artificiale Azure.

Dopo aver aggiunto il SearchIndexClient, puoi recuperare l'istanza del client usando la dependency injection. Ad esempio, per recuperare l'istanza client da un servizio di esempio:

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

È anche possibile recuperare un SearchClient che può essere usato per l'esecuzione di query chiamando il metodo 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;
    }
}

Per altre informazioni, vedere:

  • libreria client per la ricerca con intelligenza artificiale per esempi che utilizzano il .
  • Per ulteriori dettagli sull'iniezione delle dipendenze, vedere iniezione di dipendenze in .NET.

Aggiungere il client dell'indice di ricerca di intelligenza artificiale con chiave Azure

In alcuni casi potrebbe essere necessario registrare più istanze di SearchIndexClient con nomi di connessione diversi. Per registrare i client di ricerca di intelligenza artificiale con chiave Azure, chiamare il metodo AddKeyedAzureSearchClient:

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

Importante

Quando si usano i servizi con chiave, si prevede che la risorsa di ricerca di intelligenza artificiale Azure configuri due connessioni nominate, una per il images e una per l'documents.

È quindi possibile recuperare le istanze client usando l'iniezione di dipendenze. Ad esempio, per recuperare i client da un servizio:

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

Per altre informazioni, vedere Servizi con chiave in .NET.

Configurazione

La raccolta documenti di ricerca di intelligenza artificiale .NET AspireAzure offre più opzioni per configurare la connessione di ricerca di intelligenza artificiale Azure in base ai requisiti e alle convenzioni del progetto. È necessario specificare un Endpoint o un ConnectionString.

Usare una stringa di connessione

Una connessione può essere costruita dalla scheda Chiavi ed Endpoint con il formato Endpoint={endpoint};Key={key};. È possibile specificare il nome della stringa di connessione quando si chiama builder.AddAzureSearchClient():

builder.AddAzureSearchClient("searchConnectionName");

La stringa di connessione viene recuperata dalla sezione di configurazione ConnectionStrings. Sono supportati due formati di connessione:

Endpoint dell'account

L'approccio consigliato consiste nell'usare un Endpoint, che funziona con la proprietà AzureSearchSettings.Credential per stabilire una connessione. Se non è configurata alcuna credenziale, viene usato il DefaultAzureCredential.

{
  "ConnectionStrings": {
    "search": "https://{search_service}.search.windows.net/"
  }
}
Stringa di connessione

In alternativa, è possibile usare una stringa di connessione con chiave; non è l'approccio consigliato:

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

Utilizzare i provider di configurazione

La libreria di ricerca di intelligenza artificiale .NET AspireAzure supporta Microsoft.Extensions.Configuration. Carica i AzureSearchSettings e SearchClientOptions dalla configurazione usando la chiave Aspire:Azure:Search:Documents. Esempio appsettings.json che configura alcune delle opzioni:

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

Per lo schema completo per l'integrazione del client Azure AI Search Documents JSON, consultare Aspire.Azure.Search.Documents/ConfigurationSchema.json.

Usare inline delegati

È anche possibile passare il delegato Action<AzureSearchSettings> configureSettings per configurare alcune o tutte le opzioni in linea, ad esempio per disabilitare la tracciatura direttamente dal codice.

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

È anche possibile configurare il SearchClientOptions usando il parametro facoltativo Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder del metodo AddAzureSearchClient. Ad esempio, per impostare l'ID client per questo client:

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

Client verifiche di integrità dell'integrazione

Per impostazione predefinita, le integrazioni client .NET.NET Aspire hanno i controlli di integrità abilitati per tutti i servizi. Analogamente, molte integrazioni di hosting .NET.NET Aspire abilitano anche gli endpoint di controllo dell'integrità. Per altre informazioni, vedere:

L'integrazione di documenti di ricerca basata sull'intelligenza artificiale .NET AspireAzure implementa una singola verifica dello stato di salute che chiama il metodo GetServiceStatisticsAsync su SearchIndexClient per verificare che il servizio sia disponibile.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente la registrazione, la tracciatura e le metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione dei documenti di ricerca di intelligenza artificiale .NET AspireAzure usa le categorie di log seguenti:

  • Azure
  • Azure.Core
  • Azure.Identity

Tracciamento

L'integrazione dei documenti di ricerca con intelligenza artificiale .NET AspireAzure genera attività di tracciamento usando OpenTelemetry durante l'interazione con il servizio di ricerca.

Vedere anche