레코드 정의를 사용하여 스토리지 스키마 정의(미리 보기)

Warning

의미 체계 커널 벡터 저장소 기능은 미리 보기 상태이며 릴리스 전에 제한된 상황에서도 호환성이 손상되는 변경이 필요한 개선 사항이 계속 발생할 수 있습니다.

개요

의미 체계 커널 벡터 저장소 커넥터는 데이터베이스와 상호 작용하는 모델 첫 번째 접근 방식을 사용하며 인덱스를 만들거나 데이터를 데이터베이스 스키마에 매핑하는 데 필요한 정보로 데이터 모델에 주석을 추가할 수 있습니다.

이 정보를 제공하는 또 다른 방법은 데이터 모델에 별도로 정의하고 제공할 수 있는 레코드 정의를 사용하는 것입니다. 이 기능은 여러 시나리오에서 유용할 수 있습니다.

• 개발자가 둘 이상의 구성으로 동일한 데이터 모델을 사용하려는 경우가 있을 수 있습니다.
• 개발자가 모델에 매우 다른 스키마를 사용하여 데이터를 저장하고 데이터 모델과 스토리지 스키마 간에 변환하기 위한 사용자 지정 매퍼를 제공하려는 경우가 있을 수 있습니다.
• 개발자가 dict와 같은 기본 제공 형식 또는 데이터 프레임과 같은 최적화된 형식을 사용하려고 하지만 여전히 벡터 저장소 기능을 활용하려는 경우가 있을 수 있습니다.

레코드 정의를 만드는 방법의 예는 다음과 같습니다.

using Microsoft.Extensions.VectorData;

var hotelDefinition = new VectorStoreRecordDefinition
{
    Properties = new List<VectorStoreRecordProperty>
    {
        new VectorStoreRecordKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },
        new VectorStoreRecordDataProperty("Description", typeof(string)) { IsFullTextSearchable = true },
        new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },
    }
};

정의를 만들 때 인덱스 만들기 및 데이터 매핑에 필요하므로 스키마의 각 속성에 대한 이름과 형식을 항상 제공해야 합니다.

정의를 사용하려면 GetCollection 메서드에 전달합니다.

var collection = vectorStore.GetCollection<ulong, Hotel>("skhotels", hotelDefinition);

Record 속성 구성 클래스

VectorStoreRecordKeyProperty

이 클래스를 사용하여 속성이 레코드의 키임을 나타냅니다.

new VectorStoreRecordKeyProperty("HotelId", typeof(ulong)),

VectorStoreRecordKeyProperty 구성 설정

매개 변수	필수	설명
DataModelPropertyName	예	데이터 모델의 속성 이름입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
PropertyType	예	데이터 모델의 속성 형식입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
StoragePropertyName	아니요	데이터베이스의 속성에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: 다음과 같은 JsonPropertyNameAttribute 대안이 지원되는 경우).

팁

StoragePropertyName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.

VectorStoreRecordDataProperty

이 클래스를 사용하여 속성에 키 또는 벡터가 아닌 일반 데이터가 포함되어 있음을 나타냅니다.

new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },

VectorStoreRecordDataProperty 구성 설정

매개 변수	필수	설명
DataModelPropertyName	예	데이터 모델의 속성 이름입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
PropertyType	예	데이터 모델의 속성 형식입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
IsFilterable	아니요	데이터베이스에서 속성당 인덱싱을 옵트인해야 하는 경우 필터링을 위해 속성을 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다.
IsFullTextSearchable	아니요	전체 텍스트 검색을 지원하는 데이터베이스에 대한 전체 텍스트 검색을 위해 속성을 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다.
StoragePropertyName	아니요	데이터베이스의 속성에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: 다음과 같은 JsonPropertyNameAttribute 대안이 지원되는 경우).

팁

StoragePropertyName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.

VectorStoreRecordVectorProperty

