Integrace .NET.NET Aspire Qdrant

Článek
03/09/2025

zahrnuje: integraci hostování a Client integraci

Qdrant je opensourcový vyhledávací modul pro vektorové podobnosti, který efektivně ukládá, indexuje a prohledává rozsáhlá vektorová data. Běžně se používá v aplikacích strojového učení, umělé inteligence a datových věd.

Vektorová data kódují informace jako matematické vektory, což jsou pole čísel nebo souřadnic. Systémy strojového učení a umělé inteligence často používají vektory k reprezentaci nestrukturovaných objektů, jako jsou obrázky, text, zvuk nebo video. Každá dimenze vektoru popisuje specifickou charakteristiku objektu. Díky jejich porovnání můžou systémy klasifikovat, vyhledávat a identifikovat clustery objektů.

V tomto článku se dozvíte, jak používat integraci .NET.NET Aspire Qdrant. Integrace .NET.NET Aspire Qdrant umožňuje připojit se k existujícím databázím Qdrant nebo vytvořit nové instance s qdrant/qdrant obrazem kontejneru.

Integrace hostování

Integrace hostování Qdrant modeluje server jako typ QdrantServerResource. Pokud chcete získat přístup k tomuto typu a rozhraním API, přidejte balíček NuGet 📦Aspire.Hosting.Qdrant do projektu hostování aplikace .

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.Qdrant

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

Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v aplikacích .NET.

Přidejte prostředek Qdrant

V projektu hostitele aplikace zavolejte AddQdrant, abyste přidali a vrátili nástroj pro tvorbu prostředků 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...

Poznámka

Kontejner Qdrant může být pomalý, takže je nejlepší použít trvalou dobu životnosti, abyste se vyhnuli zbytečným restartům. Další informace najdete v části Životnost prostředků kontejneru.

Když .NET.NET Aspire přidá do hostitele aplikace obraz kontejneru, jak je znázorněno v předchozím příkladu s obrazem qdrant/qdrant, vytvoří to novou instanci Qdrantu na vašem místním počítači. Prostředek je pojmenován qdrant a poté přidán do ExampleProject.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem qdrant.

Tip

Pokud byste se raději připojili k existujícímu serveru Qdrant, volejte místo toho AddConnectionString. Další informace naleznete v tématu Odkaz na existující prostředky.

Spropitné

Image kontejneru qdrant/qdrant obsahuje webové uživatelské rozhraní, které můžete použít k prozkoumání vektorů a správě databáze. Pokud chcete získat přístup k tomuto nástroji, spusťte řešení .NET Aspire a potom na řídicím panelu .NET Aspire vyberte koncový bod prostředku Qdrant. V adresní řádku prohlížeče připojte /dashboard a stiskněte Enter.

Zpracování klíčů rozhraní API a předávání dalších parametrů pro prostředek Qdrant

Pokud se chcete připojit ke Qdrantu, musí klient předat správný klíč rozhraní API. Když ve výše uvedeném kódu .NET.NET Aspire přidá do vašeho řešení prostředek Qdrant, nastaví klíč rozhraní API na náhodný řetězec. Pokud chcete místo toho použít konkrétní klíč rozhraní API, můžete ho předat jako parametr apiKey:

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

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

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

Qdrant podporuje nastavení výchozích klíčů API na základě konfigurace pomocí proměnné prostředí QDRANT__SERVICE__API_KEY.

Předchozí kód získá parametr, který se předá rozhraní API AddQdrant, a interně přiřadí tento parametr proměnné prostředí QDRANT__SERVICE__API_KEY v kontejneru Qdrant. Parametr apiKey je obvykle určen jako tajný kód uživatele:

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

Další informace naleznete v tématu Externí parametry.

Přidejte zdroj Qdrant s datovým svazkem

Pokud chcete přidat datový objem do zdroje Qdrant, zavolejte rozšiřující metodu 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...

Objem dat se používá k uchování dat Qdrant mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /qdrant/storage v kontejneru Qdrant a pokud není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnostech o tom, proč se upřednostňují před bind mounts, najdete v Docker dokumentaci: Svazky.

Přidejte prostředek Qdrant s připojením pro vazbu dat

