Usando o conector de Armazém Vetorial NoSQL do Azure CosmosDB (Pré-visualização)

Aviso

A funcionalidade de Repositório Vetorial NoSQL do Azure CosmosDB está em pré-visualização, e as melhorias que exigem alterações disruptivas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Aviso

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

Aviso

Descrição geral

O conector do Azure CosmosDB NoSQL Vetor Store pode ser usado para acessar e gerenciar dados no Azure CosmosDB NoSQL. O conector tem as seguintes características.

Área de funcionalidades	Suporte
Mapas da coleção para	Contêiner NoSQL do Azure Cosmos DB
Tipos de propriedade de chave suportados	corda CosmosNoSqlCompositeKey
Tipos de propriedade de dados suportados	corda Int longo duplo flutuante booleano Desvio de Data e Hora e enumeráveis de cada um destes tipos
Tipos de propriedade vetorial suportados	Float ReadOnlyMemory<> Flutuador de incorporação<> flutuar[] Byte ReadOnlyMemory<> Byte de incorporação<> byte[] Sbyte ReadOnlyMemory<> Incorporação<sbyte> sbyte[]
Tipos de índice suportados	Apartamento QuantizedFlat DiskAnn
Funções de distância suportadas	Similaridade do Cosseno DotProductSimilarity Distância Euclidiana
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
IsIndexed é suportado?	Sim
"É suportado IsFullTextIndexed?"	Sim
Está StorageName suportado?	Não, use `JsonSerializerOptions` e `JsonPropertyNameAttribute` em vez disso. Veja aqui mais informações.
O HybridSearch é suportado?	Sim

Limitações

Ao inicializar CosmosClient manualmente, é necessário especificar CosmosClientOptions.UseSystemTextJsonSerializerWithOptions devido a limitações no serializador padrão. Essa opção pode ser definida como JsonSerializerOptions.Default ou personalizada com outras opções do serializador para atender às necessidades específicas de configuração.

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

Começar

Adicione o pacote NuGet do conector do Azure CosmosDB NoSQL Vector Store ao seu projeto.

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