이 클래스를 사용하여 속성에 벡터가 포함되어 있음을 나타냅니다.

new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },

VectorStoreRecordVectorProperty 구성 설정

매개 변수	필수	설명
DataModelPropertyName	예	데이터 모델의 속성 이름입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
PropertyType	예	데이터 모델의 속성 형식입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
차원	컬렉션 만들기의 경우 예입니다. 그렇지 않으면 선택 사항입니다.	벡터에 있는 차원의 수입니다. 이는 일반적으로 컬렉션에 대한 벡터 인덱스 생성 시 필요합니다.
IndexKind	아니요	벡터를 인덱싱할 인덱스의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다.
DistanceFunction	아니요	이 벡터를 검색하는 동안 벡터 비교를 수행할 때 사용할 거리 함수의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다.
StoragePropertyName	아니요	데이터베이스의 속성에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: 다음과 같은 JsonPropertyNameAttribute 대안이 지원되는 경우).

팁

StoragePropertyName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.

다음은 pandas DataFrame과 함께 사용할 레코드 정의를 만드는 방법의 예입니다.

참고 항목

데이터 모델 정의와 동일한 필드가 여기에 사용됩니다. 여기서는 주석으로 추가되는 데이터 모델에서 이름이 있는 받아쓰기로 추가됩니다.

주의해야 할 몇 가지 중요한 사항이 있으며, 다른 하나는 필드 정의 자체입니다. 첫 번째는 매개 변수입니다 container_mode . True로 설정하면 데이터 모델이 DataFrame과 같은 컨테이너 형식이며, 따라서 데이터 모델이 단일 레코드가 아닌 레코드의 컨테이너임을 나타내며, 컨테이너 레코드를 정확히 동일한 방식으로 사용할 수 있다는 것이 주요 차이점은 동일한 데이터 형식을 get_batch 반환한다는 get 것입니다. 에 대해 하나 이상의 레코드가 get 있습니다get_batch. upsert upsert upsert_batch 를 수행하려는 경우, 즉, 컨테이너를 전달 upsert 하면 단일 업서트가 아닌 여러 upsert가 생성됩니다.

두 번째는 데이터 모델과 from_dict 스토리지 스키마 간에 변환하는 데 사용되는 메서드와 메서드를 추가하는 to_dict 것입니다. 이 경우 to_dict 메서드는 DataFrame을 레코드 목록으로 변환하는 데 사용되며 from_dict , 이 메서드는 레코드 목록을 DataFrame으로 변환하는 데 사용됩니다. 또한 직렬화 설명서를 참조하여 차이점에 대한 자세한 내용은 아래 예제에 나와 있지 않은 메서드와 deserialize 메서드가 있을 serialize 수 있습니다.

from semantic_kernel.data import (
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
)

hotel_definition = VectorStoreRecordDefinition(
    fields={
        "hotel_id": VectorStoreRecordKeyField(property_type="str"),
        "hotel_name": VectorStoreRecordDataField(property_type="str", is_filterable=True),
        "description": VectorStoreRecordDataField(
            property_type="str", has_embedding=True, embedding_property_name="description_embedding"
        ),
        "description_embedding": VectorStoreRecordVectorField(property_type="list[float]"),
    },
    container_mode=True,
    to_dict=lambda record, **_: record.to_dict(orient="records"),
    from_dict=lambda records, **_: DataFrame(records),
)

정의를 만들 때 인덱스 만들기 및 데이터 매핑에 필요하므로 항상 스키마의 fields 각 속성에 대한 이름(dict의 키)과 형식을 제공해야 합니다.

정의를 사용하려면 데이터 모델 형식과 함께 GetCollection 메서드 또는 컬렉션 생성자에 전달합니다.

collection = vector_store.get_collection(
    collection_name="skhotels", 
    data_model_type=pd.DataFrame, 
    data_model_definition=hotel_definition,
)

레코드 정의를 만드는 방법의 예는 다음과 같습니다.

