Udostępnij za pośrednictwem

Integracja .NET.NET Aspire Qdrant

  • Artykuł

obejmuje: integrację hostingu i integrację Client

Qdrant to wyszukiwarka wektorów typu open source, która efektywnie przechowuje, indeksuje i wyszukuje dane wektorów na dużą skalę. Jest on często używany w aplikacjach uczenia maszynowego, sztucznej inteligencji i nauki o danych.

Dane wektorowe kodują informacje jako wektory matematyczne, które są tablicami liczb lub współrzędnych. Systemy uczenia maszynowego i sztucznej inteligencji często używają wektorów do reprezentowania obiektów bez struktury, takich jak obrazy, tekst, dźwięk lub wideo. Każdy wymiar w wektorze opisuje konkretną charakterystykę obiektu. Porównując je, systemy mogą klasyfikować, wyszukiwać i identyfikować klastry obiektów.

Z tego artykułu dowiesz się, jak korzystać z integracji .NET.NET Aspire Qdrant. Integracja .NET.NET Aspire Qdrant umożliwia łączenie się z istniejącymi bazami danych Qdrant lub tworzenie nowych wystąpień za pomocą obrazu kontenera qdrant/qdrant.

Integracja hostingu

Integracja hostingu Qdrant modeluje server jako typ QdrantServerResource. Aby uzyskać dostęp do tego typu i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.Qdrant w projekcie aplikacji hosta .

dotnet add package Aspire.Hosting.Qdrant

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w aplikacjach .NET.

Dodawanie zasobu Qdrant

W projekcie hosta aplikacji wywołaj AddQdrant, aby dodać i zwrócić konstruktor zasobów 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...

Notatka

Kontener Qdrant może być powolny do uruchomienia, dlatego najlepiej użyć trwałego okresu istnienia, aby uniknąć niepotrzebnych ponownych uruchomień. Aby uzyskać więcej informacji, zobacz cykl życia zasobu kontenera.

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem qdrant/qdrant, tworzy nowe wystąpienie usługi Qdrant na komputerze lokalnym. Zasób jest nazwany qdrant, a następnie jest dodawany do ExampleProject.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie qdrant.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym Qdrantem server, wywołaj AddConnectionString zamiast. Aby uzyskać więcej informacji, zobacz Dokumentacja istniejących zasobów.

Napiwek

Obraz kontenera qdrant/qdrant zawiera internetowy interfejs użytkownika, którego można użyć do eksplorowania wektorów i administrowania bazą danych. Aby uzyskać dostęp do tego narzędzia, uruchom rozwiązanie .NET Aspire, a następnie na pulpicie nawigacyjnym .NET Aspire wybierz punkt końcowy zasobu Qdrant. Na pasku adresu przeglądarki dołącz /dashboard i naciśnij Enter.

Obsługa kluczy interfejsu API i przekazywanie innych parametrów dla zasobu Qdrant

Aby nawiązać połączenie z usługą Qdrant, client musi przekazać odpowiedni klucz interfejsu API. W powyższym kodzie, kiedy .NET.NET Aspire dodaje zasób Qdrant do rozwiązania, ustawia klucz API na losowy ciąg znaków. Jeśli zamiast tego chcesz użyć określonego klucza interfejsu API, możesz przekazać go jako parametr apiKey:

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

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

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

Qdrant obsługuje domyślne klucze API bazujące na konfiguracji poprzez użycie zmiennej środowiskowej QDRANT__SERVICE__API_KEY.

Powyższy kod pobiera parametr do przekazania do interfejsu API AddQdrant i wewnętrznie przypisuje parametr do zmiennej środowiskowej QDRANT__SERVICE__API_KEY kontenera Qdrant. Parametr apiKey jest zwykle określany jako klucz tajny użytkownika:

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

Aby uzyskać więcej informacji, zobacz Parametry zewnętrzne.

Dodawanie zasobu Qdrant z woluminem danych

Aby dodać wolumin danych do zasobu Qdrant, wywołaj metodę rozszerzenia 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...

Wolumin danych służy do utrwalania danych Qdrant poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /qdrant/storage w kontenerze Qdrant, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat woluminów danych i szczegółów, dlaczego są preferowane zamiast montowania wiązań, zobacz dokumentację Docker: Woluminy.

Dodaj zasób Qdrant z montowaniem danych

Aby dodać montowanie powiązania danych do zasobu Qdrant, wywołaj metodę 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...

Ważny

