다음을 통해 공유

Qdrant 커넥터 사용(미리 보기)

경고

Qdrant Vector Store 기능은 미리 보기 상태이며, 릴리스 전에 특정 조건에서도 중대한 변경이 필요한 개선 사항이 계속 발생할 수 있습니다.

경고

시맨틱 커널 벡터 스토어 기능은 현재 프리뷰 상태이며, 릴리스 전에 제한된 상황에서도 호환성에 영향을 미치는 변경이 필요한 개선이 있을 수 있습니다.

경고

시맨틱 커널 벡터 스토어 기능은 현재 프리뷰 상태이며, 릴리스 전에 제한된 상황에서도 호환성에 영향을 미치는 변경이 필요한 개선이 있을 수 있습니다.

개요

Qdrant Vector Store 커넥터를 사용하여 Qdrant의 데이터에 액세스하고 관리할 수 있습니다. 커넥터의 특징은 다음과 같습니다.

기능 영역 지원
컬렉션이 특정 항목에 매핑됩니다. 필터링 가능한 데이터 필드에 대한 페이로드 인덱스가 있는 Qdrant 컬렉션
지원되는 키 속성 형식
  • ulong
  • 가이드
지원되는 데이터 속성 형식
  • 문자열
  • 정수 (int)
  • 길다
  • 두 배
  • 떠다니다
  • bool
  • 이러한 각 형식의 열거형
지원되는 벡터 속성 형식
  • 읽기 전용 메모리<float>
  • 부동 소수 자릿수<포함>
  • float[]
지원되는 인덱스 형식 Hnsw
지원되는 거리 함수
  • 코사인 유사도
  • 닷프로덕트유사도
  • EuclideanDistance
  • ManhattanDistance
지원되는 필터 구문
  • AnyTagEqualTo
  • EqualTo
레코드에서 여러 벡터를 지원합니다. 예(구성 가능)
IsIndexed가 지원되는가요? 예
IsFullTextIndexed가 지원되나요? 예
StorageName이 지원되는가요? 예
HybridSearch가 지원되는가요? 예
기능 영역 지원
컬렉션이 특정 항목에 매핑됩니다. 필터링 가능한 데이터 필드에 대한 페이로드 인덱스가 있는 Qdrant 컬렉션
지원되는 키 속성 형식
  • ulong
  • 가이드
지원되는 데이터 속성 형식
  • 문자열
  • 정수 (int)
  • 길다
  • 두 배
  • 떠다니다
  • bool
  • 이러한 각 형식의 및 반복 가능한 항목
지원되는 벡터 속성 형식
  • 리스트[float]
지원되는 인덱스 형식 Hnsw
지원되는 거리 함수
  • 코사인 유사도
  • 닷프로덕트유사도
  • EuclideanDistance
  • ManhattanDistance
지원되는 필터 구문
  • AnyTagEqualTo
  • EqualTo
레코드에서 여러 벡터를 지원합니다. 예(구성 가능)
IsFilterable이 지원되는가요? 예
IsFullTextSearchable이 지원되나요? 예
StorageName이 지원되는가요? 예

지원되지 않음

현재 지원되지 않습니다.

시작

Qdrant Vector Store 커넥터 NuGet 패키지를 프로젝트에 추가합니다.

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

의미 체계 커널에서 제공하는 확장 메서드를 사용하여 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를 사용하려면 ID, 페이로드 및 벡터 그룹에 속성을 매핑해야 합니다. 기본 매퍼는 모델 주석 또는 레코드 정의를 사용하여 각 속성의 형식을 확인하고 이 매핑을 수행합니다.

  • 키로 주석이 추가된 데이터 모델 속성은 Qdrant 지점 ID에 매핑됩니다.
  • 데이터로 주석이 추가된 데이터 모델의 속성은 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 extras를 사용하여 의미 체계 커널을 설치합니다.

pip install semantic-kernel[qdrant]

그런 다음 클래스를 사용하여 QdrantStore 벡터 저장소 인스턴스를 만들 수 있습니다. 그러면 환경 변수QDRANT_URL, QDRANT_API_KEY, QDRANT_HOST, QDRANT_PORTQDRANT_GRPC_PORTQDRANT_PATHQDRANT_LOCATIONQDRANT_PREFER_GRPS 및 Qdrant 인스턴스에 연결하여 AsyncQdrantClient를 만들고 해당 값을 직접 제공할 수도 있습니다. 만약 아무 것도 제공되지 않으면 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에서 가져올 수 있습니다. serialization 메서드는 PointStruct 개체 목록의 출력을 예상하며 역직렬화 메서드는 PointStruct 개체 목록을 받습니다.

명명되거나 명명되지 않은 벡터와 관련이 있는 몇 가지 특별한 고려 사항이 있습니다. 아래를 참조하세요.

이 개념에 대한 자세한 내용은 serialization 설명서를 참조 하세요.

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,
)