Usando o conector do Repositório de Vetores do MongoDB (vCore) do Azure CosmosDB (versão prévia)

Aviso

A funcionalidade de Armazenamento de Vetores do MongoDB (vCore) do Azure Cosmos DB está em versão prévia, e melhorias que exigem mudanças disruptivas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Aviso

A funcionalidade do Repositório de Vetores do Kernel Semântico está em versão de pré-visualização, e melhorias que exigem mudanças drásticas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Aviso

A funcionalidade do Repositório de Vetores do Kernel Semântico está em versão de pré-visualização, e melhorias que exigem mudanças drásticas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Visão geral

O conector Azure CosmosDB MongoDB Vector Store pode ser usado para acessar e gerenciar dados no MongoDB (vCore) do Azure CosmosDB. O conector tem as seguintes características.

Área de Funcionalidade	Suporte
Mapear coleção para	Coleção MongoDB (vCore) do Azure Cosmos DB + Índice
Tipos de propriedades de chave suportados	corda
Tipos de propriedade de dados com suporte	corda INT longo duplo flutuar decimal Bool Datetime e enumeráveis de cada um desses tipos
Tipos de propriedades de vetor suportadas	Float ReadOnlyMemory<> Inserindo<float> float[]
Tipos de índice com suporte	Hnsw IvfFlat
Funções de distância suportadas	Distância do cosseno DotProductSimilarity Distância Euclidiana
Cláusulas de filtro com suporte	EqualTo
Suporta vários vetores em um registro	Sim
Há suporte para IsIndexed?	Sim
Há suporte paraFullTextIndexed?	Não
"StorageName é suportado?"	Não, use BsonElementAttribute em vez disso. Veja aqui para mais informações.
O HybridSearch é suportado?	Não

Área de Funcionalidade	Suporte
Mapear coleção para	Coleção MongoDB (vCore) do Azure Cosmos DB + Índice
Tipos de propriedades de chave suportados	corda
Tipos de propriedade de dados com suporte	corda INT longo duplo flutuar decimal Bool Datetime e iteráveis de cada um desses tipos
Tipos de propriedades de vetor suportadas	lista[float] lista[int] ndarray
Tipos de índice com suporte	Hnsw IvfFlat
Funções de distância suportadas	Distância do cosseno DotProductSimilarity Distância Euclidiana
Cláusulas de filtro com suporte	EqualTo AnyTagsEqualTo
Suporta vários vetores em um registro	Sim
O IsFilterable está suportado?	Sim
A funcionalidade IsFullTextSearchable é suportada?	Não

Mais informações em breve.

Limitações

Esse conector é compatível com o MongoDB (vCore) do Azure Cosmos DB e não foi projetado para ser compatível com o Azure Cosmos DB MongoDB (RU).

Começando

Adicione o pacote NuGet do conector de Armazenamento de Vetores do MongoDB do Azure CosmosDB ao seu projeto.

dotnet add package Microsoft.SemanticKernel.Connectors.CosmosMongoDB --prerelease

Você pode adicionar o repositório de vetores ao contêiner de injeção de dependência disponível no KernelBuilder ou ao IServiceCollection contêiner de injeção de dependência usando métodos de extensão fornecidos pelo Semantic Kernel.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder();
kernelBuilder.Services
    .AddCosmosMongoVectorStore(connectionString, databaseName);

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCosmosMongoVectorStore(connectionString, databaseName);

Métodos de extensão que não usam parâmetros também são fornecidos. Eles exigem que uma instância de MongoDB.Driver.IMongoDatabase seja registrada separadamente com o contêiner de injeção de dependência MongoDB.Driver.IMongoDatabase.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using MongoDB.Driver;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<IMongoDatabase>(
    sp =>
    {
        var mongoClient = new MongoClient(connectionString);
        return mongoClient.GetDatabase(databaseName);
    });
kernelBuilder.Services.AddCosmosMongoVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using MongoDB.Driver;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IMongoDatabase>(
    sp =>
    {
        var mongoClient = new MongoClient(connectionString);
        return mongoClient.GetDatabase(databaseName);
    });
