使用 Qdrant 連接器（預覽）

發行項
11/03/2024

警告

語意核心向量存放區功能處於預覽狀態，且需要重大變更的改善可能仍會在發行前有限的情況下發生。

概觀

Qdrant Vector Store 連接器可用來存取和管理 Qdrant 中的數據。連接器具有下列特性。

功能區域	支援
集合對應至	具有可篩選數據欄位承載索引的 Qdrant 集合
支援的索引鍵屬性類型	ulong Guid
支援的數據類型	字串 int long double float bool 和這些類型的可列舉專案
支援的向量屬性類型	ReadOnlyMemory<float>
支援的索引類型	Hnsw
支援的距離函式	CosineSimilarity DotProductSimilarity EuclideanDistance 曼哈頓
支援的篩選子句	AnyTagEqualTo EqualTo
支援記錄中的多個向量	是（可設定）
是否支援IsFilterable？	Yes
是否支援IsFullTextSearchable？	Yes
支援的 StoragePropertyName？	Yes

開始使用

將 Qdrant Vector Store 連接器 NuGet 套件新增至您的專案。

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

您可以使用 Semantic Kernel 所提供的擴充方法，將向量存放區新增至 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 需要將屬性對應至標識碼、承載和向量群組。默認對應程式會使用模型批註或記錄定義來判斷每個屬性的類型，並執行此對應。

批注為索引鍵的數據模型屬性將會對應至 Qdrant 點標識碼。
批註為數據的數據模型屬性將會對應至 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 用戶端。

pip install semantic-kernel[qdrant]

接著，您可以使用類別建立向量存放區實例QdrantStore，這會使用環境變數 QDRANT_URL、QDRANT_API_KEY、、、QDRANT_HOST、QDRANT_PORTQDRANT_GRPC_PORT、 QDRANT_PATHQDRANT_LOCATION 和 QDRANT_PREFER_GRPS 來建立 AsyncQdrantClient，以聯機到 Qdrant 實例，也可以直接提供這些值。如果沒有提供任何專案，則會回復為 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 物件的清單。

有一些特殊考慮，這與具名或未命名的向量有關，請參閱下方。

如需此概念的詳細資訊，請參閱串行化檔。

Qdrant 向量模式

Qdrant 支援兩種向量儲存模式，而具有預設對應工具的 Qdrant 連接器支援這兩種模式。預設模式為 單一未命名向量。

單一未命名向量

使用此選項時，集合可能只包含單一向量，且在Qdrant的記憶體模型中不會命名。以下是使用 單一未命名向量 模式時，物件如何在 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],
)

具名向量

如果使用具名向量模式，表示集合中的每個點可能包含一個以上的向量，而且每個點都會命名。以下是使用 具名向量 模式時，如何在 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 連接器（預覽）