Delen via

.NET .NET Aspire Qdrant-integratie

  • Artikel

omvat:hosting-integratie en Client integratie

Qdrant- is een opensource vector similarity zoekmachine waarmee grootschalige vectorgegevens efficiënt worden opgeslagen, geïndexeerd en doorzocht. Het wordt vaak gebruikt in toepassingen voor machine learning, kunstmatige intelligentie en data science.

Vectorgegevens codeert informatie als wiskundige vectoren, die matrices van getallen of coördinaten zijn. Machine learning- en AI-systemen gebruiken vaak vectoren om ongestructureerde objecten weer te geven, zoals afbeeldingen, tekst, audio of video. Elke dimensie in de vector beschrijft een specifiek kenmerk van het object. Door ze te vergelijken, kunnen systemen clusters van objecten classificeren, doorzoeken en identificeren.

In dit artikel leert u hoe u de .NET.NET Aspire Qdrant-integratie gebruikt. Met de .NET.NET Aspire Qdrant-integratie wordt het mogelijk om verbinding te maken met al bestaande Qdrant-databases of om nieuwe instanties te maken met de qdrant/qdrant containerimage.

Hostingintegratie

De Qdrant-hostingintegratie modelleerde de server als het QdrantServerResource type. Als u toegang wilt krijgen tot dit type en deze API's, voegt u het 📦Aspire.Hosting.Qdrant NuGet-pakket toe in het app-hostproject.

dotnet add package Aspire.Hosting.Qdrant

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Qdrant-resource toevoegen

Roep in uw app-hostproject AddQdrant aan om een Qdrant-resourcebouwer toe te voegen en te retourneren.

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

Notitie

De Qdrant-container kan traag zijn om op te starten, dus is het het beste om een permanente levensduur te gebruiken om onnodige herstarts te voorkomen. Zie Levensduur van containerresourcesvoor meer informatie.

Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de qdrant/qdrant-installatiekopie, wordt er een nieuw Qdrant-exemplaar op uw lokale computer gemaakt. De resource heet qdrant en wordt vervolgens toegevoegd aan de ExampleProject.

De methode WithReference configureert een verbinding in de ExampleProject met de naam qdrant.

Tip

Als u liever verbinding wilt maken met een bestaande Qdrant-server, roept u in plaats daarvan AddConnectionString aan. Zie Bestaande bronnenvoor meer informatie.

Tip

De qdrant/qdrant containerinstallatiekopieën bevatten een webgebruikersinterface die u kunt gebruiken om uw vectoren te verkennen en de database te beheren. Als u toegang wilt krijgen tot dit hulpprogramma, start u uw .NET Aspire-oplossing en selecteert u vervolgens in het .NET Aspire dashboard het eindpunt voor de Qdrant-resource. Voeg in de adresbalk van uw browser /dashboard toe en druk op Enter-.

API-sleutels verwerken en andere parameters doorgeven voor de Qdrant-resource

Als u verbinding wilt maken met Qdrant, moet een client de juiste API-sleutel doorgeven. Wanneer in de bovenstaande code .NET.NET Aspire een Qdrant-resource aan uw oplossing toevoegt, wordt de API-sleutel ingesteld op een willekeurige tekenreeks. Als u in plaats daarvan een specifieke API-sleutel wilt gebruiken, kunt u deze doorgeven als een apiKey parameter:

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

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

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

Qdrant ondersteunt op configuratie gebaseerde standaard-API-sleutels met behulp van de omgevingsvariabele QDRANT__SERVICE__API_KEY.

Met de voorgaande code wordt een parameter opgehaald die moet worden doorgegeven aan de AddQdrant-API en wordt de parameter intern toegewezen aan de omgevingsvariabele QDRANT__SERVICE__API_KEY van de Qdrant-container. De parameter apiKey wordt meestal opgegeven als een gebruikersgeheim:

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

Zie Externe parametersvoor meer informatie.

Qdrant-resource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de Qdrant-resource, roept u de WithDataVolume-extensiemethode aan:

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

Het gegevensvolume wordt gebruikt om de Qdrant-gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /qdrant/storage pad in de Qdrant-container en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Voor meer informatie over gegevensvolumes en waarom ze de voorkeur krijgen boven bind mounts, zie Docker docs: Volumes.

Qdrant-resource toevoegen met koppeling voor gegevensbinding

Als u een koppeling voor gegevensbinding wilt toevoegen aan de Qdrant-resource, roept u de WithDataBindMount methode aan:

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

