共用方式為

使用 Qdrant 連接器 （預覽）

警告

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

警告

語意核心向量存放區功能目前處於預覽階段，且在發行前的某些有限情況下，可能仍需進行重大變更以實現改善。

警告

語意核心向量存放區功能目前處於預覽階段，且在發行前的某些有限情況下，可能仍需進行重大變更以實現改善。

概觀

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

功能範圍 支援
集合映射到 具有可篩選數據欄位承載索引的 Qdrant 集合
支援的關鍵屬性類型
  • ulong
  • Guid
支援的數據類型
  • 字串
  • 整數 (int)
  • 長
  • 雙倍
  • 浮動
  • 布爾 (bool)
  • 和這些類型的可列舉物件
支援的向量屬性類型
  • ReadOnlyMemory<float>
  • 內嵌<浮動>
  • float[]
支援的索引類型 Hnsw
支持的距離函數
  • CosineSimilarity
  • 點積相似性 (DotProductSimilarity)
  • EuclideanDistance
  • 曼哈頓距離
受支援的篩選條件
  • AnyTagEqualTo
  • EqualTo
支援記錄中的多個向量 是 （可設定）
是否支援 IsIndexed？ 是的
是否支援IsFullTextIndexed？ 是的
是否支援 StorageName？ 是的
支援 HybridSearch 嗎？ 是的
功能範圍 支援
集合映射到 具有可篩選數據欄位承載索引的 Qdrant 集合
支援的關鍵屬性類型
  • ulong
  • Guid
支援的數據類型
  • 字串
  • 整數 (int)
  • 長
  • 雙倍
  • 浮動
  • 布爾 (bool)
  • 以及每種類型的可迭代對象
支援的向量屬性類型
  • list[float]
支援的索引類型 Hnsw
支持的距離函數
  • CosineSimilarity
  • 點積相似性 (DotProductSimilarity)
  • EuclideanDistance
  • 曼哈頓距離
受支援的篩選條件
  • AnyTagEqualTo
  • EqualTo
支援記錄中的多個向量 是 （可設定）
是否支援IsFilterable？ 是的
支援 IsFullTextSearchable 嗎？ 是的
是否支援 StorageName？ 是的

不支援

目前不支援。

入門指南

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

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

您可以使用 Semantic Kernel 所提供的擴充方法，將向量存放區新增至 KernelBuilder 的相依性插入容器，或新增至 IServiceCollection 的相依性插入容器。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

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

using Microsoft.Extensions.DependencyInjection;

// 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.Services.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"), ownsClient: true);

可以建構對具名集合的直接參考。

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

var collection = new QdrantCollection<ulong, Hotel>(
    new QdrantClient("localhost"),
    "skhotels",
    ownsClient: true);

資料映射

Qdrant 連接器會在將數據從數據模型對應至記憶體時，提供預設對應程式。 Qdrant 需要將屬性對應至識別碼、有效載荷和向量群組。 默認對應程式會使用模型批註或記錄定義來判斷每個屬性的類型，並執行此對應。

  • 批注為索引鍵的數據模型屬性將會對應至 Qdrant 點標識碼。
  • 標註為數據的數據模型屬性將會映射到 Qdrant 點載荷對象。
  • 標註為向量的數據模型屬性將會被對應至 Qdrant 的點向量物件。

屬性名稱覆寫

對於資料屬性和向量屬性（如果使用具名向量模式），您可以提供覆寫欄位名稱，以用於儲存中，這些名稱與數據模型中的屬性名稱不同。 密鑰不支援此項目，因為金鑰在 Qdrant 中具有固定名稱。 單一未命名向量模式的 向量也不支持，因為向量 會以固定名稱儲存。

屬性名稱覆寫是透過資料模型屬性或記錄定義設定 StorageName 選項來完成的。

以下是一個其屬性已設有 StorageName 的數據模型範例，以及在 Qdrant 中的表示方式。

using Microsoft.Extensions.VectorData;

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

    [VectorStoreData(IsIndexed = true, StorageName = "hotel_name")]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true, StorageName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreVector(4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw, StorageName = "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.qdrant import QdrantStore

vector_store = QdrantStore()

您也可以使用自己的 qdrant 用戶端實例來建立向量存放區。

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

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

您也可以直接建立集合。

from semantic_kernel.connectors.qdrant import QdrantCollection

collection = QdrantCollection(collection_name="skhotels", record_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]
}

Qdrant 向量模式

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

單一未命名向量

使用此選項時，集合可能只包含單一向量，且在Qdrant的記憶體模型中不會命名。 以下是使用 單一未命名向量 模式時，物件如何在 Qdrant 中表示的範例：

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],
    }
}

具名向量

如果使用具名向量模式，表示集合中的每個點可能包含一個以上的向量，而且每個點都會命名。 以下是使用 具名向量 模式時，如何在 Qdrant 中表示物件的範例：

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"),
    ownsClient: true,
    new() { HasNamedVectors = true });

var collection = new QdrantCollection<ulong, Hotel>(
    new QdrantClient("localhost"),
    "skhotels",
    ownsClient: true,
    new() { HasNamedVectors = true });

若要啟用具名向量模式，請在建構向量存放區或集合時，以選項傳遞此選項。 相同的選項也可以傳遞至任何提供的相依性插入容器擴充方法。

在 python 中，的預設值 named_vectors 為 True，但您也可以停用此值，如下所示。

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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