Freigeben über

.NET .NET Aspire Qdrant-Integration

  • Artikel

umfasst:Hosting-Integration und Client Integration

Qdrant ist eine Open-Source-Vektor-Ähnlichkeitssuchmaschine, die Vektordaten effizient speichert, indiziert und durchsucht. Es wird häufig in Maschinellem Lernen, künstlicher Intelligenz und Data Science-Anwendungen verwendet.

Vektordaten codieren Informationen als mathematische Vektoren, die Arrays von Zahlen oder Koordinaten sind. Maschinelles Lernen und KI-Systeme verwenden häufig Vektoren, um unstrukturierte Objekte wie Bilder, Text, Audio oder Video darzustellen. Jede Dimension im Vektor beschreibt ein bestimmtes Merkmal des Objekts. Durch den Vergleich können Systeme Cluster von Objekten klassifizieren, suchen und identifizieren.

In diesem Artikel erfahren Sie, wie Sie die .NET.NET Aspire Qdrant-Integration verwenden. Mit der .NET.NET Aspire Qdrant-Integration können Sie eine Verbindung zu vorhandenen Qdrant-Datenbanken herstellen oder neue Instanzen mit dem qdrant/qdrant-Container-Imageerstellen.

Hosting-Integration

Die Qdrant-Hosting-Integrationsmodelle modelliere die server als den QdrantServerResource-Typ. Um auf diesen Typ und diese APIs zuzugreifen, fügen Sie das 📦Aspire.Hosting.Qdrant NuGet-Paket im App-Host Projekt hinzu.

dotnet add package Aspire.Hosting.Qdrant

Weitere Informationen finden Sie unter dotnet add package oder Verwalten von Paketabhängigkeiten in .NET-Anwendungen.

Hinzufügen einer Qdrant-Ressource

Rufen Sie in Ihrem App-Hostprojekt AddQdrant auf, um einen Qdrant-Ressourcen-Generator hinzuzufügen und zurückzugeben.

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

Anmerkung

Der Qdrant-Container kann langsam starten, daher empfiehlt es sich, eine persistente Laufzeit zu verwenden, um unnötige Neustarts zu vermeiden. Weitere Informationen finden Sie unter Lebensdauer der Container-Ressourcen.

Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, erstellt dies eine neue Qdrant-Instanz auf dem lokalen Computer, wie im vorherigen Beispiel mit dem qdrant/qdrant-Image gezeigt. Die Ressource wird qdrant benannt und dann dem ExampleProjecthinzugefügt.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens qdrant.

Trinkgeld

Wenn Sie lieber eine Verbindung mit einer vorhandenen Qdrant-serverherstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Trinkgeld

Das qdrant/qdrant Containerimage enthält eine Web-UI, mit der Sie Ihre Vektoren erkunden und die Datenbank verwalten können. Um auf dieses Tool zuzugreifen, starten Sie Ihre .NET Aspire Lösung, und wählen Sie dann im dashboard .NET Aspire den Endpunkt für die Qdrant-Ressource aus. Fügen Sie in der Adressleiste Ihres Browsers /dashboard an, und drücken Sie Eingabetaste.

Verwaltung von API-Schlüsseln und die Übergabe weiterer Parameter für die Qdrant-Ressource

Um eine Verbindung mit Qdrant herzustellen, muss ein client den richtigen API-Schlüssel übergeben. Wenn .NET.NET Aspire ihrer Lösung im obigen Code eine Qdrant-Ressource hinzufügt, wird der API-Schlüssel auf eine zufällige Zeichenfolge festgelegt. Wenn Sie stattdessen einen bestimmten API-Schlüssel verwenden möchten, können Sie ihn als apiKey Parameter übergeben:

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

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

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

Qdrant unterstützt konfigurationsbasierte Standard-API-Schlüssel mithilfe der Umgebungsvariablen QDRANT__SERVICE__API_KEY.

Der vorangehende Code ruft einen Parameter ab, der an die AddQdrant-API übergeben werden soll, und ordnet den Parameter intern der QDRANT__SERVICE__API_KEY-Umgebungs-Variable des Qdrant-Containers zu. Der Parameter apiKey wird in der Regel als Nutzergeheimnisangegeben:

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

Weitere Informationen finden Sie unter Externe Parameter.

Hinzufügen einer Qdrant-Ressource mit Datenvolumen

Rufen Sie die WithDataVolume Erweiterungsmethode auf, um der Qdrant-Ressource ein Datenvolume hinzuzufügen:

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

Das Datenvolume wird verwendet, um die Qdrant-Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird im Pfad /qdrant/storage im Qdrant-Container bereitgestellt, und wenn kein name-Parameter angegeben ist, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Docker-Dokumentation: Datenvolumes.

Hinzufügen einer Qdrant-Ressource mit Datenbindungs-Bereitstellung

Rufen Sie die WithDataBindMount-Methode auf, um der Qdrant-Ressource ein Datenbindungs-Mount hinzuzufügen.

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

