.NET .NET Aspire Integrering av Qdrant

Artikel
01/18/2025

omfattar:Hosting-integration och Client integration

Qdrant är en sökmotor för vektorlikhet med öppen källkod som effektivt lagrar, indexerar och söker efter storskaliga vektordata. Det används ofta i maskininlärning, artificiell intelligens och datavetenskapsprogram.

Vektordata kodar information som matematiska vektorer, som är matriser med tal eller koordinater. Maskininlärnings- och AI-system använder ofta vektorer för att representera ostrukturerade objekt som bilder, text, ljud eller video. Varje dimension i vektorn beskriver en specifik egenskap hos objektet. Genom att jämföra dem kan system klassificera, söka efter och identifiera kluster av objekt.

I den här artikeln får du lära dig hur du använder .NET.NET Aspire Qdrant-integrering. Med .NET.NET Aspire Qdrant-integrering kan du ansluta till befintliga Qdrant-databaser eller skapa nya instanser med qdrant/qdrant containeravbildningen.

Värdintegrering

Qdrant-värdintegrering modellerar server som den QdrantServerResource typen. Om du vill komma åt den här typen och API:er lägger du till 📦Aspire.Hosting.Qdrant NuGet-paket i appvärdprojektet.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Qdrant

<PackageReference Include="Aspire.Hosting.Qdrant"
                  Version="*" />

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET-applikationer.

Lägg till Qdrant-resurs

I appvärdprojektet anropar du AddQdrant för att lägga till och returnera en Qdrant-resursbyggare.

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

Not

Qdrant-containern kan vara långsam att starta, så det är bäst att använda en beständig livslängd för att undvika onödiga omstarter. Mer information finns i Containerresursens livslängd.

När .NET.NET Aspire lägger till en containeravbildning till appvärden, som visas i föregående exempel med qdrant/qdrant avbildningen, skapar den en ny Qdrant-instans på den lokala datorn. Resursen heter qdrant och läggs sedan till i ExampleProject.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet qdrant.

Tips

Om du hellre vill ansluta till en befintlig Qdrant-serveranropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Tips

Den qdrant/qdrant containeravbildningen innehåller ett webbgränssnitt som du kan använda för att utforska dina vektorer och administrera databasen. Om du vill komma åt det här verktyget startar du din .NET Aspire-lösning och väljer sedan slutpunkten för Qdrant-resursen i .NET Aspire instrumentpanel. I webbläsarens adressfält lägger du till /instrumentpanelen och trycker på Retur.

Hantera API-nycklar och skicka andra parametrar för Qdrant-resursen

Om du vill ansluta till Qdrant måste en client skicka rätt API-nyckel. När .NET.NET Aspire lägger till en Qdrant-resurs i din lösning i koden ovan, anger den API-nyckeln till en slumpmässig sträng. Om du vill använda en specifik API-nyckel i stället kan du skicka den som en apiKey parameter:

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

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

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

Qdrant stöder konfigurationsbaserade standard-API-nycklar med hjälp av miljövariabeln QDRANT__SERVICE__API_KEY.

Föregående kod hämtar en parameter för att skicka till AddQdrant-API:et och tilldelar internt parametern till QDRANT__SERVICE__API_KEY miljövariabeln för Qdrant-containern. Parametern apiKey anges vanligtvis som en användarhemlighet:

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

Mer information finns i externa parametrar.

Lägga till Qdrant-resurs med datavolym

Om du vill lägga till en datavolym i Qdrant-resursen anropar du metoden WithDataVolume-tillägg:

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

Datavolymen används för att bevara Qdrant-data utanför livscykeln för containern. Datamängden monteras på sökvägen /qdrant/storage i Qdrant-containern och när en name-parameter inte anges genereras namnet slumpmässigt. För mer information om datavolymer och varför de föredras framför bindningsmonteringar , se dokumentationen Docker: Volymer.

Lägg till Qdrant-resurs med databindningsmontering

Om du vill lägga till en databindningsmontering till Qdrant-resursen anropar du metoden 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...

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Databindningar förlitar sig på värdmaskinens filsystem för att bevara Qdrant-data vid omstart av container. Databindningsmonteringen monteras i mappen C:\Qdrant\Data i Windows (eller /Qdrant/Data på Unix) på värddatorn i Qdrant-containern. För mer information om databindningar, se Docker dokumentation: Bindmonteringar.

