Qdrant の統合 .NET.NET Aspire

[アーティクル]
01/23/2025

Qdrant は、大規模なベクターデータを効率的に格納、インデックス作成、および検索するオープンソースベクター類似性検索エンジンです。これは、機械学習、人工知能、データサイエンスアプリケーションでよく使用されます。

ベクターデータは、数値または座標の配列である数学的ベクトルとして情報をエンコードします。機械学習と AI システムでは、多くの場合、ベクターを使用して、画像、テキスト、オーディオ、ビデオなどの非構造化オブジェクトを表します。ベクトル内の各次元は、オブジェクトの特定の特性を記述します。それらを比較することで、システムはオブジェクトのクラスターを分類、検索、および識別できます。

この記事では、.NET.NET Aspire Qdrant 統合を使用する方法について説明します。 .NET .NET Aspire Qdrant 統合を使用すると、既存の Qdrant データベースに接続したり、qdrant/qdrant コンテナーイメージをして新しいインスタンスを作成したりできます。

ホスティング統合

Qdrant ホスティング統合は、サーバーを QdrantServerResource の種類としてモデル化します。この種類と API にアクセスするには、📦Aspireを追加します。アプリホストプロジェクト内の Hosting.Qdrant NuGet パッケージ。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Qdrant

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

詳細については、「dotnet パッケージの追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

Qdrant リソースを追加する

アプリホストプロジェクトで、AddQdrant を呼び出して、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...

手記

Qdrant コンテナーの起動に時間がかかる可能性があるため、不要な再起動を避けるために、永続的な の有効期間を使用することをお勧めします。詳細については、「コンテナーリソースの有効期間」を参照してください。

.NET .NET Aspire 前の例に示すように、qdrant/qdrant イメージを使用してコンテナーイメージをアプリホストに追加すると、ローカルコンピューターに新しい Qdrant インスタンスが作成されます。リソースには qdrant という名前が付けられ、ExampleProjectに追加されます。

WithReference メソッドは、ExampleProjectという名前の qdrant で接続を構成します。

ヒント

既存の Qdrant サーバーに接続する場合は、代わりに AddConnectionString を呼び出します。詳細については、「既存のリソースを参照する」を参照してください。

ヒント

qdrant/qdrant コンテナーイメージには、ベクターの探索とデータベースの管理に使用できる Web UI が含まれています。このツールにアクセスするには、.NET Aspire ソリューションを起動し、.NET Aspire ダッシュボードで Qdrant リソースのエンドポイントを選択します。ブラウザーのアドレスバーで、/dashboard を追加し、Enterキーを押します。

API キーの処理と Qdrant リソースの他のパラメーターの渡し

Qdrant に接続するには、クライアントが適切な API キーを渡す必要があります。上記のコードでは、.NET.NET Aspire ソリューションに Qdrant リソースを追加すると、API キーがランダムな文字列に設定されます。代わりに特定の API キーを使用する場合は、apiKey パラメーターとして渡すことができます。

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

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

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

Qdrant では、環境変数 QDRANT__SERVICE__API_KEYを使用して、構成ベースの既定の API キーをサポートしています。

上記のコードは、AddQdrant API に渡すパラメーターを取得し、内部的に Qdrant コンテナーの QDRANT__SERVICE__API_KEY 環境変数にパラメーターを割り当てます。 apiKey パラメーターは、通常、ユーザーシークレットとして指定されます。

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

詳細については、「外部パラメーターを参照してください。

データボリュームを使用して Qdrant リソースを追加する

Qdrant リソースにデータボリュームを追加するには、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...

データボリュームは、コンテナーのライフサイクル外に Qdrant データを保持するために使用されます。データボリュームは Qdrant コンテナーの /qdrant/storage パスにマウントされ、name パラメーターが指定されていない場合、名前はランダムに生成されます。データボリュームの詳細と、マウントのバインド優先される理由の詳細については、「ドキュメント: ボリューム」を参照してください。

データバインドマウントを使用して Qdrant リソースを追加する

Qdrant リソースにデータバインドマウントを追加するには、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...

大事な

データバインドマウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適したボリュームと比較して機能が制限されています。ただし、バインドマウントを使用すると、ホストシステム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データバインドマウントは、ホストマシンのファイルシステムに依存して、コンテナーの再起動の間に Qdrant データを保持します。データバインドマウントは、Qdrant コンテナー内のホストコンピューター上の Windows 上の C:\Qdrant\Data フォルダー (または /Qdrant/Data上の Unix) にマウントされます。データバインドマウントの詳細については、「Docker ドキュメント: バインドマウント」を参照してください。

ホスティング統合の正常性チェック

Qdrant ホスティング統合により、Qdrant リソースの正常性チェックが自動的に追加されます。正常性チェックでは、Qdrant が実行されていること、および Qdrant への接続を確立できることを確認します。

Client 統合