Pokud chcete k prostředku Qdrant přidat datovou vazbu, zavolejte metodu 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...

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Bind mounty umožňují přímý přístup a úpravy souborů na hostiteli, což je ideální pro vývoj a testování, kde jsou potřeba změny v reálném čase.

Datová přiřazení využívají systém souborů hostitelského počítače k zachování dat Qdrant při restartu kontejneru. Připojení datového úložiště je namontováno ve složce C:\Qdrant\Data ve Windows (nebo ve složce /Qdrant/Data na Unix) na hostitelském počítači v kontejneru Qdrant. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Hostování kontrol stavu integrace

Integrace hostování Qdrant automaticky přidává kontrolu stavu pro prostředek Qdrant. Kontrola stavu ověřuje, že je Qdrant spuštěný a že se k němu dá navázat připojení.

Client integrace

Pokud chcete začít s integrací klienta .NET.NET Aspire Qdrant, nainstalujte balíček NuGet 📦Aspire.Qdrant.Client v projektu spotřebovávajícího klienta, tj. projektu aplikace, která využívá klienta Qdrant. Integrace klienta Qdrant zaregistruje Qdrant.Client. QdrantClient instanci, kterou můžete použít k interakci s daty vektoru Qdrant.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Qdrant.Client

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

Přidání klienta Qdrant

V souboru Program.cs projektu, který využívá klienta, zavolejte rozšiřující metodu AddQdrantClient na libovolné IHostApplicationBuilder a zaregistrujte QdrantClient pro použití prostřednictvím kontejneru pro vkládání závislostí. Metoda přebírá parametr názvu připojení.

builder.AddQdrantClient("qdrant");

Rada

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Qdrant do hostitelského projektu aplikace. Jinými slovy, když voláte AddQdrant a zadáte název qdrant, ten samý název by měl být použit při volání AddQdrantClient. Další informace najdete v části Přidat prostředek Qdrant.

Poté můžete načíst instanci QdrantClient pomocí injektování závislostí. Například pro načtení připojení z ukázkové služby:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání klienta Qdrantu s klíči

Mohou nastat situace, kdy chcete zaregistrovat více instancí QdrantClient s různými názvy připojení. Pokud chcete zaregistrovat klienty Qdrantu s klíči, zavolejte metodu AddKeyedQdrantClient:

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

Pak můžete instance QdrantClient načíst pomocí injektování závislostí. Chcete-li například získat spojení z ukázkové služby:

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

Další informace o klíčovaných službách najdete v tématu .NET injektování závislostí: Klíčované služby.

Konfigurace

Integrace klienta .NET.NET Aspire Qdrant nabízí několik možností konfigurace připojení k Qdrantu na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání builder.AddQdrantClient()zadat název připojovacího řetězce:

builder.AddQdrantClient("qdrant");

Potom .NET.NET Aspire načte připojovací řetězec z konfigurační sekce ConnectionStrings.

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

Ve výchozím nastavení QdrantClient používá koncový bod rozhraní API gRPC.

Použití zprostředkovatelů konfigurace

Integrace klienta .NET.NET Aspire Qdrant podporuje Microsoft.Extensions.Configuration. Načte QdrantClientSettings z konfigurace pomocí klíče Aspire:Qdrant:Client. Následuje příklad appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace klienta Qdrant JSON viz Aspire. Qdrant.Client/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<QdrantClientSettings> configureSettings pro nastavení některých nebo všech možností přímo, například nastavit klíč rozhraní API přímo v kódu.

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

Client kontroly stavu integrace

Integrace .NET.NET Aspire umožňují ve výchozím nastavení kontroly stavu pro všechny služby. Další informace naleznete v tématu o přehledu integrací .NET.NET Aspire.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace pro protokolování, trasování a metriky, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET Aspire Qdrant používá standardní protokolování .NET a uvidíte položky protokolu z následující kategorie:

Qdrant.Client

Trasování

Integrace .NET.NET Aspire Qdrant v současné době negeneruje aktivity trasování, protože je knihovna Qdrant.Client nepodporuje.

Metriky

Integrace .NET.NET Aspire Qdrant v současné době negeneruje metriky, protože je knihovna Qdrant.Client nepodporuje.

Sdílet prostřednictvím