Qdrant コネクタの使用 (プレビュー)

[アーティクル]
11/03/2024

警告

セマンティックカーネルベクターストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

概要

Qdrant Vector Store コネクタを使用すると、Qdrant 内のデータにアクセスして管理できます。コネクタには次の特性があります。

機能領域	サポート
コレクションのマップ	フィルター可能なデータフィールドのペイロードインデックスを使用した Qdrant コレクション
サポートされているキープロパティの種類	ulong GUID
サポートされているデータプロパティ型	string INT long 倍精度浮動小数点 float [bool] これらの各型の列挙可能な値
サポートされているベクタープロパティ型	ReadOnlyMemory<float>
サポートされているインデックスの種類	Hnsw
サポートされている距離関数	CosineSimilarity DotProductSimilarity EuclideanDistance ManhattanDistance
サポートされているフィルター句	AnyTagEqualTo EqualTo
レコード内の複数のベクターをサポートします	はい (構成可能)
IsFilterable がサポートされていますか?	はい
IsFullTextSearchable がサポートされていますか?	はい
StoragePropertyName がサポートされていますか?	はい

作業の開始

Qdrant Vector Store コネクタ NuGet パッケージをプロジェクトに追加します。

dotnet add package Microsoft.SemanticKernel.Connectors.Qdrant --prerelease

セマンティックカーネルによって提供される拡張メソッドを使用して、 KernelBuilder で使用できる依存関係挿入コンテナーまたは IServiceCollection 依存関係挿入コンテナーにベクターストアを追加できます。

using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddQdrantVectorStore("localhost");

using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddQdrantVectorStore("localhost");

パラメーターを受け取たない拡張メソッドも提供されます。これらには、 Qdrant.Client.QdrantClient クラスのインスタンスを依存関係挿入コンテナーに個別に登録する必要があります。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Qdrant.Client;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<QdrantClient>(sp => new QdrantClient("localhost"));
kernelBuilder.AddQdrantVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Qdrant.Client;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<QdrantClient>(sp => new QdrantClient("localhost"));
builder.Services.AddQdrantVectorStore();

Qdrant Vector Store インスタンスを直接構築できます。

using Microsoft.SemanticKernel.Connectors.Qdrant;
using Qdrant.Client;

var vectorStore = new QdrantVectorStore(new QdrantClient("localhost"));

名前付きコレクションへの直接参照を構築できます。

using Microsoft.SemanticKernel.Connectors.Qdrant;
using Qdrant.Client;

var collection = new QdrantVectorStoreRecordCollection<Hotel>(
    new QdrantClient("localhost"),
    "skhotels");

データマッピング

Qdrant コネクタは、データモデルからストレージにデータをマッピングするときに、既定のマッパーを提供します。 Qdrant では、プロパティを ID、ペイロード、およびベクターのグループにマップする必要があります。既定のマッパーは、モデルの注釈またはレコード定義を使用して各プロパティの型を決定し、このマッピングを実行します。

キーとして注釈が付けられたデータモデルプロパティは、Qdrant ポイント ID にマップされます。
データとして注釈が付けられたデータモデルのプロパティは、Qdrant ポイントペイロードオブジェクトにマップされます。
ベクトルとして注釈が付けられたデータモデルのプロパティは、Qdrant ポイントベクターオブジェクトにマップされます。

プロパティ名のオーバーライド

データプロパティとベクタープロパティ (名前付きベクターモードを使用する場合) の場合は、データモデルのプロパティ名とは異なるストレージで使用するオーバーライドフィールド名を指定できます。 Qdrant ではキーの名前が固定されているため、これはキーではサポートされません。また、 名前のないベクター モードのベクターでもサポートされていません。これは、ベクターが固定名で格納されるためです。

プロパティ名のオーバーライドは、データモデル属性またはレコード定義を使用して StoragePropertyName オプションを設定することによって行われます。

属性に StoragePropertyName が設定されたデータモデルの例と、Qdrant で表される方法を次に示します。

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public ulong HotelId { get; set; }

    [VectorStoreRecordData(IsFilterable = true, StoragePropertyName = "hotel_name")]
    public string HotelName { get; set; }

    [VectorStoreRecordData(IsFullTextSearchable = true, StoragePropertyName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw, StoragePropertyName = "hotel_description_embedding")]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": 1,
    "payload": { "hotel_name": "Hotel Happy", "hotel_description": "A place where everyone can be happy." },
    "vector": {
        "hotel_description_embedding": [0.9, 0.1, 0.1, 0.1],
    }
}

作業の開始

qdrant クライアントを含む qdrant extras を使用してセマンティックカーネルをインストール。

pip install semantic-kernel[qdrant]

その後、 QdrantStore クラスを使用してベクターストアインスタンスを作成できます。これにより、Qdrant インスタンスに接続するための環境変数 QDRANT_URL、 QDRANT_API_KEY、 QDRANT_HOST、 QDRANT_PORT、 QDRANT_GRPC_PORT、 QDRANT_PATH、 QDRANT_LOCATION 、 QDRANT_PREFER_GRPS を使用して AsyncQdrantClient が作成されます。これらの値を直接指定することもできます。何も指定されていない場合は、 location=:memory:にフォールバックします。


from semantic_kernel.connectors.memory.qdrant import QdrantStore

vector_store = QdrantStore()

qdrant クライアントの独自のインスタンスを使用してベクターストアを作成することもできます。