var hotelDefinition = VectorStoreRecordDefinition.fromFields(
    Arrays.asList(
        VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),
        VectorStoreRecordDataField.builder()
            .withName("name")
            .withFieldType(String.class)
            .isFilterable(true).build(),
        VectorStoreRecordDataField.builder()
            .withName("description")
            .withFieldType(String.class)
            .isFullTextSearchable(true).build(),
        VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
            .withDimensions(4)
            .withIndexKind(IndexKind.HNSW)
            .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
            .withFieldType(List.class).build()
    )
);

정의를 만들 때 인덱스 만들기 및 데이터 매핑에 필요하므로 스키마의 각 필드에 대한 이름과 형식을 항상 제공해야 합니다.

정의를 사용하려면 GetCollection 메서드에 전달합니다.

var collection = vectorStore.getCollection("skhotels",
        JDBCVectorStoreRecordCollectionOptions.builder()
            .withRecordDefinition(hotelDefinition)
            .build()
    );

레코드 필드 구성 클래스

VectorStoreRecordKeyField

이 클래스를 사용하여 필드가 레코드의 키임을 나타냅니다.

VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),

VectorStoreRecordKeyField 구성 설정

매개 변수	필수	설명
name	예	데이터 모델의 필드 이름입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
fieldType	예	데이터 모델의 필드 형식입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
storageName	아니요	데이터베이스의 필드에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: Jackson이 사용되는 경우). 이 경우 Jackson 주석을 사용하여 스토리지 이름을 지정할 수 있습니다.

팁

storageName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.

VectorStoreRecordDataField

이 클래스를 사용하여 속성에 키 또는 벡터가 아닌 일반 데이터가 포함되어 있음을 나타냅니다.

VectorStoreRecordDataField.builder()
    .withName("name")
    .withFieldType(String.class)
    .isFilterable(true).build(),

VectorStoreRecordDataField 구성 설정

매개 변수	필수	설명
name	예	데이터 모델의 필드 이름입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
fieldType	예	데이터 모델의 필드 형식입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
isFilterable	아니요	데이터베이스에서 필드당 인덱싱을 옵트인해야 하는 경우 필터링을 위해 필드를 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다.
isFullTextSearchable	아니요	전체 텍스트 검색을 지원하는 데이터베이스에 대한 전체 텍스트 검색을 위해 필드를 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다.
storageName	아니요	데이터베이스의 필드에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: Jackson이 사용되는 경우). 이 경우 Jackson 주석을 사용하여 스토리지 이름을 지정할 수 있습니다.

팁

storageName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.

VectorStoreRecordVectorField

이 클래스를 사용하여 필드에 벡터가 포함되어 있음을 나타냅니다.

VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
    .withDimensions(4)
    .withIndexKind(IndexKind.HNSW)
    .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
    .withFieldType(List.class).build(),

VectorStoreRecordVectorField 구성 설정

매개 변수	필수	설명
name	예	데이터 모델의 필드 이름입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
fieldType	예	데이터 모델의 필드 형식입니다. 기본 제공 매퍼에서 스토리지 스키마와 데이터 모델 간에 자동으로 매핑하고 인덱스를 만드는 데 사용됩니다.
dimensions	컬렉션 만들기의 경우 예입니다. 그렇지 않으면 선택 사항입니다.	벡터에 있는 차원의 수입니다. 이는 일반적으로 컬렉션에 대한 벡터 인덱스 생성 시 필요합니다.
indexKind	아니요	벡터를 인덱싱할 인덱스의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다.
distanceFunction	아니요	이 벡터를 검색하는 동안 벡터 비교를 수행할 때 사용할 거리 함수의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다.
storageName	아니요	데이터베이스의 필드에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: Jackson이 사용되는 경우). 이 경우 Jackson 주석을 사용하여 스토리지 이름을 지정할 수 있습니다.

팁

storageName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.