Powiązania montowań danych mają ograniczoną funkcjonalność w porównaniu z woluminami , które zapewniają lepszą wydajność, przenośność i bezpieczeństwo, dzięki czemu są bardziej odpowiednie dla środowisk produkcyjnych. Jednak wiążące montowanie umożliwia bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do programowania i testowania wymagających zmian w czasie rzeczywistym.

Powiązania danych opierają się na systemie plików komputera hosta, aby dane Qdrant były utrwalane między ponownymi uruchomieniami kontenera. Instalacja powiązania danych jest instalowana w folderze C:\Qdrant\Data w systemie Windows (lub /Qdrant/Data na Unix) na maszynie hosta w kontenerze Qdrant. Aby uzyskać więcej informacji na temat instalacji powiązań danych, zobacz Docker docs: Bind mounts.

Hostowanie kontroli kondycji integracji

Integracja hostingu Qdrant automatycznie dodaje kontrolę kondycji zasobu Qdrant. Kontrola kondycji sprawdza, czy usługa Qdrant jest uruchomiona i czy można nawiązać z nim połączenie.

integracja Client

Aby rozpocząć pracę z integracją .NET Aspire Qdrant client, zainstaluj 📦Aspire.Qdrant.Client pakiet NuGet w projekcie korzystającym z client, czyli projektu dla aplikacji korzystającej z clientQdrant. Integracja client Qdrant rejestruje Qdrant.Client.QdrantClient wystąpienie, którego można użyć do interakcji z danymi wektorowymi Qdrant.

dotnet add package Aspire.Qdrant.Client

Dodaj Qdrant client

W pliku Program.cs projektu clientużywającego wywołaj metodę rozszerzenia AddQdrantClient na dowolnym IHostApplicationBuilder, aby zarejestrować QdrantClient do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddQdrantClient("qdrant");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu Qdrant w projekcie hosta aplikacji. Innymi słowy podczas wywoływania AddQdrant i podania nazwy qdrant tej samej nazwy należy użyć podczas wywoływania AddQdrantClient. Aby uzyskać więcej informacji, zobacz Dodawanie zasobu Qdrant.

Możesz wtedy uzyskać wystąpienie QdrantClient, używając wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zobacz .NET wstrzykiwanie zależności.

Dodaj Qdrant z kluczami client

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień QdrantClient z różnymi nazwami połączeń. Aby zarejestrować kluczowych klientów Qdrant, wywołaj metodę AddKeyedQdrantClient:

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

Następnie można pobrać wystąpienia QdrantClient przy użyciu wstrzykiwania zależności. Aby na przykład pobrać połączenia z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług kluczowych, zobacz sekcję .NET wstrzykiwanie zależności: usługi kluczowe.

Konfiguracja

Integracja .NET Aspireclient Qdrant udostępnia wiele opcji konfigurowania połączenia z Qdrant na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings można podać nazwę parametrów połączenia podczas wywoływania builder.AddQdrantClient():

builder.AddQdrantClient("qdrant");

Następnie .NET.NET Aspire pobiera parametry połączenia z sekcji konfiguracji ConnectionStrings:

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

Domyślnie QdrantClient używa punktu końcowego API gRPC.

Korzystanie z dostawców konfiguracji

Integracja .NET Aspireclient Qdrant obsługuje Microsoft.Extensions.Configuration. Ładuje QdrantClientSettings z konfiguracji przy użyciu klucza Aspire:Qdrant:Client. Poniżej przedstawiono przykład appsettings.json, który konfiguruje niektóre opcje:

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

Aby zobaczyć pełny schemat integracji client Qdrant JSON, zapoznaj się z Aspire.Qdrant.Client/ConfigurationSchema.json.

Używanie delegatów wbudowanych

Możesz również przekazać delegata Action<QdrantClientSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje bezpośrednio, na przykład w celu ustawienia klucza interfejsu API z poziomu kodu.

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

Client kontroli stanu integracji

Domyślnie .NET.NET Aspire integracje umożliwiają kontrolę kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Wyrąb

Integracja .NET Aspire Qdrant korzysta ze standardowego logowania .NET i zobaczysz wpisy dziennika z następującej kategorii:

  • Qdrant.Client

Śledzenie

Integracja .NET.NET Aspire Qdrant nie emituje obecnie działań śledzenia, ponieważ nie są one obsługiwane przez bibliotekę Qdrant.Client.

Metryki

Integracja .NET.NET Aspire Qdrant nie emituje obecnie metryk, ponieważ nie są one obsługiwane przez bibliotekę Qdrant.Client.

Zobacz też