Sdílet prostřednictvím

Použití konektoru Azure CosmosDB NoSQL Vector Store (Preview)

  • Článek

Varování

Funkce sémantického úložiště vektorů jádra je ve verzi Preview a vylepšení, která vyžadují zásadní změny, se můžou vyskytovat za omezených okolností před vydáním.

Přehled

Konektor Azure CosmosDB NoSQL Vector Store je možné použít k přístupu k datům v NoSQL a jejich správě. Konektor má následující charakteristiky.

Oblast funkcí Technická podpora
Mapa sbírky na Kontejner NoSQL služby Azure Cosmos DB
Podporované klíčové typy vlastností
  • řetězec
  • AzureCosmosDBNoSQLCompositeKey
Podporované typy datových vlastností
  • řetězec
  • int
  • dlouhý
  • dvojitý
  • float
  • bool
  • DateTimeOffset
  • a výčtové typy každého z těchto typů
Podporované typy vektorových vlastností
  • ReadOnlyMemory<float>
  • ReadOnlyMemory
  • ReadOnlyMemory<sbyte>
  • Paměť pouze pro čtení<Polovina>
Podporované typy indexů
  • Plochý
  • QuantizedFlat
  • DiskAnn
Podporované funkce vzdálenosti
  • KosineSimilarita
  • DotProductSimilarity
  • EuclideanDistance
Podporované klauzule filtru
  • AnyTagEqualTo
  • EqualTo
Podporuje více vektorů v záznamu. Ano
Je podporováno Filtrování? Ano
Podporuje se IsFullTextSearchable? Ano
StoragePropertyName se podporuje? Ne, použijte JsonSerializerOptions a JsonPropertyNameAttribute místo toho. Další informace najdete tady.
Podporuje se HybridSearch? Ano

Omezení

Při ruční inicializaci CosmosClient je nutné zadat CosmosClientOptions.UseSystemTextJsonSerializerWithOptions kvůli omezením výchozího serializátoru. Tuto možnost můžete nastavit na JsonSerializerOptions.Default nebo přizpůsobit pomocí dalších možností serializátoru, aby vyhovovala konkrétním potřebám konfigurace.

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

Začínáme

Do svého projektu přidejte balíček NuGet konektoru Azure CosmosDB NoSQL Vector Store.

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

Vektorové úložiště můžete přidat do kontejneru pro vkládání závislostí dostupného na KernelBuilder nebo do kontejneru pro vkládání závislostí na IServiceCollection pomocí rozšiřujících metod poskytovaných Sémantickým jádrem.

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

K dispozici jsou také metody rozšíření, které nepoužívají žádné parametry. Je nutné, aby byla instance Microsoft.Azure.Cosmos.Database zaregistrována samostatně v kontejneru pro injekci závislostí.

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

Instanci Azure CosmosDB NoSQL Vector Store můžete vytvořit přímo.

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

Je možné vytvořit přímý odkaz na pojmenovanou kolekci.

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

Mapování dat

Konektor Azure CosmosDB NoSQL Vector Store poskytuje výchozí mapovač při mapování z datového modelu do úložiště.

Tento mapovač provede přímý převod seznamu vlastností datového modelu na pole v NoSQL služby Azure CosmosDB a používá System.Text.Json.JsonSerializer k převodu na schéma úložiště. To znamená, že použití tohoto objektu JsonPropertyNameAttribute se podporuje, pokud se vyžaduje jiný název úložiště s názvem vlastnosti datového modelu. Jedinou výjimkou je klíč záznamu, který je namapován na pole databáze s názvem id, protože všechny záznamy NoSQL služby Cosmos DB musí pro ID používat tento název.

Je také možné použít vlastní instanci JsonSerializerOptions s přizpůsobenou zásadou pojmenování vlastností. Aby to bylo možné, JsonSerializerOptions musí být předáno AzureCosmosDBNoSQLVectorStoreRecordCollection při konstrukci.

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

Pomocí výše uvedeného vlastního JsonSerializerOptions modelu, který používá SnakeCaseUpper, se následující datový model namapuje na následující 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],
}

Použití klíče oddílu

Ve výchozím nastavení je vlastnost klíče oddílu v konektoru Azure Cosmos DB for NoSQL nastavena na vlastnost klíče – id. Vlastnost PartitionKeyPropertyName ve třídě AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> umožňuje určit jinou vlastnost jako klíč pro oddílování.

Třída AzureCosmosDBNoSQLVectorStoreRecordCollection podporuje dva typy klíčů: string a AzureCosmosDBNoSQLCompositeKey. AzureCosmosDBNoSQLCompositeKey se skládá z RecordKey a PartitionKey.

Pokud vlastnost klíče oddílu není nastavená (a použije se výchozí vlastnost klíče), lze string klíče použít pro operace se záznamy databáze. Pokud je však zadána vlastnost klíče oddílu, doporučuje se použít AzureCosmosDBNoSQLCompositeKey k zadání hodnot klíče i klíče oddílu.

