共用方式為

定義您的資料模型 （預覽）

  • 發行項

警告

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

概觀

語意核心向量存放區連接器會使用模型第一種方法來與資料庫互動。

更新插入或取得記錄的所有方法都會使用強型別模型類別。 這些類別上的屬性會以指出每個屬性用途的屬性裝飾。

提示

如需使用屬性的替代方案，請參閱 使用記錄定義來定義架構。

提示

如需定義您自己的數據模型的替代方案，請參閱 使用向量存放區抽象概念，而不定義您自己的數據模型。

以下是以這些屬性裝飾的模型範例。

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 No 可用來提供資料庫中屬性的替代名稱。 請注意，所有連接器都不支援此參數，例如支援的替代 JsonPropertyNameAttribute 專案。

提示

如需哪些連接器支援 StoragePropertyName 以及有哪些替代方案的詳細資訊，請參閱 每個連接器的檔。

VectorStoreRecordDataAttribute

使用這個屬性表示您的屬性包含不是索引鍵或向量的一般數據。

[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }

VectorStoreRecordDataAttribute 參數

參數 必要 描述
IsFilterable No 指出當資料庫需要加入每個屬性的索引編製索引時，是否應該為屬性編製索引以進行篩選。 預設為 False。
IsFullTextSearchable No 指出是否應該針對支援全文搜索的資料庫，為全文搜索編製屬性的索引。 預設為 False。
StoragePropertyName No 可用來提供資料庫中屬性的替代名稱。 請注意，所有連接器都不支援此參數，例如支援的替代 JsonPropertyNameAttribute 專案。

提示

如需哪些連接器支援 StoragePropertyName 以及有哪些替代方案的詳細資訊，請參閱 每個連接器的檔。

VectorStoreRecordVectorAttribute

使用這個屬性表示您的屬性包含向量。

[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

VectorStoreRecordVectorAttribute 參數

參數 必要 描述
維度 [是] 用於集合建立，否則為選擇性 向量擁有的維度數目。 建立集合的向量索引時，通常需要這樣做。
IndexKind No 要用來為向量編製索引的索引型別。 預設值會依向量存放區類型而有所不同。
DistanceFunction No 在此向量搜尋期間執行向量比較時所要使用的距離函式類型。 預設值會依向量存放區類型而有所不同。
StoragePropertyName No 可用來提供資料庫中屬性的替代名稱。 請注意，所有連接器都不支援此參數，例如支援的替代 JsonPropertyNameAttribute 專案。

常見的索引種類和距離函式類型會以 和 Microsoft.SemanticKernel.Data.DistanceFunction 類別上的Microsoft.SemanticKernel.Data.IndexKind靜態值的形式提供。 個別向量存放區實作也可以使用自己的索引類型和距離函式，其中資料庫支援不尋常的類型。

提示

如需哪些連接器支援 StoragePropertyName 以及有哪些替代方案的詳細資訊，請參閱 每個連接器的檔。

所有更新插入或取得記錄的方法都會使用 類別和向量存放區記錄定義。

這可以藉由使用欄位的註釋來定義您自己的類別，或使用類別/型別搭配記錄定義來完成。 類別需要做兩件事，第一件事是新增具有字段類型的批註，第二件事是使用 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)]

提示

您可以透過多種方式定義具有這些註釋的類別，其中一種是在 dataclasses Python 中使用模組，如下所示。 此 範例 也會示範其他方法（使用 Pydantic BaseModels 和 vanilla Python 類別）。

註釋

有三種類型的註釋可供使用，而且具有通用基類。

VectorStoreRecordField

這是所有批注的基類，不打算直接使用。

VectorStoreRecordField 參數

參數 必要 描述
NAME No 可以直接新增，但將在模型剖析期間設定。
property_type No 應該是字串，也會在剖析期間衍生。

提示

批註是由 vectorstoremodel 裝飾專案剖析，而其所做的其中一件事是建立類別的記錄定義，因此不需要在未設定任何參數時具現化欄位類別，字段只能以 類別加上批注，如下所示：

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

使用此批注來指出此屬性是記錄的索引鍵。

VectorStoreRecordKeyField()

VectorStoreRecordKeyField 參數

不會定義基類以外的其他參數。

VectorStoreRecordDataField

使用此批注來指出您的屬性包含不是索引鍵或向量的一般數據。

VectorStoreRecordDataField(is_filterable=True)

VectorStoreRecordDataField 參數

