Condividi tramite

integrazione di .NET.NET Aspire Qdrant

  • Articolo

Include:integrazione dell'hosting e Client integrazione

Qdrant è un motore di ricerca di somiglianza di vettori open source che archivia, indici e cerca dati vettoriali su larga scala in modo efficiente. Viene comunemente usato nelle applicazioni di Machine Learning, intelligenza artificiale e data science.

I dati vettoriali codificano le informazioni come vettori matematici, ovvero matrici di numeri o coordinate. I sistemi di Machine Learning e intelligenza artificiale spesso usano vettori per rappresentare oggetti non strutturati come immagini, testo, audio o video. Ogni dimensione nel vettore descrive una caratteristica specifica dell'oggetto . Confrontandoli, i sistemi possono classificare, cercare e identificare cluster di oggetti.

In questo articolo, impari come usare l'integrazione di .NET.NET Aspire Qdrant. L'integrazione di .NET.NET Aspire Qdrant consente di connettersi ai database Qdrant esistenti o creare nuove istanze con l'immagine del container qdrant/qdrant.

Integrazione dell'hosting

L'integrazione di hosting di Qdrant modella il server come il tipo QdrantServerResource. Per accedere a questo tipo e API, aggiungere il . Hosting.Qdrant pacchetto NuGet nel progetto host dell'app .

dotnet add package Aspire.Hosting.Qdrant

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere una risorsa Qdrant

Nel progetto host dell'app chiamare AddQdrant per aggiungere e restituire un generatore di risorse Qdrant.

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithLifetime(ContainerLifetime.Persistent);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant)
       .WaitFor(qdrant);

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

Nota

Il contenitore Qdrant può essere lento all'avvio, quindi è consigliabile utilizzare un ciclo di vita persistente per evitare riavvii non necessari. Per ulteriori informazioni, vedere durata della risorsa del contenitore.

Quando .NET.NET Aspire aggiunge un'immagine del container all'host dell'app, come illustrato nell'esempio precedente con l'immagine qdrant/qdrant, crea una nuova istanza Qdrant nel computer locale. La risorsa viene denominata qdrant e quindi aggiunta al ExampleProject.

Il metodo WithReference configura una connessione nel ExampleProject denominato qdrant.

Suggerimento

Se si preferisce connettersi a un server Qdrant esistente, chiamare invece AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Suggerimento

L'immagine del contenitore qdrant/qdrant include un'interfaccia utente Web che è possibile usare per esplorare i vettori e amministrare il database. Per accedere a questo strumento, avviare la soluzione .NET Aspire e quindi, nel dashboard .NET Aspire selezionare l'endpoint per la risorsa Qdrant. Nella barra degli indirizzi del browser aggiungere /dashboard e premere INVIO.

Gestione delle chiavi API e passaggio di altri parametri per la risorsa Qdrant

Per connettersi a Qdrant, un client deve passare la chiave API corretta. Nel codice precedente, quando .NET.NET Aspire aggiunge una risorsa Qdrant alla soluzione, imposta la chiave API su una stringa casuale. Se invece si vuole usare una chiave API specifica, è possibile passarla come parametro apiKey:

var apiKey = builder.AddParameter("apiKey", secret: true);

var qdrant = builder.AddQdrant("qdrant", apiKey);

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

Qdrant supporta le chiavi API predefinite basate sulla configurazione usando la variabile di ambiente QDRANT__SERVICE__API_KEY.

Il codice precedente ottiene un parametro da passare all'API AddQdrant e assegna internamente il parametro alla variabile di ambiente QDRANT__SERVICE__API_KEY del contenitore Qdrant. Il parametro apiKey viene in genere specificato come segreto utente:

{
  "Parameters": {
    "apiKey": "Non-default-P@ssw0rd"
  }
}

Per altre informazioni, vedere Parametri esterni.

Aggiungere una risorsa Qdrant con volume di dati

Per aggiungere un volume di dati alla risorsa Qdrant, chiamare il metodo di estensione WithDataVolume:

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithLifetime(ContainerLifetime.Persistent)
                    .WithDataVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant)
       .WaitFor(qdrant);

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

Il volume di dati viene utilizzato per mantenere i dati Qdrant al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /qdrant/storage nel contenitore Qdrant e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai punti di montaggio associati , consultare la documentazione Docker: Volumi.

Aggiungere una risorsa Qdrant con bind mount dei dati

Per aggiungere un montaggio di associazione dati alla risorsa Qdrant, chiamare il metodo WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithLifetime(ContainerLifetime.Persistent)
                    .WithDataBindMount(source: @"C:\Qdrant\Data");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant)
       .WaitFor(qdrant);

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

Importante

