Partager via

intégration de Qdrant .NET.NET Aspire

  • Article

inclut : l’intégration d’hébergement et l’intégration de Client

Qdrant est un moteur de recherche de similarité de vecteur open source qui stocke, indexe et recherche efficacement des données vectorielles à grande échelle. Il est couramment utilisé dans le Machine Learning, l’intelligence artificielle et les applications de science des données.

Les données vectorielles encodent les informations en tant que vecteurs mathématiques, qui sont des tableaux de nombres ou de coordonnées. Les systèmes Machine Learning et IA utilisent souvent des vecteurs pour représenter des objets non structurés tels que des images, du texte, de l’audio ou de la vidéo. Chaque dimension du vecteur décrit une caractéristique spécifique de l’objet. En les comparant, les systèmes peuvent classifier, rechercher et identifier des clusters d’objets.

Dans cet article, vous allez apprendre à utiliser l’intégration .NET.NET Aspire Qdrant. L’intégration .NET.NET Aspire Qdrant vous permet de vous connecter à des bases de données Qdrant existantes ou de créer de nouvelles instances avec l’image conteneur qdrant/qdrant.

Intégration de l’hébergement

L’hébergement Qdrant modélise le serveur en tant que type QdrantServerResource. Pour accéder à ce type et à ces API, ajoutez le package NuGet 📦Aspire.Hosting.Qdrant dans le projet hôte de l’application.

dotnet add package Aspire.Hosting.Qdrant

Pour plus d'informations, consultez dotnet add package ou Gérer les dépendances de package dans des applications.NET.

Ajouter une ressource Qdrant

Dans votre projet hôte d’application, appelez AddQdrant pour ajouter et retourner un générateur de ressources 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...

Remarque

Le conteneur Qdrant peut être lent à démarrer. Il est donc préférable d’utiliser une durée de vie persistante pour éviter les redémarrages inutiles. Pour plus d’informations, consultez Durée de vie des ressources de conteneur.

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image qdrant/qdrant, elle crée une nouvelle instance Qdrant sur votre ordinateur local. La ressource est nommée qdrant, puis ajoutée au ExampleProject.

La méthode WithReference configure une connexion dans le ExampleProject nommé qdrant.

Pourboire

Si vous préférez vous connecter à un serveur Qdrant existant, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Pourboire

L’image conteneur qdrant/qdrant inclut une interface utilisateur web que vous pouvez utiliser pour explorer vos vecteurs et administrer la base de données. Pour accéder à cet outil, démarrez votre solution .NET Aspire, puis, dans le tableau de bord .NET Aspire, sélectionnez le point de terminaison de la ressource Qdrant. Dans la barre d’adresses de votre navigateur, ajoutez /dashboard et tapez Entrée.

Gestion des clés API et transmission d’autres paramètres pour la ressource Qdrant

Pour vous connecter à Qdrant, un client doit passer la clé API appropriée. Dans le code ci-dessus, lorsque .NET.NET Aspire ajoute une ressource Qdrant à votre solution, elle définit la clé API sur une chaîne aléatoire. Si vous souhaitez utiliser une clé API spécifique à la place, vous pouvez le passer en tant que paramètre apiKey :

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

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

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

Qdrant prend en charge les clés API par défaut basées sur la configuration à l’aide de la variable d’environnement QDRANT__SERVICE__API_KEY.

Le code précédent obtient un paramètre à passer à l’API AddQdrant et affecte en interne le paramètre à la variable d’environnement QDRANT__SERVICE__API_KEY du conteneur Qdrant. Le paramètre apiKey est généralement spécifié en tant que secret utilisateur :

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

Pour plus d’informations, consultez paramètres externes.

Ajouter une ressource Qdrant avec un volume de données

Pour ajouter un volume de données à la ressource Qdrant, appelez la méthode d’extension 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...

Le volume de données est utilisé pour conserver les données Qdrant en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /qdrant/storage dans le conteneur Qdrant et lorsqu’un paramètre name n’est pas fourni, un nom est généré aléatoirement. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés par rapport aux montages de liaison , consultez la documentation Docker : Volumes.

Ajouter une ressource Qdrant avec montage de liaison de données

