Определение модели данных (предварительная версия)
Предупреждение
Функции хранилища векторов семантического ядра доступны в предварительной версии и улучшения, требующие критических изменений, могут по-прежнему возникать в ограниченных обстоятельствах перед выпуском.
Обзор
Соединители хранилища векторов семантического ядра используют модель первого подхода к взаимодействию с базами данных.
Все методы для upsert или получения записей используют строго типизированные классы моделей. Свойства этих классов декорируются атрибутами, указывающими назначение каждого свойства.
Совет
Для альтернативы использованию атрибутов см . определение схемы с определением записи.
Совет
Для альтернативы определению собственной модели данных см. сведения об использовании абстракций Vector Store без определения собственной модели данных.
Ниже приведен пример модели, украшенной этими атрибутами.
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.IndexKind в классах и Microsoft.SemanticKernel.Data.DistanceFunction классах.
Отдельные реализации векторного хранилища также могут использовать собственные типы индексов и функции расстояния, где база данных поддерживает необычные типы.
Совет
Дополнительные сведения о том, какие соединители поддерживают 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)]
Совет
Определение класса с помощью этих заметок можно сделать несколькими способами, одним из которых является использование dataclasses модуля в Python, показанного здесь. В этом примере также показаны другие подходы (с помощью Pydantic BaseModels и ванильного python-классов).
Заметки
Используется три типа заметок, и они имеют общий базовый класс.
VectorStoreRecordField
Это базовый класс для всех заметок, он не предназначен для непосредственного использования.
Параметры VectorStoreRecordField
| Параметр | Обязательное поле | Description |
|---|---|---|
| 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
| Параметр | Обязательное поле | Описание |
|---|---|---|
| dimensions | Да для создания коллекции, необязательно в противном случае | Число измерений, которые имеет вектор. Обычно это необходимо при создании векторного индекса для коллекции. |
| index_kind | No | Тип индекса для индексирования вектора. Значение по умолчанию зависит от типа векторного хранилища. |
| distance_function | No | Тип функции расстояния, используемой при сравнении векторов во время векторного поиска по этому вектору. Значение по умолчанию зависит от типа векторного хранилища. |
| local_embedding | No | Указывает, имеет ли свойство локальную внедренную связь с ним, значение по умолчанию — None. |
| embedding_settings | No | Параметры внедрения в виде дикта с service_id в качестве ключа и PromptExecutionSettings в качестве значения по умолчанию — None. |
| serialize_function | No | Функция, используемая для сериализации вектора, если тип не является списком[float | int] этой функцией, или необходимо сериализовать всю модель. |
| deserialize_function | No | Функция, используемая для десериализации вектора, если тип не является списком[float | int] этой функцией, или необходимо десериализировать всю модель. |
Распространенные типы индексов и типы функций расстояния предоставляются в виде статических значений 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
| Параметр | Обязательное поле | Описание |
|---|---|---|
| storageName | No | Можно использовать для указания альтернативного имени поля в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где используется Джексон, в этом случае имя хранилища можно указать с помощью заметок Джексона. |
Совет
Дополнительные сведения о том, какие соединители поддерживают storageName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.
VectorStoreRecordData
Используйте эту заметку, чтобы указать, что поле содержит общие данные, которые не являются ключом или вектором.
@VectorStoreRecordData(isFilterable = true)
private String name;
Параметры VectorStoreRecordData
| Параметр | Обязательное поле | Описание |
|---|---|---|
| isFilterable | No | Указывает, следует ли индексировать поле для фильтрации в случаях, когда для базы данных требуется выбрать индексирование для каждого поля. По умолчанию — false. |
| isFullTextSearchable | No | Указывает, следует ли индексировать поле для полнотекстового поиска баз данных, поддерживающих полнотекстовый поиск. По умолчанию — false. |
| storageName | No | Можно использовать для указания альтернативного имени поля в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где используется Джексон, в этом случае имя хранилища можно указать с помощью заметок Джексона. |
Совет
Дополнительные сведения о том, какие соединители поддерживают storageName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.
VectorStoreRecordVector
Используйте эту заметку, чтобы указать, что поле содержит вектор.
@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;
Параметры VectorStoreRecordVector
| Параметр | Обязательное поле | Описание |
|---|---|---|
| dimensions | Да для создания коллекции, необязательно в противном случае | Число измерений, которые имеет вектор. Обычно это необходимо при создании векторного индекса для коллекции. |
| indexKind | No | Тип индекса для индексирования вектора. Значение по умолчанию зависит от типа векторного хранилища. |
| distanceFunction | No | Тип функции расстояния, используемой при сравнении векторов во время векторного поиска по этому вектору. Значение по умолчанию зависит от типа векторного хранилища. |
| storageName | No | Можно использовать для указания альтернативного имени поля в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где используется Джексон, в этом случае имя хранилища можно указать с помощью заметок Джексона. |
Общие типы индексов и типы функций расстояния предоставляются в com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind перечислениях и com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction перечислениях.
Отдельные реализации векторного хранилища также могут использовать собственные типы индексов и функции расстояния, где база данных поддерживает необычные типы.
Совет
Дополнительные сведения о том, какие соединители поддерживают storageName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.
Дополнительные сведения в ближайшее время.