Wichtig

Daten Binden von Bereitstellungen mit eingeschränkter Funktionalität im Vergleich zu Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten, wodurch sie für Produktionsumgebungen besser geeignet sind. Bind-Mounts ermöglichen jedoch direkten Zugriff und die Änderung von Dateien auf dem Hostsystem, ideal für Entwicklung und Tests, wo Echtzeitänderungen erforderlich sind.

Datenbindungs-Bereitstellungen basieren auf dem Dateisystem des Hostcomputers, um die Qdrant-Daten über Containerneustarts hinweg beizubehalten. Die Datenbindemontage wird im Ordner C:\Qdrant\Data unter Windows (oder /Qdrant/Data auf Unix) auf dem Hostcomputer im Qdrant-Container eingehängt. Weitere Informationen zu Daten-Bind-Einhängungen finden Sie in der Docker Dokumentation: Bind-Einhängungen.

Integrations-Gesundheitschecks hosten

Die Qdrant-Hostingintegration fügt automatisch eine Gesundheitsprüfung für die Qdrant-Ressource hinzu. Die Systemprüfung überprüft, ob Qdrant läuft und ob eine Verbindung dazu hergestellt werden kann.

Client Integration

Um mit der .NET Aspire Qdrant client-Integration zu beginnen, installieren Sie das 📦Aspire.Qdrant.Client NuGet-Paket im Verbrauchsprojekt client, das heißt in dem Projekt der Anwendung, die Qdrant-clientverwendet. Die Qdrant-client-Integration registriert eine Qdrant-Client.QdrantClient--Instanz, mit der Sie auf Qdrant-Vektordaten zugreifen können.

dotnet add package Aspire.Qdrant.Client

Qdrant-client hinzufügen

Rufen Sie in der Datei Program.cs Ihres client-verbrauchenden Projekts die Erweiterungsmethode AddQdrantClient an jedem IHostApplicationBuilder auf, um eine QdrantClient für die Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddQdrantClient("qdrant");

Trinkgeld

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der Qdrant-Ressource im App-Hostprojekt verwendet wird. Anders ausgedrückt: Wenn Sie AddQdrant aufrufen und einen Namen von qdrant angeben, sollte dieser Name beim Aufrufen von AddQdrantClientverwendet werden. Weitere Informationen finden Sie unter Hinzufügen der Qdrant-Ressource.

Anschließend können Sie die QdrantClient Instanz mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Füge keyed Qdrant client hinzu

Es kann Situationen geben, in denen Sie mehrere QdrantClient Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die AddKeyedQdrantClient-Methode auf, um Keyed-Qdrant-Clients zu registrieren.

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

Anschließend können Sie die QdrantClient Instanzen mithilfe der Abhängigkeitsinjektion abrufen. So können Sie zum Beispiel die Verbindungen von einem Beispieldienst abrufen:

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

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: schlüsselbasierte Dienste.

Konfiguration

Die .NET Aspire Qdrant client Integration bietet mehrere Optionen zum Konfigurieren der Verbindung mit Qdrant basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von builder.AddQdrantClient()den Namen der Verbindungszeichenfolge angeben:

builder.AddQdrantClient("qdrant");

Anschließend ruft .NET.NET Aspire die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings ab:

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

Standardmäßig verwendet der QdrantClient den gRPC-API-Endpunkt.

Verwendung von Konfigurationsanbietern

Die .NET Aspire Qdrant client Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die QdrantClientSettings mithilfe des Aspire:Qdrant:Client Schlüssels aus der Konfiguration. Im Folgenden ein Beispiel für ein appsettings.json, das einige der Optionen konfiguriert:

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

Die vollständige Qdrant-Integration clientJSON finden Sie im Schema unter AspireQdrantClient/ConfigurationSchemajson.

Verwenden von Inlinedelegaten

Sie können auch den Action<QdrantClientSettings> configureSettings Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. um den API-Schlüssel aus Code festzulegen:

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

Client Gesundheitschecks der Integration

Standardmäßig aktivieren .NET.NET Aspire-Integrationen Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Observabilitybezeichnet werden. Weitere Informationen zur Integrationsobservierbarkeit und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Je nach unterstützendem Dienst unterstützen einige Integrationen möglicherweise nur bestimmte dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefeatures können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Konfiguration dargestellt werden.

Protokollierung

Die .NET Aspire Qdrant-Integration verwendet Standard-.NET-Protokollierung, und Sie sehen Protokolleinträge aus der folgenden Kategorie:

  • Qdrant.Client

Nachverfolgung

Die .NET.NET Aspire Qdrant-Integration gibt derzeit keine Tracing-Aktivitäten aus, da sie von der Qdrant.Client-Bibliothek nicht unterstützt werden.

Metriken

Die .NET.NET Aspire Qdrant-Integration gibt derzeit keine Metriken aus, da sie von der Qdrant.Client-Bibliothek nicht unterstützt werden.

Siehe auch