Integracja .NET.NET Aspire Qdrant

obejmuje: integracja hostingu oraz integracja 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 hostowania Qdrant modeluje serwer jako typ QdrantServerResource. Aby uzyskać dostęp do tego typu i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.Qdrant w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.Qdrant

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

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

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.

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

Aby nawiązać połączenie z usługą Qdrant, klient musi przekazać odpowiedni klucz interfejsu API. W powyższym kodzie, gdy .NET.NET Aspire dodaje zasób Qdrant do rozwiązania, ustawia klucz API na losowo wygenerowany 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 punktów wiązania, 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...

Powiązania danych opierają się na systemie plików komputera hosta, aby dane Qdrant były utrwalane między ponownymi uruchomieniami kontenera. Powiązanie danych jest zamontowane 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 bindowania danych, zobacz Docker dokumentację: Bind mounts.

Sprawdzanie kondycji integracji hostingu

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ą klienta .NET.NET Aspire Qdrant, zainstaluj 📦Aspire. Qdrant.Client pakiet NuGet w projekcie korzystającym z klienta, czyli projekt dla aplikacji korzystającej z klienta Qdrant. Integracja klienta Qdrant rejestruje instancję Qdrant.Client.QdrantClient, której można użyć do interakcji z danymi wektorowymi Qdrant.

dotnet add package Aspire.Qdrant.Client

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

Dodawanie klienta Qdrant

W pliku Program.cs projektu korzystającego z klienta 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");

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.

Dodawanie klienta Qdrant z kluczem

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 przy użyciu wstrzykiwania zależności pobrać wystąpienia QdrantClient. 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 klienta .NET.NET Aspire Qdrant udostępnia wiele opcji konfigurowania połączenia z usługą 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 klienta .NET.NET Aspire Qdrant obsługuje Microsoft.Extensions.Configuration. Ładuje QdrantClientSettings z konfiguracji za pomocą 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 uzyskać pełny schemat integracji klienta Qdrant JSON, zobacz Aspire. Qdrant.Client/ConfigurationSchema.json.

Użyj delegatów w linii

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ę stanu zdrowia 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 .

Logowanie

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 aktualnie nie emituje 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ż

• Qdrant
• dokumentacja Qdrant
• Qdrant GitHub repozytorium
• Qdrant SDK
• .NET .NET Aspire integracje
• .NET Aspire GitHubrepozytorium