定义数据模型（预览版）

警告

语义内核向量存储功能处于预览状态，需要中断性变更的改进可能仍发生在发布前的有限情况下。

概述

语义内核向量存储连接器使用模型第一种方法与数据库交互。

用于更新插入或获取记录的所有方法都使用强类型模型类。 这些类上的属性用指示每个属性的用途的属性进行修饰。

提示

有关使用属性的替代方法，请参阅 使用记录定义定义架构。

提示

有关定义自己的数据模型的替代方法，请参阅 使用矢量存储抽象，而无需定义自己的数据模型。

下面是用这些属性修饰的模型的示例。

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.IndexKind 提供，并且 Microsoft.SemanticKernel.Data.DistanceFunction 类。 单个矢量存储实现还可以使用自己的索引类型和距离函数，其中数据库支持异常类型。

提示

有关哪些连接器支持 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	否	可以直接添加，但在分析模型期间设置。
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]，则需要此函数，或者需要序列化整个模型。
deserialize_function	否	要用于反序列化向量的函数，如果类型不是 list[float | int]，则需要此函数，或者需要反序列化整个模型。

常见的索引类型和距离函数类型作为静态值 semantic_kernel.data.IndexKind 提供，并且 semantic_kernel.data.DistanceFunction 类。 单个矢量存储实现还可以使用自己的索引类型和距离函数，其中数据库支持异常类型。

用于更新插入或获取记录的所有方法都使用强类型模型类。 这些类上的字段用注释进行修饰，这些批注指示每个字段的用途。

提示

有关使用属性的替代方法，请参阅 使用记录定义定义架构。

下面是用这些批注修饰的模型的示例。 默认情况下，大多数开箱即用矢量存储使用 Jackson，因此是确保杰克逊可以序列化模型对象的良好做法，即类可见、具有 getters、构造函数、批注等。

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 注释指定存储名称。

提示

有关哪些连接器支持 storageName 以及哪些替代项可用的详细信息，请参阅 每个连接器的文档。

VectorStoreRecordData

使用此批注可指示字段包含不是键或矢量的常规数据。

@VectorStoreRecordData(isFilterable = true)
private String name;

VectorStoreRecordData 参数

参数	必需	说明
isFilterable	否	指示在数据库需要选择为每个字段编制索引的情况下，是否应为字段编制索引以进行筛选。 默认为 false。
isFullTextSearchable	否	指示是否应为字段编制索引，以便对支持全文搜索的数据库进行全文搜索。 默认为 false。
storageName	否	可用于为数据库中的字段提供备用名称。 请注意，所有连接器都不支持此参数，例如使用杰克逊的位置，在这种情况下，可以使用 Jackson 注释指定存储名称。

提示

有关哪些连接器支持 storageName 以及哪些替代项可用的详细信息，请参阅 每个连接器的文档。

VectorStoreRecordVector

使用此批注指示字段包含向量。

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

VectorStoreRecordVector 参数

参数	必需	说明
dimensions	是用于集合创建，否则为可选	矢量具有的维度数。 为集合创建向量索引时，通常需要这样做。
indexKind	否	要为向量编制索引的索引的类型。 默认值因矢量存储类型而异。
distanceFunction	否	在此向量搜索期间执行矢量比较时要使用的距离函数的类型。 默认值因矢量存储类型而异。
storageName	否	可用于为数据库中的字段提供备用名称。 请注意，所有连接器都不支持此参数，例如使用杰克逊的位置，在这种情况下，可以使用 Jackson 注释指定存储名称。

常见的索引类型和距离函数类型在枚举上com.microsoft.semantickernel.data.vectorstorage.definition.IndexKindcom.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction提供。 单个矢量存储实现还可以使用自己的索引类型和距离函数，其中数据库支持异常类型。

提示

有关哪些连接器支持 storageName 以及哪些替代项可用的详细信息，请参阅 每个连接器的文档。

更多信息即将推出。