Você pode adicionar o armazenamento vetorial ao contêiner de injeção de dependência disponível no KernelBuilder ou ao contêiner de IServiceCollection 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
    .AddCosmosNoSqlVectorStore(connectionString, databaseName);

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

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCosmosNoSqlVectorStore(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 Microsoft.Azure.Cosmos.Database seja registada separadamente no contêiner de injeção de dependências.

using System.Text.Json;
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.Services.AddCosmosNoSqlVectorStore();

using System.Text.Json;
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.AddCosmosNoSqlVectorStore();

Você pode construir uma instância do Azure CosmosDB NoSQL Vetor Store diretamente.

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

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 CosmosNoSqlVectorStore(database);

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

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

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 CosmosNoSqlCollection<string, Hotel>(
    database,
    "skhotels");

Mapeamento de dados

O conector do Azure CosmosDB NoSQL Vetor Store fornece um mapeador padrão ao mapear do modelo de dados para o armazenamento.

Esse mapeador faz uma conversão direta da lista de propriedades no modelo de dados para os campos no Azure CosmosDB NoSQL e usa System.Text.Json.JsonSerializer para converter para o esquema de armazenamento. Isso significa que o uso do JsonPropertyNameAttribute é suportado se for necessário um nome de armazenamento diferente ao nome da propriedade do modelo de dados. A única exceção é a chave do registro que é mapeada para um campo de banco de dados chamado id, já que todos os registros NoSQL do CosmosDB devem usar esse nome para ids.

Também é possível usar uma instância personalizada JsonSerializerOptions com uma política de nomenclatura de propriedade personalizada. Para permitir isso, o JsonSerializerOptions deve ser passado para o CosmosNoSqlCollection durante a construção.

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

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 CosmosNoSqlCollection<string, Hotel>(
    database,
    "skhotels",
    new() { JsonSerializerOptions = jsonSerializerOptions });

Usando o JsonSerializerOptions personalizado acima que está utilizando SnakeCaseUpper, o modelo de dados a seguir será mapeado para o json abaixo.

using System.Text.Json.Serialization;
using Microsoft.Extensions.VectorData;

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

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

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

    [JsonPropertyName("HOTEL_DESCRIPTION_EMBEDDING")]
    [VectorStoreVector(4, DistanceFunction = DistanceFunction.EuclideanDistance, IndexKind = 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],
}

Usando a chave de partição

No conector do Azure Cosmos DB para NoSQL, a propriedade da chave de partição assume como padrão a propriedade da chave - id. A propriedade PartitionKeyPropertyName em CosmosNoSqlCollectionOptions classe permite especificar uma propriedade diferente como a chave de partição.

A classe CosmosNoSqlCollection suporta dois tipos de chave: string e CosmosNoSqlCompositeKey. O CosmosNoSqlCompositeKey consiste em RecordKey e PartitionKey.

Se a propriedade da chave de partição não estiver definida (e a propriedade de chave padrão for usada), string chaves poderão ser usadas para operações com registros de banco de dados. No entanto, se uma propriedade de chave de partição for especificada, é recomendável usar CosmosNoSqlCompositeKey para fornecer tanto a chave quanto os valores da chave de partição.

Especifique o nome da propriedade da chave de partição:

var options = new CosmosNoSqlCollectionOptions
{
    PartitionKeyPropertyName = nameof(Hotel.HotelName)
};

var collection = new CosmosNoSqlCollection<string, Hotel>(database, "collection-name", options) 
    as VectorStoreCollection<CosmosNoSqlCompositeKey, Hotel>;

Obter usando a chave de partição:

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

Descrição geral

O conector do Azure CosmosDB NoSQL Vetor Store pode ser usado para acessar e gerenciar dados no Azure CosmosDB NoSQL. O conector tem as seguintes características.

Área de funcionalidades	Suporte
Mapas da coleção para	Contêiner NoSQL do Azure Cosmos DB
Tipos de propriedade de chave suportados	corda CosmosNoSqlCompositeKey
Tipos de propriedade de dados suportados	corda Int longo duplo flutuante booleano Desvio de Data e Hora e iteráveis de cada um desses tipos
Tipos de propriedade vetorial suportados	lista[float] lista[int] ndarray
Tipos de índice suportados	Apartamento QuantizedFlat DiskAnn
Funções de distância suportadas	Similaridade do Cosseno DotProductSimilarity Distância Euclidiana
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
Está is_filterable suportado?	Sim
A pesquisa em texto completo é suportada?	Sim
O HybridSearch é suportado?	Não

Começar

Adicione o pacote extra do Azure ao seu projeto.

pip install semantic-kernel[azure]

Em seguida, você pode criar uma instância do Azure CosmosDB NoSQL Vetor Store diretamente. Isso lê determinadas variáveis de ambiente para configurar a conexão com o Azure CosmosDB NoSQL:

AZURE_COSMOS_DB_NO_SQL_URL
AZURE_COSMOS_DB_NO_SQL_DATABASE_NAME

E, opcionalmente:

AZURE_COSMOS_DB_NO_SQL_KEY

Quando isso não é definido, um AsyncDefaultAzureCredential é usado para autenticar.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlStore

vector_store = CosmosNoSqlStore()

Você também pode fornecer esses valores no construtor:

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlStore

vector_store = CosmosNoSqlStore(
    url="https://<your-account-name>.documents.azure.com:443/",
    key="<your-account-key>",
    database_name="<your-database-name>"
)

E podes passar uma instância de CosmosClient, certifica-te apenas de que é um cliente assíncrono.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlStore
from azure.cosmos.aio import CosmosClient

client = CosmosClient(
    url="https://<your-account-name>.documents.azure.com:443/",
    credential="<your-account-key>" or AsyncDefaultAzureCredential()
)
vector_store = CosmosNoSqlStore(
    client=client,
    database_name="<your-database-name>"
)

A próxima etapa precisa de um modelo de dados, uma variável chamada Hotels é usada no exemplo abaixo.

Com uma loja, podes obter uma coleção:

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlStore

vector_store = CosmosNoSqlStore()
collection = vector_store.get_collection(collection_name="skhotels", record_type=Hotel)

É possível construir uma referência direta a uma coleção nomeada, isso usa as mesmas variáveis de ambiente acima.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlCollection

collection = CosmosNoSqlCollection(
    record_type=Hotel,
    collection_name="skhotels",
)

Usando a chave de partição

No conector do Azure Cosmos DB para NoSQL, a propriedade da chave de partição assume como padrão a propriedade da chave - id. Você também pode fornecer um valor para a chave de partição no construtor.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlCollection

collection = CosmosNoSqlCollection(
    record_type=Hotel,
    collection_name="skhotels",
    partition_key="hotel_name"
)

Esta pode ser uma chave mais complexa, ao usar o objeto PartitionKey:

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlCollection
from azure.cosmos import PartitionKey

partition_key = PartitionKey(path="/hotel_name")
collection = CosmosNoSqlCollection(
    record_type=Hotel,
    collection_name="skhotels",
    partition_key=partition_key
)

A classe CosmosNoSqlVectorStoreRecordCollection suporta dois tipos de chave: string e CosmosNoSqlCompositeKey. O CosmosNoSqlCompositeKey consiste em key e partition_key.

Se a propriedade da chave de partição não estiver definida (e a propriedade de chave padrão for usada), string chaves poderão ser usadas para operações com registros de banco de dados. No entanto, se uma propriedade de chave de partição for especificada, é recomendável usar CosmosNoSqlCompositeKey para fornecer os valores de chave e chave de partição para os métodos get e delete.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlCollection, CosmosNoSqlCompositeKey
from semantic_kernel.data.vector import VectorStoreField

@vectorstoremodel
class Record:
    id: Annotated[str, VectorStoreField("key")]
    product_type: Annotated[str, VectorStoreField("data")]
    ...

collection = store.get_collection(
    record_type=Record,
    collection_name=collection_name,
    partition_key=PartitionKey(path="/product_type"),
)

# when there is data in the collection
composite_key = CosmosNoSqlCompositeKey(
    key='key value', partition_key='partition key value'
)
# get a record, with the partition key
record = await collection.get(composite_key)

# or delete
await collection.delete(composite_key)

Brevemente

Mais informações em breve.

Last updated on 2025-06-25

Partilhar via

Usando o conector de Armazém Vetorial NoSQL do Azure CosmosDB (Pré-visualização)

Descrição geral

Limitações

Começar

Mapeamento de dados

Usando a chave de partição

Descrição geral

Começar

Usando a chave de partição

Brevemente

Recursos adicionais