Pour ajouter un montage de liaison de données à la ressource Qdrant, appelez la méthode 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...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes, qui offrent de meilleures performances, une meilleure portabilité et une sécurité accrue, ce qui les rend plus adaptés aux environnements de production. Toutefois, les montages de liaison autorisent l’accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et les tests où les modifications en temps réel sont nécessaires.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données Qdrant entre les redémarrages de conteneur. Le montage de liaison de données est monté sur le dossier C:\Qdrant\Data sur Windows (ou /Qdrant/Data sur Unix) sur l’ordinateur hôte dans le conteneur Qdrant. Pour plus d’informations sur les montages de liaison de données, consultez les documents Docker : Montages de liaison.

Contrôles de santé de l’intégration des systèmes d’hébergement

L’intégration de l’hébergement Qdrant ajoute automatiquement un contrôle d’intégrité pour la ressource Qdrant. Le contrôle d'intégrité vérifie que Qdrant fonctionne et qu'une connexion peut être établie à celle-ci.

intégration Client

Pour commencer à utiliser l'intégration du client Qdrant .NET.NET Aspire, installez le package NuGet 📦Aspire.Qdrant.Client dans le projet consommant le client, c'est-à-dire le projet pour l'application qui utilise le client Qdrant. L’intégration du client Qdrant inscrit une instance Qdrant.Client.QdrantClient que vous pouvez utiliser pour interagir avec les données vectorielles Qdrant.

dotnet add package Aspire.Qdrant.Client

Ajouter un client Qdrant

Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddQdrantClient sur n’importe quelle IHostApplicationBuilder pour inscrire un QdrantClient à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddQdrantClient("qdrant");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource Qdrant dans le projet hôte d’application. En d’autres termes, lorsque vous appelez AddQdrant et fournissez un nom de qdrant ce même nom doit être utilisé lors de l’appel de AddQdrantClient. Pour plus d’informations, consultez Ajouter une ressource Qdrant.

Vous pouvez ensuite récupérer l’instance QdrantClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

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

Pour plus d’informations sur l’injection de dépendances, consultez .NET l’injection de dépendances.

Ajouter un client Qdrant configuré par clé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de QdrantClient avec différents noms de connexion. Pour enregistrer les clients Qdrant avec clés, appelez la méthode AddKeyedQdrantClient :

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

Vous pouvez ensuite récupérer les instances QdrantClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer les connexions à partir d’un exemple de service :

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

Pour plus d’informations sur les services à clé, consultez .NET injection de dépendances : services à clé.

Configuration

L’intégration du client Qdrant .NET.NET Aspire fournit plusieurs options pour configurer la connexion à Qdrant en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de builder.AddQdrantClient():

builder.AddQdrantClient("qdrant");

Ensuite, .NET.NET Aspire récupère la chaîne de connexion à partir de la section de configuration ConnectionStrings :

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

Par défaut, le QdrantClient utilise le point de terminaison de l’API gRPC.

Utiliser des fournisseurs de configuration

L’intégration du client .NET.NET Aspire de Qdrant prend en charge Microsoft.Extensions.Configuration. Il charge le QdrantClientSettings à partir de la configuration en utilisant la clé Aspire:Qdrant:Client. Voici un exemple de appsettings.json qui configure certaines des options suivantes :

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

Pour connaître le schéma complet de l’intégration du client Qdrant JSON, consultez Aspire. Qdrant.Client/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<QdrantClientSettings> configureSettings pour configurer certaines ou toutes les options inline, par exemple pour définir la clé API à partir du code :

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

Client vérifications de santé de l'intégration

Par défaut, les intégrations .NET.NET Aspire activent les contrôles de santé des services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration .NET Aspire Qdrant utilise la journalisation standard .NET, et vous verrez des entrées dans la catégorie suivante :

  • Qdrant.Client

Traçage

L’intégration .NET.NET Aspire Qdrant n’émet actuellement pas d’activités de suivi, car elles ne sont pas prises en charge par la bibliothèque Qdrant.Client.

Métriques

L’intégration .NET.NET Aspire Qdrant n’émet actuellement pas de métriques, car elles ne sont pas prises en charge par la bibliothèque Qdrant.Client.

Voir aussi