參數 必要 描述
has_embedding No 指出屬性是否有與其相關聯的內嵌，預設值為 None。
embedding_property_name No 包含內嵌的屬性名稱，預設值為 None。
is_filterable No 指出當資料庫需要加入每個屬性的索引編製索引時，是否應該為屬性編製索引以進行篩選。 預設為 False。
is_full_text_searchable No 指出是否應該針對支援全文搜索的資料庫，為全文搜索編製屬性的索引。 預設為 False。

VectorStoreRecordVectorField

使用此批注來指出您的屬性包含向量。

VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)

VectorStoreRecordVectorField 參數

參數 必要 描述
尺寸 [是] 用於集合建立，否則為選擇性 向量擁有的維度數目。 建立集合的向量索引時，通常需要這樣做。
index_kind No 要用來為向量編製索引的索引型別。 預設值會依向量存放區類型而有所不同。
distance_function No 在此向量搜尋期間執行向量比較時所要使用的距離函式類型。 預設值會依向量存放區類型而有所不同。
local_embedding No 指出屬性是否有與其相關聯的本機內嵌，預設值為 None。
embedding_settings No 內嵌的設定，格式為 service_id 做為索引鍵，PromptExecutionSettings 做為值，預設值為 None。
serialize_function No 如果要用來串行化向量的函式，如果類型不是 list[float | int]，則需要此函式，或需要串行化整個模型。
deserialize_function No 如果要用來還原串行化向量的函式，如果類型不是 list[float | int]，則需要此函式，或需要還原串行化整個模型。

常見的索引種類和距離函式類型會以 和 semantic_kernel.data.DistanceFunction 類別上的semantic_kernel.data.IndexKind靜態值的形式提供。 個別向量存放區實作也可以使用自己的索引類型和距離函式，其中資料庫支援不尋常的類型。

更新插入或取得記錄的所有方法都會使用強型別模型類別。 這些類別上的欄位會以批註裝飾，指出每個欄位的用途。

提示

如需使用屬性的替代方案，請參閱 使用記錄定義來定義架構。

以下是使用這些批注裝飾的模型範例。 根據預設，大部分現成的向量存放區都使用 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 No 可用來提供資料庫中欄位的替代名稱。 請注意，所有連接器都不支援此參數，例如使用 Jackson 的位置，在此情況下，可以使用 Jackson 註釋來指定儲存名稱。

提示

如需哪些連接器支援 storageName 和哪些替代專案的詳細資訊，請參閱 每個連接器的檔。

VectorStoreRecordData

使用此批注來指出您的字段包含不是索引鍵或向量的一般數據。

@VectorStoreRecordData(isFilterable = true)
private String name;

VectorStoreRecordData 參數

參數 必要 描述
isFilterable No 指出當資料庫需要加入每個欄位的索引編製索引時，是否應該為欄位編製索引以進行篩選。 預設為 False。
isFullTextSearchable No 指出是否應該為支援全文搜索的資料庫編製全文搜索索引欄位。 預設為 False。
storageName No 可用來提供資料庫中欄位的替代名稱。 請注意，所有連接器都不支援此參數，例如使用 Jackson 的位置，在此情況下，可以使用 Jackson 註釋來指定儲存名稱。

提示

如需哪些連接器支援 storageName 和哪些替代專案的詳細資訊，請參閱 每個連接器的檔。

VectorStoreRecordVector

使用此批注來指出您的欄位包含向量。

@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;

VectorStoreRecordVector 參數

參數 必要 描述
尺寸 [是] 用於集合建立，否則為選擇性 向量擁有的維度數目。 建立集合的向量索引時，通常需要這樣做。
indexKind No 要用來為向量編製索引的索引型別。 預設值會依向量存放區類型而有所不同。
distanceFunction No 在此向量搜尋期間執行向量比較時所要使用的距離函式類型。 預設值會依向量存放區類型而有所不同。
storageName No 可用來提供資料庫中欄位的替代名稱。 請注意，所有連接器都不支援此參數，例如使用 Jackson 的位置，在此情況下，可以使用 Jackson 註釋來指定儲存名稱。

在和 com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction 列舉上com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind會提供常見的索引種類和距離函式類型。 個別向量存放區實作也可以使用自己的索引類型和距離函式，其中資料庫支援不尋常的類型。

提示

如需哪些連接器支援 storageName 和哪些替代專案的詳細資訊，請參閱 每個連接器的檔。

更多信息即將推出。