Определение модели данных (предварительная версия)

Все методы для upsert или получения записей используют строго типизированные классы моделей. Свойства этих классов декорируются атрибутами, указывающими назначение каждого свойства.

Ниже приведен пример модели, украшенной этими атрибутами.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public ulong HotelId { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true)]
    public string Description { get; set; }

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

    [VectorStoreData(IsIndexed = true)]
    public string[] Tags { get; set; }
}

Атрибуты

VectorStoreKeyAttribute

Используйте этот атрибут, чтобы указать, что свойство является ключом записи.

[VectorStoreKey]
public ulong HotelId { get; set; }

Параметры VectorStoreKeyAttribute

VectorStoreDataAttribute

Используйте этот атрибут, чтобы указать, что свойство содержит общие данные, которые не являются ключом или вектором.

[VectorStoreData(IsIndexed = true)]
public string HotelName { get; set; }

Параметры VectorStoreDataAttribute

VectorStoreVectorAttribute

Используйте этот атрибут, чтобы указать, что свойство содержит вектор.

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

Также можно использовать VectorStoreVectorAttribute свойства, которые не имеют векторного типа, например свойство типа string. Когда свойство декорируется таким образом, Microsoft.Exntesions.AI.IEmbeddingGenerator экземпляр должен быть предоставлен в хранилище векторов. При изменении записи текст, который находится в свойстве, автоматически преобразуется в string вектор и сохраняется в качестве вектора в базе данных. Невозможно получить вектор с помощью этого механизма.

[VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
public string DescriptionEmbedding { get; set; }

Параметры VectorStoreVectorAttribute

Распространенные типы индексов и типы функций расстояния предоставляются в виде статических значений Microsoft.SemanticKernel.Data.IndexKind в классах и Microsoft.SemanticKernel.Data.DistanceFunction классах. Отдельные реализации векторного хранилища также могут использовать собственные типы индексов и функции расстояния, где база данных поддерживает необычные типы.

Все методы для 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)]

Заметки

Используется три типа заметок, и они имеют общий базовый класс.

VectorStoreRecordField

Это базовый класс для всех заметок, он не предназначен для непосредственного использования.

Параметры VectorStoreRecordField

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Используйте эту заметку, чтобы указать, что этот атрибут является ключом записи.

VectorStoreRecordKeyField()

Параметры VectorStoreRecordKeyField

Другие параметры за пределами базового класса не определены.

VectorStoreRecordDataField

Используйте эту заметку, чтобы указать, что атрибут содержит общие данные, которые не являются ключом или вектором.

VectorStoreRecordDataField(is_filterable=True)

Параметры VectorStoreRecordDataField

VectorStoreRecordVectorField

Используйте эту заметку, чтобы указать, что атрибут содержит вектор.

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

Параметры VectorStoreRecordVectorField

Распространенные типы индексов и типы функций расстояния предоставляются в виде статических значений semantic_kernel.data.IndexKind в классах и semantic_kernel.data.DistanceFunction классах. Отдельные реализации векторного хранилища также могут использовать собственные типы индексов и функции расстояния, где база данных поддерживает необычные типы.

Все методы для upsert или получения записей используют строго типизированные классы моделей. Поля этих классов украшены заметками, указывающими назначение каждого поля.

Ниже приведен пример модели, украшенной этими заметками. По умолчанию большинство векторных векторов коробки используют Джексон, поэтому рекомендуется, чтобы объект модели можно сериализовать Джексоном, т. е. класс виден, имеет методы получения, конструктор, заметки и т. д.

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

VectorStoreRecordData

Используйте эту заметку, чтобы указать, что поле содержит общие данные, которые не являются ключом или вектором.

@VectorStoreRecordData(isFilterable = true)
private String name;

Параметры VectorStoreRecordData

VectorStoreRecordVector

Используйте эту заметку, чтобы указать, что поле содержит вектор.

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

Параметры VectorStoreRecordVector

Общие типы индексов и типы функций расстояния предоставляются в com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind перечислениях и com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction перечислениях. Отдельные реализации векторного хранилища также могут использовать собственные типы индексов и функции расстояния, где база данных поддерживает необычные типы.

Дополнительные сведения в ближайшее время.