Uso del conector del almacén de vectores noSQL de Azure CosmosDB (versión preliminar)

Artículo
01/23/2025

Advertencia

La funcionalidad Almacén de vectores de kernel semántico está en versión preliminar y las mejoras que requieren cambios importantes pueden producirse en circunstancias limitadas antes de la versión.

Información general

El conector del almacén de vectores noSQL de Azure CosmosDB se puede usar para acceder a los datos y administrarlos en NoSQL de Azure CosmosDB. El conector tiene las siguientes características.

Área de características	Soporte técnico
La colección se asigna a	Contenedor NoSQL de Azure Cosmos DB
Tipos de propiedades de clave admitidos	string AzureCosmosDBNoSQLCompositeKey
Tipos de propiedad de datos admitidos	string int long double FLOAT bool DateTimeOffset y enumerables de cada uno de estos tipos
Tipos de propiedades vectoriales admitidos	ReadOnlyMemory<float> Byte ReadOnlyMemory<> ReadOnlyMemory<sbyte> ReadOnlyMemory<Half>
Tipos de índice admitidos	Plano QuantizedFlat DiskAnn
Funciones de distancia admitidas	CosineSimilarity DotProductSimilarity EuclideanDistance
Cláusulas de filtro admitidas	AnyTagEqualTo EqualTo
Admite varios vectores en un registro	Sí
¿Se admite IsFilterable?	Sí
¿Se admite IsFullTextSearchable?	Sí
¿Se admite StoragePropertyName?	No, use `JsonSerializerOptions` y `JsonPropertyNameAttribute` en su lugar. Consulta aquí para obtener más información.

Limitaciones

Al inicializar CosmosClient manualmente, es necesario especificar CosmosClientOptions.UseSystemTextJsonSerializerWithOptions debido a limitaciones en el serializador predeterminado. Esta opción se puede establecer en JsonSerializerOptions.Default o personalizarse con otras opciones de serializador para satisfacer necesidades de configuración específicas.

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

Introducción

Agregue el paquete NuGet del conector noSQL Del almacén de vectores de Azure CosmosDB al proyecto.

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

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

using Microsoft.SemanticKernel;

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

using Microsoft.SemanticKernel;

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

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

using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<Database>(
    sp =>
    {
        var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
        {
            // When initializing CosmosClient manually, setting this property is required 
            // due to limitations in default serializer. 
            UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
        });

        return cosmosClient.GetDatabase(databaseName);
    });
kernelBuilder.AddAzureCosmosDBNoSQLVectorStore();

using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<Database>(
    sp =>
    {
        var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
        {
            // When initializing CosmosClient manually, setting this property is required 
            // due to limitations in default serializer. 
            UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
        });

        return cosmosClient.GetDatabase(databaseName);
    });
builder.Services.AddAzureCosmosDBNoSQLVectorStore();

Puede construir directamente una instancia de Almacén de vectores noSQL de Azure CosmosDB.

using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

var database = cosmosClient.GetDatabase(databaseName);
var vectorStore = new AzureCosmosDBNoSQLVectorStore(database);

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

using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

var database = cosmosClient.GetDatabase(databaseName);
var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(
    database,
    "skhotels");

Asignación de datos

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

Este asignador realiza una conversión directa de la lista de propiedades en el modelo de datos a los campos de NoSQL de Azure CosmosDB y usa System.Text.Json.JsonSerializer para realizar la conversión al esquema de almacenamiento. Esto significa que se admite el uso de si se requiere un nombre de almacenamiento diferente al nombre de JsonPropertyNameAttribute 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 NoSQL de CosmosDB deben usar este nombre para los identificadores.

También es posible usar una instancia personalizada JsonSerializerOptions con una directiva de nomenclatura de propiedades personalizada. Para habilitar esto, JsonSerializerOptions debe pasarse a la AzureCosmosDBNoSQLVectorStoreRecordCollection construcción en .

using System.Text.Json;
using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var jsonSerializerOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper };

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = jsonSerializerOptions
});

var database = cosmosClient.GetDatabase(databaseName);
var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(
    database,
    "skhotels",
    new() { JsonSerializerOptions = jsonSerializerOptions });

Con el personalizado JsonSerializerOptions anterior que usa SnakeCaseUpper, el siguiente modelo de datos se asignará al siguiente json.

using System.Text.Json.Serialization;
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; }

    [JsonPropertyName("HOTEL_DESCRIPTION_EMBEDDING")]
    [VectorStoreRecordVector(4, DistanceFunction.EuclideanDistance, IndexKind.QuantizedFlat)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": 1,
    "HOTEL_NAME": "Hotel Happy",
    "DESCRIPTION": "A place where everyone can be happy.",
    "HOTEL_DESCRIPTION_EMBEDDING": [0.9, 0.1, 0.1, 0.1],
}

Uso de la clave de partición

En el conector de Azure Cosmos DB para NoSQL, la propiedad de clave de partición tiene como valor predeterminado la propiedad de clave, id. La propiedad PartitionKeyPropertyName de AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> clase permite especificar una propiedad diferente como clave de partición.

La clase AzureCosmosDBNoSQLVectorStoreRecordCollection admite dos tipos clave: string y AzureCosmosDBNoSQLCompositeKey. El AzureCosmosDBNoSQLCompositeKey consta de RecordKey y PartitionKey.

Si no se establece la propiedad de clave de partición (y se utiliza la propiedad de clave predeterminada), se pueden usar claves string para operaciones con registros de bases de datos. Sin embargo, si se especifica una propiedad de clave de partición, se recomienda usar AzureCosmosDBNoSQLCompositeKey para proporcionar tanto los valores de la clave como los de la clave de partición.

Especifique el nombre de la propiedad de clave de partición:

var options = new AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<Hotel>
{
    PartitionKeyPropertyName = nameof(Hotel.HotelName)
};

var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(database, "collection-name", options) 
    as IVectorStoreRecordCollection<AzureCosmosDBNoSQLCompositeKey, Hotel>;

Obtenga con la clave de partición:

var record = await collection.GetAsync(new AzureCosmosDBNoSQLCompositeKey("hotel-id", "hotel-name"));

Próximamente

Más información próximamente.

Próximamente

Más información próximamente.

Compartir a través de

Uso del conector del almacén de vectores noSQL de Azure CosmosDB (versión preliminar)

Información general

Limitaciones

Introducción

Asignación de datos

Uso de la clave de partición

Próximamente

Próximamente

Recursos adicionales