Värd för hälsokontroller för integrering

Integrering av värdtjänst med Qdrant lägger automatiskt till en hälsokontroll för Qdrant-resursen. Hälsokontrollen verifierar att Qdrant körs och att en anslutning kan upprättas till den.

Client integration

Kom igång med .NET Aspire Qdrant-client-integrering genom att installera 📦Aspire.Qdrant.Client NuGet-paketet i det client-konsumerande projektet, dvs. projektet för programmet som använder Qdrant-client. Qdrant-client-integreringen registrerar en Qdrant.Client. QdrantClient instans som du kan använda för att interagera med Qdrant-vektordata.

.NET CLI
PackageReference

dotnet add package Aspire.Qdrant.Client

<PackageReference Include="Aspire.Qdrant.Client"
                  Version="*" />

Lägg till Qdrant client

I Program.cs-filen för ditt client-konsumerande projekt anropar du AddQdrantClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en QdrantClient för användning via containern för beroendeinjektion. Metoden tar en parameter för anslutningsnamn.

builder.AddQdrantClient("qdrant");

Tips

Parametern connectionName måste matcha namnet som användes när du lägger till Qdrant-resursen i appvärdprojektet. Med andra ord, när du anropar AddQdrant och anger ett namn på qdrant ska samma namn användas när du anropar AddQdrantClient. För mer information, se Lägg till Qdrant-resurs.

Du kan sedan hämta QdrantClient-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till kodad Qdrant client

Det kan finnas situationer där du vill registrera flera QdrantClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade Qdrant-klienter anropar du metoden AddKeyedQdrantClient:

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

Sedan kan du hämta QdrantClient-instanser med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningarna från en exempeltjänst:

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

Mer information om nyckelade tjänster finns i .NET beroendeinmatning: Nyckelade tjänster.

Konfiguration

Integreringen .NET Aspire Qdrant client innehåller flera alternativ för att konfigurera anslutningen till Qdrant baserat på kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar builder.AddQdrantClient():

builder.AddQdrantClient("qdrant");

Sedan hämtar .NET.NET Aspire anslutningssträngen från avsnittet ConnectionStrings konfiguration:

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

Som standard använder QdrantClient gRPC API-slutpunkten.

Använda konfigurationsprovidrar

Integrationen .NET Aspire Qdrant client stöder Microsoft.Extensions.Configuration. Den läser in QdrantClientSettings från konfigurationen med hjälp av Aspire:Qdrant:Client-nyckeln. Följande är ett exempel på en appsettings.json som konfigurerar några av alternativen:

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

Det fullständiga schemat för Qdrant-client-JSON-integration finns i Aspire. Qdrant.Client/ConfigurationSchema.json.

Använd inline-delegater

Du kan också skicka Action<QdrantClientSettings> configureSettings delegering för att konfigurera några eller alla alternativ direkt, till exempel för att ange API-nyckeln i koden.

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

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire Qdrant-integreringen använder standardloggning .NET och du kommer att se loggningar från följande kategori:

Qdrant.Client

Spårning

Den .NET.NET Aspire Qdrant-integreringen genererar för närvarande inte spårningsaktiviteter eftersom de inte stöds av Qdrant.Client-biblioteket.

Mått

Den .NET.NET Aspire Qdrant-integreringen genererar för närvarande inte mått eftersom de inte stöds av Qdrant.Client-biblioteket.

Dela via

.NET .NET Aspire Integrering av Qdrant

Värdintegrering

Lägg till Qdrant-resurs

Hantera API-nycklar och skicka andra parametrar för Qdrant-resursen

Lägga till Qdrant-resurs med datavolym

Lägg till Qdrant-resurs med databindningsmontering

Värd för hälsokontroller för integrering

Client integration

Lägg till Qdrant client

Lägg till kodad Qdrant client

Konfiguration

Använda en anslutningssträng

Använda konfigurationsprovidrar

Använd inline-delegater

Client hälsokontroller för integrering

Observerbarhet och telemetri

Skogsavverkning

Spårning

Mått

Se även

Ytterligare resurser