Definindo seu modelo de dados (versão prévia)

Aviso

A funcionalidade do Repositório de Vetores do Kernel Semântico está em versão prévia e as melhorias que exigem alterações significativas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Visão geral

Os conectores do Repositório de Vetores do Kernel Semântico usam uma abordagem de primeiro modelo para interagir com bancos de dados.

Todos os métodos para upsert ou obter registros usam classes de modelo fortemente tipadas. As propriedades nessas classes são decoradas com atributos que indicam a finalidade de cada propriedade.

Dica

Para obter uma alternativa ao uso de atributos, consulte definição do esquema com uma definição de registro.

Dica

Para obter uma alternativa para definir seu próprio modelo de dados, consulte o uso de abstrações do Repositório de vetores sem definir seu próprio modelo de dados.

Aqui está um exemplo de um modelo decorado com esses atributos.

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; }
}

Atributos

VectorStoreRecordKeyAttribute

Use esse atributo para indicar que sua propriedade é a chave do registro.

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

Parâmetros VectorStoreRecordKeyAttribute

Parâmetro	Obrigatório	Descrição
StoragePropertyName	Não	Pode ser usado para fornecer um nome alternativo para a propriedade no banco de dados. Observe que esse parâmetro não é compatível com todos os conectores, por exemplo, onde alternativas como JsonPropertyNameAttribute são suportadas.

Dica

Para obter mais informações sobre quais conectores dão suporte a StoragePropertyName e quais alternativas estão disponíveis, consulte a documentação de cada conector.

VectorStoreRecordDataAttribute

Use esse atributo para indicar que sua propriedade contém dados gerais que não são uma chave ou um vetor.

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

Parâmetros VectorStoreRecordDataAttribute

Parâmetro	Obrigatório	Descrição
IsFilterable	Não	Indica se a propriedade deve ser indexada para filtragem nos casos em que um banco de dados requer a aceitação da indexação por propriedade. Padrão é false
ÉFullTextSearchable	Não	Indica se a propriedade deve ser indexada para pesquisa de texto completo para bancos de dados que dão suporte à pesquisa de texto completo. Padrão é false
StoragePropertyName	Não	Pode ser usado para fornecer um nome alternativo para a propriedade no banco de dados. Observe que esse parâmetro não é compatível com todos os conectores, por exemplo, onde alternativas como JsonPropertyNameAttribute são suportadas.

Dica

Para obter mais informações sobre quais conectores dão suporte a StoragePropertyName e quais alternativas estão disponíveis, consulte a documentação de cada conector.

VectorStoreRecordVectorAttribute

Use esse atributo para indicar que sua propriedade contém um vetor.

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

Parâmetros VectorStoreRecordVectorAttribute

Parâmetro	Obrigatório	Descrição
Dimensões	Sim para criação de coleção, caso contrário, opcional	O número de dimensões que o vetor tem. Isso normalmente é necessário ao criar um índice de vetor para uma coleção.
IndexKind	Não	O tipo de índice com o qual indexar o vetor. O padrão varia de acordo com o tipo de repositório de vetores.
Função de distância	Não	O tipo de função de distância a ser usada ao fazer a comparação de vetores durante a pesquisa vetorial sobre esse vetor. O padrão varia de acordo com o tipo de repositório de vetores.
StoragePropertyName	Não	Pode ser usado para fornecer um nome alternativo para a propriedade no banco de dados. Observe que esse parâmetro não é compatível com todos os conectores, por exemplo, onde alternativas como JsonPropertyNameAttribute são suportadas.

Tipos de índice comuns e tipos de função de distância são fornecidos como valores estáticos nas Microsoft.SemanticKernel.Data.IndexKind classes e Microsoft.SemanticKernel.Data.DistanceFunction . As implementações individuais do Repositório de Vetores também podem usar seus próprios tipos de índice e funções de distância, em que o banco de dados dá suporte a tipos incomuns.

Dica

Para obter mais informações sobre quais conectores dão suporte a StoragePropertyName e quais alternativas estão disponíveis, consulte a documentação de cada conector.