Zadejte název vlastnosti klíče oddílu:

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

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

Získat pomocí klíče oddílu:

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

Přehled

Konektor Azure CosmosDB NoSQL Vector Store je možné použít k přístupu k datům v NoSQL a jejich správě. Konektor má následující charakteristiky.

Oblast funkcí Technická podpora
Mapa sbírky na Kontejner NoSQL služby Azure Cosmos DB
Podporované klíčové typy vlastností
  • řetězec
  • AzureCosmosDBNoSQLCompositeKey
Podporované typy datových vlastností
  • řetězec
  • int
  • dlouhý
  • dvojitý
  • float
  • bool
  • DateTimeOffset
  • a iterovatelné prvky každého z těchto typů
Podporované typy vektorových vlastností
  • seznam[float]
  • seznam[int]
  • ndarray
Podporované typy indexů
  • Plochý
  • QuantizedFlat
  • DiskAnn
Podporované funkce vzdálenosti
  • KosineSimilarita
  • DotProductSimilarity
  • EuclideanDistance
Podporované klauzule filtru
  • AnyTagEqualTo
  • EqualTo
Podporuje více vektorů v záznamu. Ano
Je funkce is_filterable podporována? Ano
Je "is_full_text_searchable" podporováno? Ano
Podporuje se HybridSearch? Ne

Začínáme

Přidejte do projektu další balíček Azure.

pip install semantic-kernel[azure]

Dále můžete přímo vytvořit instanci Azure CosmosDB NoSQL Vector Store. Načte se určité proměnné prostředí pro konfiguraci připojení ke službě Azure CosmosDB NoSQL:

  • AZURE_COSMOS_DB_NO_SQL_URL
  • AZURE_COSMOS_DB_NO_SQL_DATABASE_NAME

A volitelně:

  • AZURE_COSMOS_DB_NO_SQL_KEY

Pokud toto nastavení není nastavené, použije se k ověření AsyncDefaultAzureCredential.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLStore

vector_store = AzureCosmosDBNoSQLStore()

Tyto hodnoty můžete zadat také v konstruktoru:

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLStore

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

A můžete předat instanci CosmosClient, jen se ujistěte, že se jedná o asynchronního klienta.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLStore
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 = AzureCosmosDBNoSQLStore(
    client=client,
    database_name="<your-database-name>"
)

Další krok potřebuje datový model, proměnná s názvem Hotely se používá v následujícím příkladu.

V obchodě můžete získat kolekci:

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLStore

vector_store = AzureCosmosDBNoSQLStore()
collection = vector_store.get_collection(collection_name="skhotels", data_model=Hotel)

Je možné vytvořit přímý odkaz na pojmenovanou kolekci, která používá stejné proměnné prostředí jako výše.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLCollection

collection = AzureCosmosDBNoSQLCollection(
    collection_name="skhotels",
    data_model_type=Hotel,
)

Použití klíče oddílu

Ve výchozím nastavení je vlastnost klíče oddílu v konektoru Azure Cosmos DB for NoSQL nastavena na vlastnost klíče – id. Můžete také zadat hodnotu klíče oddílu v konstruktoru.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLCollection

collection = AzureCosmosDBNoSQLCollection(
    collection_name="skhotels",
    data_model_type=Hotel,
    partition_key="hotel_name"
)

Při použití objektu PartitionKey to může být složitější klíč:

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLCollection
from azure.cosmos import PartitionKey

partition_key = PartitionKey(path="/hotel_name")
collection = AzureCosmosDBNoSQLCollection(
    collection_name="skhotels",
    data_model_type=Hotel,
    partition_key=partition_key
)

Třída AzureCosmosDBNoSQLVectorStoreRecordCollection podporuje dva typy klíčů: string a AzureCosmosDBNoSQLCompositeKey. AzureCosmosDBNoSQLCompositeKey se skládá z key a partition_key.

Pokud vlastnost klíče oddílu není nastavená (a použije se výchozí vlastnost klíče), lze string klíče použít pro operace se záznamy databáze. Pokud je však zadána vlastnost klíče oddílu, je doporučeno použít AzureCosmosDBNoSQLCompositeKey k zadání hodnot klíče i klíče oddílu metodám get a delete.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLCollection
from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBNoSQLCompositeKey
from semantic_kernel.data import VectorStoreRecordDataField

@vectorstoremodel
class data_model_type:
    id: Annotated[str, VectorStoreRecordKeyField]
    product_type: Annotated[str, VectorStoreRecordDataField()]
    ...

collection = store.get_collection(
    collection_name=collection_name,
    data_model=data_model_type,
    partition_key=PartitionKey(path="/product_type"),
)

# when there is data in the collection
composite_key = AzureCosmosDBNoSQLCompositeKey(
    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)

Již brzy

Další informace budou brzy k dispozici.