builder.Services.AddCosmosMongoVectorStore();

Você pode construir uma instância do Repositório de Vetores do MongoDB do Azure CosmosDB diretamente.

using Microsoft.SemanticKernel.Connectors.CosmosMongoDB;
using MongoDB.Driver;

var mongoClient = new MongoClient(connectionString);
var database = mongoClient.GetDatabase(databaseName);
var vectorStore = new CosmosMongoVectorStore(database);

É possível construir uma referência direta a uma coleção nomeada.

using Microsoft.SemanticKernel.Connectors.CosmosMongoDB;
using MongoDB.Driver;

var mongoClient = new MongoClient(connectionString);
var database = mongoClient.GetDatabase(databaseName);
var collection = new CosmosMongoCollection<ulong, Hotel>(
    database,
    "skhotels");

Mapeamento de dados

O conector de Armazenamento de Vetores do MongoDB do Azure CosmosDB fornece um mapeador padrão para mapear dados do modelo de dados para o armazenamento.

Esse mapeador realiza uma conversão direta da lista de propriedades no modelo de dados para os campos no MongoDB do Azure CosmosDB, usando MongoDB.Bson.Serialization para converter para o esquema de armazenamento. Isso significa que o uso do MongoDB.Bson.Serialization.Attributes.BsonElement será suportado se um nome de armazenamento diferente do nome da propriedade do modelo de dados for necessário. A única exceção é a chave do registro que é mapeada para um campo de banco de dados chamado _id, pois todos os registros do CosmosDB MongoDB devem usar esse nome para ids.

Sobrescrição do nome da propriedade

Para propriedades de dados e propriedades de vetor, você pode fornecer nomes de campo de substituição a serem usados no armazenamento que sejam diferentes dos nomes de propriedade no modelo de dados. Isso não é suportado para chaves, pois uma chave tem um nome fixo no MongoDB.

A substituição do nome da propriedade é feita definindo o BsonElement atributo nas propriedades do modelo de dados.

Aqui está um exemplo de um modelo de dados com BsonElement set.

using Microsoft.Extensions.VectorData;

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

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

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

    [BsonElement("hotel_description_embedding")]
    [VectorStoreVector(4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

Começando

Adicione as dependências do Repositório de Vetores do MongoDB do Azure CosmosDB ao seu ambiente. Como o conector do MongoDB do Azure CosmosDB é construído sobre o conector do Atlas do MongoDB e usa o mesmo cliente que esse, você precisa instalar com os seguintes extras:

pip install semantic-kernel[azure, mongo]

Em seguida, você pode criar o repositório de vetores.

from semantic_kernel.connectors.azure_cosmos_db import CosmosMongoStore

# If the right environment settings are set, namely AZURE_COSMOS_DB_MONGODB_CONNECTION_STRING and optionally AZURE_COSMOS_DB_MONGODB_DATABASE_NAME, this is enough to create the Store:
store = CosmosMongoStore()

Como alternativa, você também pode passar seu próprio cliente MongoDB se quiser ter mais controle sobre a construção do cliente.

from pymongo import AsyncMongoClient
from semantic_kernel.connectors.azure_cosmos_db import CosmosMongoStore

client = AsyncMongoClient(...)
store = CosmosMongoStore(mongo_client=client)

Quando um cliente é passado, o Kernel Semântico não fechará a conexão para você, portanto, você precisa garantir que a feche, por exemplo, com uma instrução async with.

Você também pode criar uma coleção diretamente, sem a loja.

from semantic_kernel.connectors.azure_cosmos_db import CosmosMongoCollection

# `Hotel` is a class created with the @vectorstoremodel decorator
collection = CosmosMongoCollection(
    record_type=Hotel,
    collection_name="my_collection"
)

Serialização

Como o conector do Azure CosmosDB para MongoDB precisa de um ditado simples com os campos correspondentes ao índice como entrada, a serialização é muito fácil, ela usa apenas uma chave predeterminada _id, portanto, substituimos a chave do modelo de dados por isso, se ainda não estiver _id.

Para obter mais detalhes sobre esse conceito, consulte a documentação de serialização.

Em breve

Mais informações em breve.