Todos os métodos para upsert ou get records usam uma classe e uma definição de registro de armazenamento de vetor.

Isso pode ser feito definindo sua própria classe com anotações para os campos ou usando uma classe/tipo em combinação com uma definição de registro. Duas coisas precisam ser feitas para uma classe, a primeira é adicionar as anotações com os tipos de campo, a segunda é decorar a classe com o vectorstoremodel decorador.

Dica

Para obter a abordagem alternativa usando uma definição de registro, consulte definição do esquema com uma definição de registro.

Aqui está um exemplo de um modelo decorado com essas anotações.

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)]

Dica

A definição de uma classe com essas anotações pode ser feita de várias maneiras, uma das quais é usando o dataclasses módulo em Python, mostrado aqui. Este exemplo mostra outras abordagens (usando Pydantic BaseModels e classes vanilla python) também.

Anotações

Há três tipos de anotações a serem usadas e elas têm uma classe base comum.

VectorStoreRecordField

Esta é a classe base para todas as anotações, não deve ser usada diretamente.

Parâmetros VectorStoreRecordField

Parâmetro	Obrigatório	Descrição
name	Não	Pode ser adicionado diretamente, mas será definido durante a análise do modelo.
property_type	Não	Deve ser uma string, também será derivada durante a análise.

Dica

As anotações são analisadas pelo vectorstoremodel decorador e uma das coisas que ele faz é criar uma definição de registro para a classe, portanto, não é necessário instanciar uma classe de campo quando nenhum parâmetro é definido, o campo pode ser anotado apenas com a classe, assim:

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Use essa anotação para indicar que esse atributo é a chave do registro.

VectorStoreRecordKeyField()

Parâmetros VectorStoreRecordKeyField

Nenhum outro parâmetro fora da classe base é definido.

VectorStoreRecordDataField

Use essa anotação para indicar que seu atributo contém dados gerais que não são uma chave ou um vetor.

VectorStoreRecordDataField(is_filterable=True)

Parâmetros VectorStoreRecordDataField

Parâmetro	Obrigatório	Descrição
has_embedding	Não	Indica se a propriedade tem uma inserção associada a ela, o padrão é Nenhum.
embedding_property_name	Não	O nome da propriedade que contém a inserção, o padrão é Nenhum.
is_filterable	Não	Indica se a propriedade deve ser indexada para filtragem nos casos em que um banco de dados requer a aceitação da indexação por propriedade. Padrão é false
is_full_text_searchable	Não	Indica se a propriedade deve ser indexada para pesquisa de texto completo para bancos de dados que dão suporte à pesquisa de texto completo. Padrão é false

VectorStoreRecordVectorField

Use essa anotação para indicar que seu atributo contém um vetor.

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

Parâmetros VectorStoreRecordVectorField

Parâmetro	Obrigatório	Descrição
dimensões	Sim para criação de coleção, caso contrário, opcional	O número de dimensões que o vetor tem. Isso normalmente é necessário ao criar um índice de vetor para uma coleção.
index_kind	Não	O tipo de índice com o qual indexar o vetor. O padrão varia de acordo com o tipo de repositório de vetores.
distance_function	Não	O tipo de função de distância a ser usada ao fazer a comparação de vetores durante a pesquisa vetorial sobre esse vetor. O padrão varia de acordo com o tipo de repositório de vetores.
local_embedding	Não	Indica se a propriedade tem uma inserção local associada a ela, o padrão é Nenhum.
embedding_settings	Não	As configurações para a inserção, na forma de um dicionário com service_id como chave e PromptExecutionSettings como valor, o padrão é Nenhum.
serialize_function	Não	A função a ser usada para serializar o vetor, se o tipo não for uma lista[float | int], essa função será necessária ou todo o modelo precisará ser serializado.
deserialize_function	Não	A função a ser usada para desserializar o vetor, se o tipo não for uma lista[float | int], essa função será necessária ou todo o modelo precisará ser desserializado.

