데이터 모델 정의(미리 보기)
Warning
의미 체계 커널 벡터 저장소 기능은 미리 보기 상태이며 릴리스 전에 제한된 상황에서도 호환성이 손상되는 변경이 필요한 개선 사항이 계속 발생할 수 있습니다.
개요
의미 체계 커널 벡터 저장소 커넥터는 모델 첫 번째 접근 방식을 사용하여 데이터베이스와 상호 작용합니다.
레코드를 upsert하거나 가져오는 모든 메서드는 강력한 형식의 모델 클래스를 사용합니다. 이러한 클래스의 속성은 각 속성의 용도를 나타내는 특성으로 데코레이팅됩니다.
팁
특성을 사용하는 대신 레코드 정의를 사용하여 스키마를 정의하는 방법을 참조하세요.
팁
사용자 고유의 데이터 모델을 정의하는 대신 사용자 고유의 데이터 모델을 정의하지 않고 벡터 저장소 추상화 사용을 참조하세요.
다음은 이러한 특성으로 데코레이팅된 모델의 예입니다.
using Microsoft.Extensions.VectorData;
public class Hotel
{
[VectorStoreRecordKey]
public ulong HotelId { get; set; }
[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }
[VectorStoreRecordData(IsFullTextSearchable = true)]
public string Description { get; set; }
[VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
[VectorStoreRecordData(IsFilterable = true)]
public string[] Tags { get; set; }
}
특성
VectorStoreRecordKeyAttribute
이 특성을 사용하여 속성이 레코드의 키임을 나타냅니다.
[VectorStoreRecordKey]
public ulong HotelId { get; set; }
VectorStoreRecordKeyAttribute 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| StoragePropertyName | 아니요 | 데이터베이스의 속성에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: 다음과 같은 JsonPropertyNameAttribute 대안이 지원되는 경우). |
팁
StoragePropertyName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.
VectorStoreRecordDataAttribute
이 특성을 사용하여 속성에 키 또는 벡터가 아닌 일반 데이터가 포함되어 있음을 나타냅니다.
[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }
VectorStoreRecordDataAttribute 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| IsFilterable | 아니요 | 데이터베이스에서 속성당 인덱싱을 옵트인해야 하는 경우 필터링을 위해 속성을 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다. |
| IsFullTextSearchable | 아니요 | 전체 텍스트 검색을 지원하는 데이터베이스에 대한 전체 텍스트 검색을 위해 속성을 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다. |
| StoragePropertyName | 아니요 | 데이터베이스의 속성에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: 다음과 같은 JsonPropertyNameAttribute 대안이 지원되는 경우). |
팁
StoragePropertyName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.
VectorStoreRecordVectorAttribute
이 특성을 사용하여 속성에 벡터가 포함되어 있음을 나타냅니다.
[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
VectorStoreRecordVectorAttribute 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| 차원 | 컬렉션 만들기의 경우 예입니다. 그렇지 않으면 선택 사항입니다. | 벡터에 있는 차원의 수입니다. 이는 일반적으로 컬렉션에 대한 벡터 인덱스 생성 시 필요합니다. |
| IndexKind | 아니요 | 벡터를 인덱싱할 인덱스의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다. |
| DistanceFunction | 아니요 | 이 벡터를 검색하는 동안 벡터 비교를 수행할 때 사용할 거리 함수의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다. |
| StoragePropertyName | 아니요 | 데이터베이스의 속성에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: 다음과 같은 JsonPropertyNameAttribute 대안이 지원되는 경우). |
공통 인덱스 종류 및 거리 함수 형식은 및 Microsoft.SemanticKernel.Data.DistanceFunction 클래스에서 Microsoft.SemanticKernel.Data.IndexKind 정적 값으로 제공됩니다.
개별 벡터 저장소 구현은 데이터베이스에서 비정상적인 형식을 지원하는 자체 인덱스 종류 및 거리 함수를 사용할 수도 있습니다.
팁
StoragePropertyName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.
레코드를 upsert하거나 가져오는 모든 메서드는 클래스 및 벡터 저장소 레코드 정의를 사용합니다.
이 작업은 필드에 대한 주석을 사용하여 고유한 클래스를 정의하거나 레코드 정의와 함께 클래스/형식을 사용하여 수행할 수 있습니다. 클래스에 대해 수행해야 하는 두 가지 작업은 첫 번째는 필드 형식으로 주석을 추가하는 것입니다. 두 번째는 클래스를 데코레이터로 vectorstoremodel 데코레이트하는 것입니다.
팁
레코드 정의를 사용하는 대체 방법은 레코드 정의를 사용하여 스키마를 정의하는 방법을 참조하세요.
다음은 이러한 주석으로 데코레이팅된 모델의 예입니다.
from dataclasses import dataclass, field
from typing import Annotated
from semantic_kernel.data import (
DistanceFunction,
IndexKind,
VectorStoreRecordDataField,
VectorStoreRecordDefinition,
VectorStoreRecordKeyField,
VectorStoreRecordVectorField,
vectorstoremodel,
)
@vectorstoremodel
@dataclass
class Hotel:
hotel_id: Annotated[str, VectorStoreRecordKeyField()] = field(default_factory=lambda: str(uuid4()))
hotel_name: Annotated[str, VectorStoreRecordDataField(is_filterable=True)]
description: Annotated[str, VectorStoreRecordDataField(is_full_text_searchable=True)]
description_embedding: Annotated[list[float], VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)]
tags: Annotated[list[str], VectorStoreRecordDataField(is_filterable=True)]
팁
이러한 주석을 사용하여 클래스를 정의하는 작업은 여러 가지 방법으로 수행할 수 있으며, 그 중 하나는 여기에 표시된 Python의 모듈을 사용하는 dataclasses 것입니다. 이 샘플 에서는 다른 방법(Pydantic BaseModels 및 바닐라 Python 클래스 사용)도 보여 줍니다.
주석
사용할 주석에는 세 가지 유형이 있으며 공통 기본 클래스가 있습니다.
VectorStoreRecordField
이는 모든 주석의 기본 클래스이며 직접 사용할 수 없습니다.
VectorStoreRecordField 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| name | 아니요 | 직접 추가할 수 있지만 모델을 구문 분석하는 동안 설정됩니다. |
| property_type | 아니요 | 문자열이어야 하며 구문 분석 중에도 파생됩니다. |
팁
주석은 데코레이터에 의해 vectorstoremodel 구문 분석되고 클래스에 대한 레코드 정의를 만드는 것입니다. 따라서 매개 변수가 설정되지 않은 경우 필드 클래스를 인스턴스화할 필요가 없으며 다음과 같이 클래스로만 필드에 주석을 달 수 있습니다.
hotel_id: Annotated[str, VectorStoreRecordKeyField]
VectorStoreRecordKeyField
이 주석을 사용하여 이 특성이 레코드의 키임을 나타냅니다.
VectorStoreRecordKeyField()
VectorStoreRecordKeyField 매개 변수
기본 클래스 외부의 다른 매개 변수는 정의되지 않습니다.
VectorStoreRecordDataField
이 주석을 사용하여 특성에 키 또는 벡터가 아닌 일반 데이터가 포함되어 있음을 나타냅니다.
VectorStoreRecordDataField(is_filterable=True)
VectorStoreRecordDataField 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| has_embedding | 아니요 | 속성에 연결된 포함이 있는지 여부를 나타냅니다. 기본값은 None입니다. |
| embedding_property_name | 아니요 | 포함을 포함하는 속성의 이름이며, 기본값은 None입니다. |
| is_filterable | 아니요 | 데이터베이스에서 속성당 인덱싱을 옵트인해야 하는 경우 필터링을 위해 속성을 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다. |
| is_full_text_searchable | 아니요 | 전체 텍스트 검색을 지원하는 데이터베이스에 대한 전체 텍스트 검색을 위해 속성을 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다. |
VectorStoreRecordVectorField
이 주석을 사용하여 특성에 벡터가 포함되어 있음을 나타냅니다.
VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)
VectorStoreRecordVectorField 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| dimensions | 컬렉션 만들기의 경우 예입니다. 그렇지 않으면 선택 사항입니다. | 벡터에 있는 차원의 수입니다. 이는 일반적으로 컬렉션에 대한 벡터 인덱스 생성 시 필요합니다. |
| index_kind | 아니요 | 벡터를 인덱싱할 인덱스의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다. |
| distance_function | 아니요 | 이 벡터를 검색하는 동안 벡터 비교를 수행할 때 사용할 거리 함수의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다. |
| local_embedding | 아니요 | 속성에 연결된 로컬 포함이 있는지 여부를 나타냅니다. 기본값은 None입니다. |
| embedding_settings | 아니요 | service_id 키로 사용하고 PromptExecutionSettings를 값으로 사용하는 받아쓰기 형식의 포함 설정은 기본값은 None입니다. |
| serialize_function | 아니요 | 형식이 list[float | int]이 아니거나 이 함수가 필요하거나 전체 모델을 serialize해야 하는 경우 벡터를 serialize하는 데 사용할 함수입니다. |
| deserialize_function | 아니요 | 형식이 list[float | int]이 아니거나 이 함수가 필요하거나 전체 모델을 역직렬화해야 하는 경우 벡터를 역직렬화하는 데 사용할 함수입니다. |
공통 인덱스 종류 및 거리 함수 형식은 및 semantic_kernel.data.DistanceFunction 클래스에서 semantic_kernel.data.IndexKind 정적 값으로 제공됩니다.
개별 벡터 저장소 구현은 데이터베이스에서 비정상적인 형식을 지원하는 자체 인덱스 종류 및 거리 함수를 사용할 수도 있습니다.
레코드를 upsert하거나 가져오는 모든 메서드는 강력한 형식의 모델 클래스를 사용합니다. 이러한 클래스의 필드는 각 필드의 용도를 나타내는 주석으로 데코레이팅됩니다.
팁
특성을 사용하는 대신 레코드 정의를 사용하여 스키마를 정의하는 방법을 참조하세요.
다음은 이러한 주석으로 데코레이팅된 모델의 예입니다. 기본적으로 대부분의 기본 벡터 저장소는 Jackson을 사용하므로 모델 개체가 Jackson에 의해 직렬화될 수 있도록 하는 것이 좋습니다. 즉, 클래스가 표시되고 getter, 생성자, 주석이 있습니다.
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordData;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordKey;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordVector;
import com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction;
import com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind;
import java.util.List;
public class Hotel {
@VectorStoreRecordKey
private String hotelId;
@VectorStoreRecordData(isFilterable = true)
private String name;
@VectorStoreRecordData(isFullTextSearchable = true)
private String description;
@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;
@VectorStoreRecordData(isFilterable = true)
private List<String> tags;
public Hotel() { }
public Hotel(String hotelId, String name, String description, List<Float> descriptionEmbedding, List<String> tags) {
this.hotelId = hotelId;
this.name = name;
this.description = description;
this.descriptionEmbedding = descriptionEmbedding;
this.tags = tags;
}
public String getHotelId() { return hotelId; }
public String getName() { return name; }
public String getDescription() { return description; }
public List<Float> getDescriptionEmbedding() { return descriptionEmbedding; }
public List<String> getTags() { return tags; }
}
주석
VectorStoreRecordKey
이 주석을 사용하여 필드가 레코드의 키임을 나타냅니다.
@VectorStoreRecordKey
private String hotelId;
VectorStoreRecordKey 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| storageName | 아니요 | 데이터베이스의 필드에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: Jackson이 사용되는 경우). 이 경우 Jackson 주석을 사용하여 스토리지 이름을 지정할 수 있습니다. |
팁
storageName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.
VectorStoreRecordData
이 주석을 사용하여 필드에 키 또는 벡터가 아닌 일반 데이터가 포함되어 있음을 나타냅니다.
@VectorStoreRecordData(isFilterable = true)
private String name;
VectorStoreRecordData 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| isFilterable | 아니요 | 데이터베이스에서 필드당 인덱싱을 옵트인해야 하는 경우 필터링을 위해 필드를 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다. |
| isFullTextSearchable | 아니요 | 전체 텍스트 검색을 지원하는 데이터베이스에 대한 전체 텍스트 검색을 위해 필드를 인덱싱해야 하는지 여부를 나타냅니다. 기본값은 false입니다. |
| storageName | 아니요 | 데이터베이스의 필드에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: Jackson이 사용되는 경우). 이 경우 Jackson 주석을 사용하여 스토리지 이름을 지정할 수 있습니다. |
팁
storageName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.
VectorStoreRecordVector
이 주석을 사용하여 필드에 벡터가 포함되어 있음을 나타냅니다.
@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;
VectorStoreRecordVector 매개 변수
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| dimensions | 컬렉션 만들기의 경우 예입니다. 그렇지 않으면 선택 사항입니다. | 벡터에 있는 차원의 수입니다. 이는 일반적으로 컬렉션에 대한 벡터 인덱스 생성 시 필요합니다. |
| indexKind | 아니요 | 벡터를 인덱싱할 인덱스의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다. |
| distanceFunction | 아니요 | 이 벡터를 검색하는 동안 벡터 비교를 수행할 때 사용할 거리 함수의 형식입니다. 기본값은 벡터 저장소 유형에 따라 다릅니다. |
| storageName | 아니요 | 데이터베이스의 필드에 대한 대체 이름을 제공하는 데 사용할 수 있습니다. 이 매개 변수는 모든 커넥터에서 지원되지 않습니다(예: Jackson이 사용되는 경우). 이 경우 Jackson 주석을 사용하여 스토리지 이름을 지정할 수 있습니다. |
공통 인덱스 종류 및 거리 함수 형식은 열거형 및 com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction 열거형에 com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind 제공됩니다.
개별 벡터 저장소 구현은 데이터베이스에서 비정상적인 형식을 지원하는 자체 인덱스 종류 및 거리 함수를 사용할 수도 있습니다.
팁
storageName을 지원하는 커넥터 및 사용 가능한 대안에 대한 자세한 내용은 각 커넥터에 대한 설명서를 참조하세요.
추가 정보는 곧 제공될 예정입니다.