Belangrijk

Gegevens koppelen beperkte functionaliteit hebben in vergelijking met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind-mounts bieden echter directe toegang tot en wijziging van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waarbij realtime veranderingen nodig zijn.

Data-bindingskoppelingen zijn afhankelijk van het bestandssysteem van de hostcomputer om de Qdrant-gegevens te behouden bij het opnieuw opstarten van de container. De koppeling voor gegevensbinding wordt gekoppeld aan de map C:\Qdrant\Data in Windows (of /Qdrant/Data op Unix) op de hostcomputer in de Qdrant-container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

Gezondheidscontroles voor hostingintegratie

De integratie van Qdrant-hosting voegt automatisch een statuscontrole toe voor de Qdrant-resource. De gezondheidscontrole verifieert of Qdrant draait en of er een verbinding mee kan worden gemaakt.

integratie van Client

Installeer de 📦Aspireom aan de slag te gaan met de .NET.NET Aspire Qdrant-clientintegratie. Qdrant.Client NuGet-pakket in het clientgebruikte project, dat wil gezegd het project voor de toepassing die gebruikmaakt van de Qdrant-client. De Qdrant-clientintegratie registreert een Qdrant.Client. QdrantClient exemplaar dat u kunt gebruiken om te communiceren met Qdrant-vectorgegevens.

dotnet add package Aspire.Qdrant.Client

Een Qdrant-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddQdrantClient-extensiemethode aan op elke IHostApplicationBuilder om een QdrantClient te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddQdrantClient("qdrant");

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Qdrant-resource in het app-hostproject. Met andere woorden, wanneer u AddQdrant aanroept en een naam opgeeft van qdrant diezelfde naam moet worden gebruikt bij het aanroepen van AddQdrantClient. Zie Qdrant-resource toevoegenvoor meer informatie.

Vervolgens kunt u het QdrantClient exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Keyed Qdrant-client toevoegen

Er kunnen situaties zijn waarin u meerdere QdrantClient exemplaren met verschillende verbindingsnamen wilt registreren. Als u "keyed Qdrant-clients" wilt registreren, roept u de methode AddKeyedQdrantClient aan:

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

Vervolgens kunt u de QdrantClient exemplaren ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbindingen van een voorbeeldservice wilt ophalen:

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

Voor meer informatie over keyed services, zie .NET afhankelijkheidsinjectie: Keyed Services.

Configuratie

De .NET.NET Aspire Qdrant-clientintegratie biedt meerdere opties voor het configureren van de verbinding met Qdrant op basis van de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van builder.AddQdrantClient():

builder.AddQdrantClient("qdrant");

Vervolgens haalt .NET.NET Aspire de verbindingsreeks op uit de sectie ConnectionStrings configuratie:

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

De QdrantClient maakt standaard gebruik van het gRPC API-eindpunt.

Configuratieproviders gebruiken

De .NET.NET Aspire Qdrant-clientintegratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de QdrantClientSettings vanuit de configuratie met behulp van de Aspire:Qdrant:Client-sleutel. Hier volgt een voorbeeld van een appsettings.json waarmee een aantal van de opties wordt geconfigureerd:

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

Zie Aspirevoor het volledige Qdrant-clientintegratieschema JSON. Qdrant.Client/ConfigurationSchema.json.

Inline-afgevaardigden gebruiken

U kunt de Action<QdrantClientSettings> configureSettings delegate ook doorgeven om bepaalde of alle opties inline in te stellen, bijvoorbeeld om de API-sleutel in de code in te stellen.

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

statuscontroles voor Client integratie

Standaard maken .NET.NET Aspire integraties voor alle services statuscontroles mogelijk. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch logging-, tracing- en metriekenconfiguraties in, die soms worden genoemd als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De .NET Aspire Qdrant-integratie maakt gebruik van standaard .NET logboekregistratie en u ziet logboekvermeldingen uit de volgende categorieën:

  • Qdrant.Client

Tracering

De .NET.NET Aspire Qdrant-integratie verzendt momenteel geen traceringsactiviteiten omdat deze niet worden ondersteund door de Qdrant.Client-bibliotheek.

Statistieken

De .NET.NET Aspire Qdrant-integratie verzendt momenteel geen metrische gegevens omdat deze niet worden ondersteund door de Qdrant.Client-bibliotheek.

Zie ook