.NET .NET Aspire Integrering av Qdrant

Artikel
03/09/2025

omfattar: Hostingintegration 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 servern som QdrantServerResource-typ. 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 värdprojektet för appen 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 containerbild till applikationsvärden, vilket visas i föregående exempel med qdrant/qdrant-bilden, skapar det en ny Qdrant-instans på din lokala dator. 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-server anropar 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

För att ansluta till Qdrant måste en klient 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 bind mounts har begränsade funktioner jämfört med volymer, som ger bättre prestanda, portabilitet och säkerhet, därför är de 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.

Genomförande av hälsokontroller för integration

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.NET Aspire Qdrant-klientintegrering genom att installera 📦Aspire. Qdrant.Client NuGet-paket i det klientkrävande projektet, dvs. projektet för programmet som använder Qdrant-klienten. Qdrant-klientintegrering 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ägga till en Qdrant-klient

I den Program.cs filen för ditt klientkrävande projekt anropar du AddQdrantClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en QdrantClient för användning via containern för beroendeinmatning. 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 nyckelad Qdrant-klient

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 genom att använda 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

.NET .NET Aspire Qdrant-klientintegrering 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

.NET .NET Aspire Qdrant-klientintegrering 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 Qdrant-klientintegreringsschemat JSON 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

Genomförande av hälsokontroller för integration

Client integration

Lägga till en Qdrant-klient

Lägg till nyckelad Qdrant-klient

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