Använda Azure CosmosDB NoSQL Vector Store-anslutningsappen (förhandsversion)

Artikel
01/23/2025

Varning

Funktionen Semantic Kernel Vector Store är i förhandsversion, och förbättringar som kräver icke-bakåtkompatibla ändringar kan fortfarande ske under begränsade omständigheter före lanseringen.

Översikt

Azure CosmosDB NoSQL Vector Store-anslutningsappen kan användas för att komma åt och hantera data i Azure CosmosDB NoSQL. Anslutningsappen har följande egenskaper.

Funktionsområde	Support
Samlingskartor till	Azure Cosmos DB NoSQL-container
Nyckelegenskapstyper som stöds	sträng AzureCosmosDBNoSQLCompositeKey
Dataegenskapstyper som stöds	sträng heltal lång dubbel flyttal bool DateTimeOffset och uppräkningar av var och en av dessa typer
Egenskapstyper för vektorer som stöds	ReadOnlyMemory-flyttal<> ReadOnlyMemory<byte> ReadOnlyMemory<sbyte> ReadOnlyMemory<Half>
Indextyper som stöds	Förenklat QuantizedFlat DiskAnn
Avståndsfunktioner som stöds	CosineSimilarity DotProductSimilarity EuclideanDistance
Filtersatser som stöds	AnyTagEqualTo EqualTo
Stöder flera vektorer i en post	Ja
Stöds IsFilterable?	Ja
Stöds IsFullTextSearchable?	Ja
Stöds StoragePropertyName?	Nej, använd `JsonSerializerOptions` och `JsonPropertyNameAttribute` i stället. Mer information finns här.

Begränsningar

När du initierar CosmosClient manuellt måste du ange CosmosClientOptions.UseSystemTextJsonSerializerWithOptions på grund av begränsningar i standard-serialiseraren. Det här alternativet kan ställas in på JsonSerializerOptions.Default eller anpassas med andra serialiseraralternativ för att uppfylla specifika konfigurationsbehov.

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

Komma igång

Lägg till NuGet-paketet för Azure CosmosDB NoSQL Vector Store-anslutningsappen i projektet.

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

Du kan lägga till vektorlagret i den beroendeinmatningscontainer som är tillgänglig i containern KernelBuilder eller till containern för IServiceCollection beroendeinmatning med hjälp av tilläggsmetoder som tillhandahålls av semantisk kernel.

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);

Tilläggsmetoder som inte har några parametrar tillhandahålls också. Dessa kräver att en instans av Microsoft.Azure.Cosmos.Database registreras separat med containern för beroendeinmatning.

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

Du kan skapa en Azure CosmosDB NoSQL Vector Store-instans direkt.

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);

Det går att skapa en direktreferens till en namngiven samling.

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");

Mappning av data

Azure CosmosDB NoSQL Vector Store-anslutningsappen tillhandahåller en standardmappare vid mappning från datamodellen till lagringen.

Den här mapparen utför en direkt konvertering av listan över egenskaper i datamodellen till fälten i Azure CosmosDB NoSQL och använder System.Text.Json.JsonSerializer för att konvertera till lagringsschemat. Det innebär att användning av JsonPropertyNameAttribute stöds om ett annat lagringsnamn än datamodellens egenskapsnamn krävs. Det enda undantaget är nyckeln för posten som mappas till ett databasfält med namnet id, eftersom alla CosmosDB NoSQL-poster måste använda det här namnet för ID:n.

Du kan också använda en anpassad JsonSerializerOptions instans med en anpassad namngivningsprincip för egenskaper. För att aktivera detta JsonSerializerOptions måste skickas till bygget AzureCosmosDBNoSQLVectorStoreRecordCollection .

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 });

Med hjälp av ovanstående anpassade JsonSerializerOptions som använder SnakeCaseUppermappas följande datamodell till json nedan.

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],
}

Använda partitionsnyckel

I Azure Cosmos DB for NoSQL-anslutningsappen använder partitionsnyckelegenskapen som standard nyckelegenskapen – id. Egenskapen PartitionKeyPropertyName i klassen AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> gör att du kan ange en annan egenskap som partitionsnyckel.

Klassen AzureCosmosDBNoSQLVectorStoreRecordCollection stöder två nyckeltyper: string och AzureCosmosDBNoSQLCompositeKey. AzureCosmosDBNoSQLCompositeKey består av RecordKey och PartitionKey.

Om partitionsnyckelegenskapen inte har angetts (och standardnyckelegenskapen används) kan string nycklar användas för åtgärder med databasposter. Men om en partitionsnyckelegenskap anges rekommenderar vi att du använder AzureCosmosDBNoSQLCompositeKey för att ange både nyckel- och partitionsnyckelvärdena.

Ange egenskapsnamnet för partitionsnyckeln:

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

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

Hämta med partitionsnyckel:

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

Kommer snart

Mer information kommer snart.

Kommer snart

Mer information kommer snart.

Dela via

Använda Azure CosmosDB NoSQL Vector Store-anslutningsappen (förhandsversion)

Översikt

Begränsningar

Komma igång

Mappning av data

Använda partitionsnyckel

Kommer snart

Kommer snart

Ytterligare resurser