from qdrant_client.async_qdrant_client import AsyncQdrantClient
from semantic_kernel.connectors.memory.qdrant import QdrantStore

client = AsyncQdrantClient(host='localhost', port=6333)
vector_store = QdrantStore(client=client)

コレクションを直接作成することもできます。

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

collection = QdrantCollection(collection_name="skhotels", data_model_type=hotel)

シリアル化

Qdrant コネクタは、ストアへの読み取りと書き込みに PointStruct と呼ばれるモデルを使用します。これは、 from qdrant_client.models import PointStructからインポートできます。シリアル化メソッドは PointStruct オブジェクトのリストの出力を受け取り、逆シリアル化メソッドは PointStruct オブジェクトのリストを受け取ります。

これには、名前付きベクトルまたは名前のないベクトルに関連する特別な考慮事項がいくつかあります。以下を参照してください。

この概念の詳細については、 erialization のドキュメントを参照してください。

Qdrant ベクターモード

Qdrant ではベクターストレージに対して 2 つのモードがサポートされ、既定のマッパーを備えた Qdrant Connector では両方のモードがサポートされます。既定のモードは、名前のないベクターです。

単一の無名ベクトル

このオプションでは、コレクションに含まれるベクターは 1 つだけで、Qdrant のストレージモデルでは名前が付けなくなります。次に示すのは、 single 無名ベクター モードを使用する場合に、Qdrant でオブジェクトがどのように表されるかを示しています。

new Hotel
{
    HotelId = 1,
    HotelName = "Hotel Happy",
    Description = "A place where everyone can be happy.",
    DescriptionEmbedding = new float[4] { 0.9f, 0.1f, 0.1f, 0.1f }
};

{
    "id": 1,
    "payload": { "HotelName": "Hotel Happy", "Description": "A place where everyone can be happy." },
    "vector": [0.9, 0.1, 0.1, 0.1]
}

Hotel(
    hotel_id = 1,
    hotel_name = "Hotel Happy",
    description = "A place where everyone can be happy.",
    description_embedding = [0.9f, 0.1f, 0.1f, 0.1f],
)

from qdrant_client.models import PointStruct

PointStruct(
    id=1,
    payload={ "hotel_name": "Hotel Happy", "description": "A place where everyone can be happy." },
    vector=[0.9, 0.1, 0.1, 0.1],
)

名前付きベクター

名前付きベクターモードを使用する場合は、コレクション内の各ポイントに複数のベクターが含まれる可能性があり、それぞれに名前が付けられることを意味します。次に示すのは、 named vector モードを使用する場合に Qdrant でオブジェクトを表す方法の例です。

new Hotel
{
    HotelId = 1,
    HotelName = "Hotel Happy",
    Description = "A place where everyone can be happy.",
    HotelNameEmbedding = new float[4] { 0.9f, 0.5f, 0.5f, 0.5f }
    DescriptionEmbedding = new float[4] { 0.9f, 0.1f, 0.1f, 0.1f }
};

{
    "id": 1,
    "payload": { "HotelName": "Hotel Happy", "Description": "A place where everyone can be happy." },
    "vector": {
        "HotelNameEmbedding": [0.9, 0.5, 0.5, 0.5],
        "DescriptionEmbedding": [0.9, 0.1, 0.1, 0.1],
    }
}

Hotel(
    hotel_id = 1,
    hotel_name = "Hotel Happy",
    description = "A place where everyone can be happy.",
    hotel_name_embedding = [0.9f, 0.5f, 0.5f, 0.5f],
    description_embedding = [0.9f, 0.1f, 0.1f, 0.1f],
)

from qdrant_client.models import PointStruct

PointStruct(
    id=1,
    payload={ "hotel_name": "Hotel Happy", "description": "A place where everyone can be happy." },
    vector={
        "hotel_name_embedding": [0.9, 0.5, 0.5, 0.5],
        "description_embedding": [0.9, 0.1, 0.1, 0.1],
    },
)

名前付きベクターモードを有効にするには、ベクターストアまたはコレクションを構築するときにオプションとしてこれを渡します。同じオプションを、指定された依存関係挿入コンテナー拡張メソッドのいずれかに渡すこともできます。

using Microsoft.SemanticKernel.Connectors.Qdrant;
using Qdrant.Client;

var vectorStore = new QdrantVectorStore(
    new QdrantClient("localhost"),
    new() { HasNamedVectors = true });

var collection = new QdrantVectorStoreRecordCollection<Hotel>(
    new QdrantClient("localhost"),
    "skhotels",
    new() { HasNamedVectors = true });

python では、 named_vectors の既定値は True ですが、次に示すように無効にすることもできます。

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

collection = QdrantCollection(
    collection_name="skhotels", 
    data_model_type=Hotel, 
    named_vectors=False,
)

次の方法で共有

Qdrant コネクタの使用 (プレビュー)

概要

作業の開始

データマッピング

プロパティ名のオーバーライド

作業の開始

シリアル化

Qdrant ベクターモード

単一の無名ベクトル

名前付きベクター

その他のリソース

次の方法で共有

Qdrant コネクタの使用 (プレビュー)

概要

作業の開始

データ マッピング

プロパティ名のオーバーライド

作業の開始

シリアル化

Qdrant ベクター モード

単一の無名ベクトル

名前付きベクター

その他のリソース

データマッピング

Qdrant ベクターモード