I mount bind dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file sul sistema host, ideale per lo sviluppo e il test quando sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati Qdrant tra i riavvii del contenitore. Il punto di montaggio dei dati è montato nella cartella C:\Qdrant\Data su Windows (o /Qdrant/Data su Unix) all'interno del contenitore Qdrant sulla macchina host. Per ulteriori informazioni sui data bind mounts, consulta la documentazione Docker: Bind mounts.

Controlli di integrità dell'integrazione di hosting

L'integrazione dell'hosting Qdrant aggiunge automaticamente un controllo dello stato di salute per la risorsa Qdrant. Il controllo di integrità verifica che Qdrant sia in esecuzione e che sia possibile stabilire una connessione.

integrazione Client

Per iniziare a usare l'integrazione client .NET.NET Aspire di Qdrant, installare il pacchetto NuGet 📦Aspire.Qdrant.Client nel progetto consumatore del client, ovvero il progetto per l'applicazione che utilizza il client Qdrant. L'integrazione client Qdrant registra un Qdrant.Client.QdrantClient istanza che è possibile usare per interagire con i dati vettoriali Qdrant.

dotnet add package Aspire.Qdrant.Client

Aggiungere un client Qdrant

Nel file Program.cs del progetto che utilizza il client, chiama il metodo di estensione AddQdrantClient su qualsiasi IHostApplicationBuilder per registrare un QdrantClient da utilizzare tramite il contenitore di iniezione delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddQdrantClient("qdrant");

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Qdrant nel progetto host dell'app. In altre parole, quando si chiama AddQdrant e si specifica un nome di qdrant lo stesso nome deve essere usato quando si chiama AddQdrantClient. Per altre informazioni, vedere Aggiungere una risorsa Qdrant.

È quindi possibile recuperare l'istanza di QdrantClient usando l'inserimento delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

public class ExampleService(QdrantClient client)
{
    // Use client...
}

Per ulteriori informazioni sull'inserimento delle dipendenze, vedere .NET l'inserimento delle dipendenze.

Aggiungere il client Qdrant con chiave

In alcuni casi potrebbe essere necessario registrare più istanze di QdrantClient con nomi di connessione diversi. Per registrare i client Qdrant con chiave, chiamare il metodo AddKeyedQdrantClient:

builder.AddKeyedQdrantClient(name: "mainQdrant");
builder.AddKeyedQdrantClient(name: "loggingQdrant");

È quindi possibile recuperare le istanze di QdrantClient tramite l'iniezione delle dipendenze. Ad esempio, per recuperare le connessioni da un servizio di esempio:

public class ExampleService(
    [FromKeyedServices("mainQdrant")] QdrantClient mainQdrantClient,
    [FromKeyedServices("loggingQdrant")] QdrantClient loggingQdrantClient)
{
    // Use clients...
}

Per ulteriori informazioni sui servizi chiave, vedere .NET dipendenza di iniezione: Servizi chiave.

Configurazione

L'integrazione client .NET.NET Aspire Qdrant offre più opzioni per configurare la connessione a Qdrant in base ai requisiti e alle convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama builder.AddQdrantClient():

builder.AddQdrantClient("qdrant");

Quindi .NET.NET Aspire recupera la stringa di connessione dalla sezione di configurazione ConnectionStrings:

{
  "ConnectionStrings": {
    "qdrant": "Endpoint=http://localhost:6334;Key=123456!@#$%"
  }
}

Per impostazione predefinita, il QdrantClient usa l'endpoint dell'API gRPC.

Usare i fornitori di configurazione

L'integrazione client .NET.NET Aspire Qdrant supporta Microsoft.Extensions.Configuration. Carica il QdrantClientSettings dalla configurazione usando la chiave Aspire:Qdrant:Client. Di seguito è riportato un esempio di appsettings.json che configura alcune delle opzioni:

{
  "Aspire": {
    "Qdrant": {
      "Client": {
        "Endpoint": "http://localhost:6334/",
        "Key": "123456!@#$%"
      }
    }
  }
}

Per lo schema completo di integrazione del client Qdrant JSON, vedere Aspire. Qdrant.Client/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<QdrantClientSettings> configureSettings per configurare alcune o tutte le opzioni inline, ad esempio per impostare la chiave API dal codice:

builder.AddQdrantClient(
    "qdrant", 
    settings => settings.Key = "12345!@#$%");

Client controlli di integrità dell'integrazione

Per impostazione predefinita, le integrazioni .NET.NET Aspire abilitano i health checks per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente la registrazione, il tracciamento 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 di .NET Aspire Qdrant utilizza il sistema di logging .NET standard e le registrazioni di log verranno visualizzate nella categoria seguente:

  • Qdrant.Client

Tracciamento

L'integrazione di .NET.NET Aspire Qdrant attualmente non genera attività di tracciamento perché non sono supportate dalla libreria Qdrant.Client.

Metriche

L'integrazione di .NET.NET Aspire Qdrant non genera attualmente metriche perché non sono supportate dalla libreria Qdrant.Client.

Vedere anche