Tipos de índice comuns e tipos de função de distância são fornecidos como valores estáticos nas semantic_kernel.data.IndexKind classes e semantic_kernel.data.DistanceFunction . As implementações individuais do Repositório de Vetores também podem usar seus próprios tipos de índice e funções de distância, em que o banco de dados dá suporte a tipos incomuns.

Todos os métodos para upsert ou obter registros usam classes de modelo fortemente tipadas. Os campos nessas classes são decorados com anotações que indicam a finalidade de cada campo.

Dica

Para obter uma alternativa ao uso de atributos, consulte definição do esquema com uma definição de registro.

Aqui está um exemplo de um modelo decorado com essas anotações. Por padrão, a maioria dos armazenamentos de vetores prontos para uso usa Jackson, portanto, é uma boa prática garantir que o objeto de modelo possa ser serializado por Jackson, ou seja, a classe é visível, tem getters, construtor, anotações, etc.

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; }
}

Anotações

VectorStoreRecordKey

Use essa anotação para indicar que seu campo é a chave do registro.

@VectorStoreRecordKey
private String hotelId;

Parâmetros VectorStoreRecordKey

Parâmetro	Obrigatório	Descrição
storageName	Não	Pode ser usado para fornecer um nome alternativo para o campo no banco de dados. Observe que esse parâmetro não é suportado por todos os conectores, por exemplo, onde Jackson é usado, nesse caso, o nome de armazenamento pode ser especificado usando anotações Jackson.

Dica

Para obter mais informações sobre quais conectores dão suporte a storageName e quais alternativas estão disponíveis, consulte a documentação de cada conector.

VectorStoreRecordData

Use essa anotação para indicar que seu campo contém dados gerais que não são uma chave ou um vetor.

@VectorStoreRecordData(isFilterable = true)
private String name;

Parâmetros VectorStoreRecordData

Parâmetro	Obrigatório	Descrição
isFiltrável	Não	Indica se o campo deve ser indexado para filtragem nos casos em que um banco de dados requer a aceitação da indexação por campo. Padrão é false
isFullTextSearchable	Não	Indica se o campo deve ser indexado para pesquisa de texto completo para bancos de dados que dão suporte à pesquisa de texto completo. Padrão é false
storageName	Não	Pode ser usado para fornecer um nome alternativo para o campo no banco de dados. Observe que esse parâmetro não é suportado por todos os conectores, por exemplo, onde Jackson é usado, nesse caso, o nome de armazenamento pode ser especificado usando anotações Jackson.

Dica

Para obter mais informações sobre quais conectores dão suporte a storageName e quais alternativas estão disponíveis, consulte a documentação de cada conector.

VectorStoreRecordVector

Use essa anotação para indicar que seu campo contém um vetor.

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

Parâmetros VectorStoreRecordVector

Parâmetro	Obrigatório	Descrição
dimensões	Sim para criação de coleção, caso contrário, opcional	O número de dimensões que o vetor tem. Isso normalmente é necessário ao criar um índice de vetor para uma coleção.
tipo de índice	Não	O tipo de índice com o qual indexar o vetor. O padrão varia de acordo com o tipo de repositório de vetores.
função distância	Não	O tipo de função de distância a ser usada ao fazer a comparação de vetores durante a pesquisa vetorial sobre esse vetor. O padrão varia de acordo com o tipo de repositório de vetores.
storageName	Não	Pode ser usado para fornecer um nome alternativo para o campo no banco de dados. Observe que esse parâmetro não é suportado por todos os conectores, por exemplo, onde Jackson é usado, nesse caso, o nome de armazenamento pode ser especificado usando anotações Jackson.

Tipos de índice comuns e tipos de função de distância são fornecidos nas com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind enumerações e com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction . As implementações individuais do Repositório de Vetores também podem usar seus próprios tipos de índice e funções de distância, em que o banco de dados dá suporte a tipos incomuns.

Dica

Para obter mais informações sobre quais conectores dão suporte a storageName e quais alternativas estão disponíveis, consulte a documentação de cada conector.

Mais informações em breve.