Uso del conector de Vector Store de Azure CosmosDB MongoDB (vCore) (versión preliminar)

Advertencia

La funcionalidad de almacenamiento de vectores del kernel semántico está en versión preliminar y es posible que las mejoras que requieren cambios significativos se realicen en circunstancias limitadas antes del lanzamiento.

Información general

El conector del almacén de vectores para MongoDB de Azure CosmosDB puede utilizarse para acceder y administrar datos en Azure CosmosDB MongoDB (vCore). El conector tiene las siguientes características.

Área de funciones	Soporte técnico
La colección se corresponde con	Colección MongoDB (vCore) de Azure Cosmos DB + Índice
Tipos de propiedades de clave admitidos	string
Tipos de propiedad de datos admitidos	cadena int largo doble flotador decimal bool FechaHora y enumerables de cada uno de estos tipos
Tipos de propiedades vectoriales admitidos	MemoriaDeSoloLectura<flotante> ReadOnlyMemory<double>
Tipos de índice admitidos	Hnsw FertilizaciónInVitroPlano
Funciones de distancia admitidas	CosineDistance DotProductSimilarity EuclideanDistance
Cláusulas de filtro admitidas	EqualTo
Admite varios vectores en un registro	Sí
¿Se admite IsFilterable?	Sí
¿Se admite IsFullTextSearchable?	No
¿Se admite StoragePropertyName?	No, use BsonElementAttribute en su lugar. Consulta aquí para obtener más información.
¿Se admite HybridSearch?	No

Área de funciones	Soporte técnico
La colección se asigna a	Colección MongoDB (vCore) de Azure Cosmos DB + Índice
Tipos de propiedades de clave admitidos	string
Tipos de propiedad de datos admitidos	string int largo doble flotar decimal bool FechaHora y iterables de cada uno de estos tipos
Tipos de propiedades vectoriales admitidos	lista[flotante] lista[int] ndarray
Tipos de índice admitidos	Hnsw IvfPlano
Funciones de distancia admitidas	CosineDistance DotProductSimilarity EuclideanDistance
Cláusulas de filtro admitidas	EqualTo AnyTagsEqualTo
Admite varios vectores en un registro	Sí
¿Se admite IsFilterable?	Sí
¿Se admite IsFullTextSearchable?	No

Más información próximamente.

Limitaciones

Este conector es compatible con MongoDB (núcleo virtual) de Azure Cosmos DB y no es diseñado para ser compatible con MongoDB (RU) de Azure Cosmos DB.

Introducción

Agregue el paquete NuGet del conector del almacén de vectores de MongoDB de Azure CosmosDB a tu proyecto.

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

Puede agregar el almacén de vectores al contenedor de inserción de dependencias disponible en KernelBuilder o al contenedor de inserción de dependencias IServiceCollection mediante métodos de extensión proporcionados por el Kernel Semántico.

using Microsoft.SemanticKernel;

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

using Microsoft.SemanticKernel;

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

También se proporcionan métodos de extensión que no toman parámetros. Estos requieren que una instancia de MongoDB.Driver.IMongoDatabase se registre por separado con el contenedor de inserción de dependencias.

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.AddAzureCosmosDBMongoDBVectorStore();

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.AddAzureCosmosDBMongoDBVectorStore();

Puede construir directamente una instancia de Almacén vectorial de MongoDB de Azure CosmosDB.

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

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

Es posible construir una referencia directa a una colección con nombre.

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

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

Asignación de datos

El conector del almacén de vectores de MongoDB de Azure CosmosDB proporciona un asignador predeterminado al asignar datos del modelo de datos al almacenamiento.

Este asignador realiza una conversión directa de la lista de propiedades del modelo de datos a los campos de Azure CosmosDB MongoDB y usa MongoDB.Bson.Serialization para convertir al esquema de almacenamiento. Esto significa que se admite el uso de MongoDB.Bson.Serialization.Attributes.BsonElement si se requiere un nombre de almacenamiento diferente al nombre de la propiedad del modelo de datos. La única excepción es la clave del registro que se asigna a un campo de base de datos denominado _id, ya que todos los registros de MongoDB de CosmosDB deben usar este nombre para los identificadores.

Anulación del nombre de propiedad

En el caso de las propiedades de datos y las propiedades vectoriales, puede proporcionar nombres de campo alternativos para su utilización en un almacenamiento que difiere respecto a los nombres de propiedad del modelo de datos. Esto no se admite para las claves, ya que una clave tiene un nombre fijo en MongoDB.

La anulación del nombre de propiedad se realiza al establecer el atributo BsonElement en las propiedades del modelo de datos.

Este es un ejemplo de un modelo de datos con BsonElement establecido.

using Microsoft.Extensions.VectorData;

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

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

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

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

Comenzar

Agregue las dependencias de la tienda de vectores de MongoDB de Azure CosmosDB a tu entorno. Dado que el conector mongoDB de Azure CosmosDB se basa en el conector de MongoDB Atlas y usa el mismo cliente que ese, debe instalar con estos extras:

pip install semantic-kernel[azure, mongo]

A continuación, puede crear el almacén de vectores.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBStore

# 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 = AzureCosmosDBforMongoDBStore()

Como alternativa, también puede pasar su propio cliente de MongoDB si desea tener más control sobre la construcción del cliente.

from pymongo import AsyncMongoClient
from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBStore

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

Cuando se pasa un cliente, el Kernel Semántico no cerrará la conexión por usted, por lo que debe asegurarse de cerrarla, por ejemplo, con una instrucción async with.

También puede crear una colección directamente, sin el almacén.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBCollection

# `hotel` is a class created with the @vectorstoremodel decorator
collection = AzureCosmosDBforMongoDBCollection(
    collection_name="my_collection",
    data_model_type=hotel
)

Serialización

Dado que el conector de Azure CosmosDB para MongoDB necesita un dict sencillo con los campos correspondientes al índice como entrada, la serialización es bastante fácil, solo usa una clave predeterminada _id, por lo que reemplazamos la clave del modelo de datos por eso si aún no está _id.

Para obtener más información sobre este concepto, consulte la documentación de serialización.

Próximamente

Más información próximamente.