.NET .NET Aspire Qdrant クライアント統合を開始するには、クライアントを使用するプロジェクト、つまり Qdrant クライアントを利用するアプリケーションのプロジェクトに 📦AspireClient の NuGet パッケージをインストールします。 Qdrant クライアント統合は、Qdrant を登録します。Client.QdrantClient、Qdrant ベクターデータとの対話に使用できるインスタンスです。

.NET CLI
PackageReference

dotnet add package Aspire.Qdrant.Client

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

Qdrant クライアントを追加する

クライアントを使用するプロジェクトの Program.cs ファイルで、任意の IHostApplicationBuilder で AddQdrantClient 拡張メソッドを呼び出して、依存関係挿入コンテナーで使用する QdrantClient を登録します。このメソッドは、接続名パラメーターを受け取ります。

builder.AddQdrantClient("qdrant");

ヒント

connectionName パラメーターは、アプリホストプロジェクトに Qdrant リソースを追加するときに使用される名前と一致する必要があります。つまり、AddQdrant を呼び出すとき、qdrant の名前を指定し、その同じ名前を AddQdrantClientを呼び出すときにも使用する必要があります。詳細については、「Qdrant リソースの追加」を参照してください。

その後、依存関係の挿入を使用して QdrantClient インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

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

依存関係の挿入の詳細については、.NET 依存関係の挿入を参照してください。

キー付き Qdrant クライアントを追加する

接続名が異なる複数の QdrantClient インスタンスを登録する場合があります。キー付き Qdrant クライアントを登録するには、AddKeyedQdrantClient メソッドを呼び出します。

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

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

キー付きサービスの詳細については、「.NET 依存関係の挿入: キー付きサービスの」を参照してください。

構成

.NET .NET Aspire Qdrant クライアント統合には、プロジェクトの要件と規則に基づいて Qdrant への接続を構成するための複数のオプションが用意されています。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、builder.AddQdrantClient()を呼び出すときに接続文字列の名前を指定できます。

builder.AddQdrantClient("qdrant");

次 .NET.NET Aspire、ConnectionStrings 構成セクションから接続文字列を取得します。

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

既定では、QdrantClient は gRPC API エンドポイントを使用します。

構成プロバイダーを使用する

.NET .NET Aspire Qdrant クライアント統合では、Microsoft.Extensions.Configurationがサポートされます。 QdrantClientSettings キーを使用して、構成から Aspire:Qdrant:Client を読み込みます。オプションの一部を構成する appsettings.json の例を次に示します。

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

完全な Qdrant クライアント統合 JSON スキーマについては、Aspireを参照してください。Qdrant。Client/ConfigurationSchema.json.

インラインデリゲートを使用する

Action<QdrantClientSettings> configureSettings デリゲートを渡して、コードから API キーを設定するなど、一部またはすべてのオプションをインラインで設定することもできます。

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

Client 統合の正常性チェック

既定では、.NET.NET Aspire 統合により、すべてのサービス正常性チェックが有効になります。詳細については、.NET.NET Aspire 統合の概要を参照してください。

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱とも呼ばれます。統合の可観測性とテレメトリの詳細については、統合の概要参照してください。バッキングサービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.NET Aspire Qdrant 統合では、標準の .NET ログが使用され、次のカテゴリのログエントリが表示されます。

Qdrant.Client

トレーシング

.NET .NET Aspire Qdrant 統合では、Qdrant.Client ライブラリでサポートされていないため、トレースアクティビティは現在出力されません。

メトリック

.NET .NET Aspire Qdrant 統合は、Qdrant.Client ライブラリでサポートされていないため、現在メトリックを出力しません。

次の方法で共有

Qdrant の統合 .NET.NET Aspire

ホスティング統合

Qdrant リソースを追加する

API キーの処理と Qdrant リソースの他のパラメーターの渡し

データボリュームを使用して Qdrant リソースを追加する

データバインドマウントを使用して Qdrant リソースを追加する

ホスティング統合の正常性チェック

Client 統合

Qdrant クライアントを追加する

キー付き Qdrant クライアントを追加する

構成

接続文字列を使用する

構成プロバイダーを使用する

インラインデリゲートを使用する

Client 統合の正常性チェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

次の方法で共有

Qdrant の統合 .NET.NET Aspire

ホスティング統合

Qdrant リソースを追加する

API キーの処理と Qdrant リソースの他のパラメーターの渡し

データ ボリュームを使用して Qdrant リソースを追加する

データ バインド マウントを使用して Qdrant リソースを追加する

ホスティング統合の正常性チェック

Client 統合

Qdrant クライアントを追加する

キー付き Qdrant クライアントを追加する

構成

接続文字列を使用する

構成プロバイダーを使用する

インライン デリゲートを使用する

Client 統合の正常性チェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

データボリュームを使用して Qdrant リソースを追加する

データバインドマウントを使用して Qdrant リソースを追加する

インラインデリゲートを使用する