Definindo seu modelo de dados (Visualização)

Aviso

A funcionalidade Semantic Kernel Vetor Store está em pré-visualização, e melhorias que exigem alterações de quebra ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Descrição geral

Os conectores do Semantic Kernel Vetor Store usam uma abordagem de modelo inicial 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.

Gorjeta

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

Gorjeta

Para obter uma alternativa à definição de seu próprio modelo de dados, consulte o uso de abstrações do Vetor Store sem definir seu próprio modelo de dados.

Aqui está um exemplo de um modelo que é 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	Necessário	Description
StoragePropertyName	Não	Pode ser usado para fornecer um nome alternativo para a propriedade no banco de dados. Note que este parâmetro não é suportado por todos os conectores, por exemplo, onde alternativas como JsonPropertyNameAttribute é suportado.

Gorjeta

Para obter mais informações sobre quais conectores suportam 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	Necessário	Description
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. A predefinição é falsa.
IsFullTextSearchable	Não	Indica se a propriedade deve ser indexada para pesquisa de texto completo para bancos de dados que oferecem suporte à pesquisa de texto completo. A predefinição é falsa.
StoragePropertyName	Não	Pode ser usado para fornecer um nome alternativo para a propriedade no banco de dados. Note que este parâmetro não é suportado por todos os conectores, por exemplo, onde alternativas como JsonPropertyNameAttribute é suportado.

Gorjeta

Para obter mais informações sobre quais conectores suportam 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	Necessário	Description
Dimensões	Sim para criar coleção, opcional caso contrário	O número de dimensões que o vetor tem. Isso geralmente é 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 armazenamento vetorial.
Função DistânciaDistância	Não	O tipo de função de distância a ser usada ao fazer a comparação vetorial durante a pesquisa vetorial sobre esse vetor. O padrão varia de acordo com o tipo de armazenamento vetorial.
StoragePropertyName	Não	Pode ser usado para fornecer um nome alternativo para a propriedade no banco de dados. Note que este parâmetro não é suportado por todos os conectores, por exemplo, onde alternativas como JsonPropertyNameAttribute é suportado.

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 Vetor Store também podem usar seus próprios tipos de índice e funções de distância, onde o banco de dados suporta tipos incomuns.

Gorjeta

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

Todos os métodos para upsert ou obter registros usam uma classe e uma definição de registro de armazenamento vetorial.

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.

Gorjeta

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

Aqui está um exemplo de um modelo que é 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)]

Gorjeta

A definição de uma classe com essas anotações pode ser feita de várias maneiras, uma das quais é usar 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 se destina a ser usada diretamente.

Parâmetros VectorStoreRecordField

Parâmetro	Necessário	Description
nome	Não	Pode ser adicionado diretamente, mas será definido durante a análise do modelo.
property_type	Não	Deve ser uma cadeia de caracteres, também será derivada durante a análise.

Gorjeta

As anotações são analisadas vectorstoremodel pelo 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	Necessário	Description
has_embedding	Não	Indica se a propriedade tem uma incorporação associada a ela, o padrão é Nenhum.
embedding_property_name	Não	O nome da propriedade que contém a incorporaçã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. A predefinição é falsa.
is_full_text_searchable	Não	Indica se a propriedade deve ser indexada para pesquisa de texto completo para bancos de dados que oferecem suporte à pesquisa de texto completo. A predefinição é falsa.

VectorStoreRecordVectorField

Use esta 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	Necessário	Description
dimensões	Sim para criar coleção, opcional caso contrário	O número de dimensões que o vetor tem. Isso geralmente é 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 armazenamento vetorial.
distance_function	Não	O tipo de função de distância a ser usada ao fazer a comparação vetorial durante a pesquisa vetorial sobre esse vetor. O padrão varia de acordo com o tipo de armazenamento vetorial.
local_embedding	Não	Indica se a propriedade tem uma incorporação local associada a ela, o padrão é Nenhum.
embedding_settings	Não	As configurações para a incorporação, na forma de um ditado com service_id como chave e PromptExecutionSettings como valor, o padrão é None.
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 é necessária, ou todo o modelo precisa 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 é necessária, ou todo o modelo precisa 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 Vetor Store também podem usar seus próprios tipos de índice e funções de distância, onde o banco de dados suporta tipos incomuns.

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

Gorjeta

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

Aqui está um exemplo de um modelo que é decorado com essas anotações. Por padrão, a maioria dos armazenamentos vetoriais prontos para uso usa Jackson, portanto, é uma boa prática para garantir que o objeto 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 esta anotação para indicar que seu campo é a chave do registro.

@VectorStoreRecordKey
private String hotelId;

Parâmetros VectorStoreRecordKey

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

Gorjeta

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

VectorStoreRecordData

Use esta 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	Necessário	Description
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. A predefinição é falsa.
isFullTextSearchable	Não	Indica se o campo deve ser indexado para pesquisa de texto completo para bancos de dados que suportam pesquisa de texto completo. A predefinição é falsa.
nome_do_armazenamento	Não	Pode ser usado para fornecer um nome alternativo para o campo no banco de dados. Observe que este parâmetro não é suportado por todos os conectores, por exemplo, onde Jackson é usado, nesse caso, o nome do armazenamento pode ser especificado usando anotações Jackson.

Gorjeta

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

VectorStoreRecordVector

Use esta 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	Necessário	Description
dimensões	Sim para criar coleção, opcional caso contrário	O número de dimensões que o vetor tem. Isso geralmente é 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 armazenamento vetorial.
distanceFunction	Não	O tipo de função de distância a ser usada ao fazer a comparação vetorial durante a pesquisa vetorial sobre esse vetor. O padrão varia de acordo com o tipo de armazenamento vetorial.
nome_do_armazenamento	Não	Pode ser usado para fornecer um nome alternativo para o campo no banco de dados. Observe que este parâmetro não é suportado por todos os conectores, por exemplo, onde Jackson é usado, nesse caso, o nome do armazenamento pode ser especificado usando anotações Jackson.

Tipos de índice comuns e tipos de função de distância são fornecidos no com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind e com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction enums. As implementações individuais do Vetor Store também podem usar seus próprios tipos de índice e funções de distância, onde o banco de dados suporta tipos incomuns.

Gorjeta

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

Mais informações em breve.