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

Varning

Funktionerna i Azure CosmosDB NoSQL 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 innan de släpps.

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.

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 Stöd
Samlingskartor för Azure Cosmos DB NoSQL-container
Nyckelegenskapstyper som stöds
  • sträng
  • CosmosNoSqlSammanfogadNyckel
Dataegenskapstyper som stöds
  • sträng
  • heltal
  • lång
  • dubbel
  • flyttal
  • Bool
  • DateTimeOffset (tidpunkt med tidsförskjutning)
  • och uppräkningar av var och en av dessa typer
Egenskapstyper för vektorer som stöds
  • ReadOnlyMemory
  • Inbäddning<flyttal>
  • float[]
  • SkrivskyddatMinne<byte>
  • Bädda<in byte>
  • byte[]
  • ReadOnlyMemory<sbyte>
  • Bädda<in sbyte>
  • sbyte[]
Indextyper som stöds
  • Platt
  • QuantizedFlat
  • DiskAnn
Avståndsfunktioner som stöds
  • Cosine-Similäritet
  • DotProduktsimilaritet
  • EuclideanDistance
Filtersatser som stöds
  • NågonTagLikaMed
  • EqualTo
Stödjer flera vektorer i en post Ja
Är IsIndexed stödd? Ja
Är FullTextIndexed stödd? Ja
Stöds StorageName? Nej, använd JsonSerializerOptions och JsonPropertyNameAttribute i stället. Mer information finns här.
Stöds HybridSearch? Ja

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

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

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

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

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

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

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 möjliggöra detta måste JsonSerializerOptions skickas till CosmosNoSqlCollection vid konstruktion.

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

Med hjälp av ovanstående anpassade JsonSerializerOptions som använder SnakeCaseUpper mappas följande datamodell till nedanstående JSON.

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

Använda partitionsnyckel

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

Klassen CosmosNoSqlCollection stöder två nyckeltyper: string och CosmosNoSqlCompositeKey. CosmosNoSqlCompositeKey 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 CosmosNoSqlCompositeKey för att ange både nyckel- och partitionsnyckelvärdena.

Ange egenskapsnamnet för partitionsnyckeln:

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

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

Hämta med partitionsnyckel:

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

Ö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 Stöd
Samlingskartor för Azure Cosmos DB NoSQL-container
Nyckelegenskapstyper som stöds
  • sträng
  • CosmosNoSqlSammanfogadNyckel
Dataegenskapstyper som stöds
  • sträng
  • heltal
  • lång
  • dubbel
  • flyttal
  • Bool
  • DateTimeOffset (tidpunkt med tidsförskjutning)
  • och iterbara objekt av var och en av dessa typer
Egenskapstyper för vektorer som stöds
  • lista[float]
  • lista[int]
  • ndarray
Indextyper som stöds
  • Platt
  • QuantizedFlat
  • DiskAnn
Avståndsfunktioner som stöds
  • Cosine-Similäritet
  • DotProduktsimilaritet
  • EuclideanDistance
Filtersatser som stöds
  • NågonTagLikaMed
  • EqualTo
Stödjer flera vektorer i en post Ja
Är "is_filterable" stödd? Ja
Stöds fulltext-sökning? Ja
Stöds HybridSearch? Nej

Komma igång

Lägg till Azure-extrapaketet i projektet.

pip install semantic-kernel[azure]

Sedan kan du skapa en Azure CosmosDB NoSQL Vector Store-instans direkt. Detta läser vissa miljövariabler för att konfigurera anslutningen till Azure CosmosDB NoSQL:

  • AZURE_COSMOS_DB_NO_SQL_URL
  • AZURE_COSMOS_DB_NO_SQL_DATABAS_NAMN

Och valfritt:

  • AZURE_COSMOS_DB_NO_SQL_KEY

När detta inte har angetts används en AsyncDefaultAzureCredential för att autentisera.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlStore

vector_store = CosmosNoSqlStore()

Du kan också ange dessa värden i konstruktorn:

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

Och du kan skicka in en CosmosClient-instans, se bara till att det är en asynkron klient.

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

Nästa steg behöver en datamodell, en variabel med namnet Hotell används i exemplet nedan.

Med en butik kan du skaffa en samling:

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlStore

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

Det går att konstruera en direktreferens till en namngiven samling. Detta använder samma miljövariabler som ovan.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlCollection

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

Använda partitionsnyckel

I Azure Cosmos DB for NoSQL-anslutningsappen använder partitionsnyckelegenskapen som standard nyckelegenskapen – id. Du kan också ange ett värde för partitionsnyckeln i konstruktorn.

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlCollection

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

Detta kan vara en mer komplex nyckel när du använder objektet 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
)

Klassen CosmosNoSqlVectorStoreRecordCollection stöder två nyckeltyper: string och CosmosNoSqlCompositeKey. CosmosNoSqlCompositeKey består av key och partition_key.

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 CosmosNoSqlCompositeKey för att ange både nyckel- och partitionsnyckelvärdena till get metoderna och 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)

Kommer snart

Mer information kommer snart.

  • Last updated on