使用 Azure CosmosDB NoSQL 向量存放區連接器 （預覽）

警告

語意核心向量存放區功能處於預覽狀態，且需要重大變更的改善可能仍會在發行前有限的情況下發生。

概觀

Azure CosmosDB NoSQL 向量存放區連接器可用來存取和管理 Azure CosmosDB NoSQL 中的數據。 連接器具有下列特性。

功能區域	支援
集合對應至	Azure Cosmos DB NoSQL 容器
支援的索引鍵屬性類型	字串 AzureCosmosDBNoSQLCompositeKey
支援的數據類型	字串 int long double float bool DateTimeOffset 和這些類型的可列舉專案
支援的向量屬性類型	ReadOnlyMemory<float> ReadOnlyMemory<位元組> ReadOnlyMemory<sbyte> ReadOnlyMemory<Half>
支援的索引類型	一般 QuantizedFlat DiskAnn
支援的距離函式	CosineSimilarity DotProductSimilarity EuclideanDistance
支援的篩選子句	AnyTagEqualTo EqualTo
支援記錄中的多個向量	Yes
是否支援IsFilterable？	Yes
是否支援IsFullTextSearchable？	Yes
支援的 StoragePropertyName？	否，請改用 JsonSerializerOptions 和 JsonPropertyNameAttribute 。 如需詳細資訊，請參閱這裡。

局限性

手動初始化 CosmosClient 時，必須指定 CosmosClientOptions.UseSystemTextJsonSerializerWithOptions，因為預設串行化程式的限制。 此選項可以設定為 JsonSerializerOptions.Default，或使用其他串行化程式選項自定義，以符合特定組態需求。

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

開始使用

將 Azure CosmosDB NoSQL 向量存放區連接器 NuGet 套件新增至您的專案。

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

您可以使用 Semantic Kernel 所提供的擴充方法，將向量存放區新增至 KernelBuilder 上IServiceCollection可用的相依性插入容器或相依性插入容器。

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

也提供不採用任何參數的擴充方法。 這些實例需要 Microsoft.Azure.Cosmos.Database 個別向相依性插入容器註冊。

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

您可以直接建構 Azure CosmosDB NoSQL 向量存放區實例。

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

可以建構具名集合的直接參考。

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

資料對應

從數據模型對應到記憶體時，Azure CosmosDB NoSQL 向量存放區連接器會提供預設對應程式。

此對應程式會將數據模型上的屬性清單直接轉換成 Azure CosmosDB NoSQL 中的欄位，並使用 System.Text.Json.JsonSerializer 轉換為記憶體架構。 這表示如果需要與資料模型屬性名稱不同的記憶體名稱，則支援 使用 JsonPropertyNameAttribute 。 唯一的例外狀況是對應至名為 id的資料庫欄位之記錄索引鍵，因為所有 CosmosDB NoSQL 記錄都必須將此名稱用於標識碼。

您也可以使用自定義實例搭配自定義 JsonSerializerOptions 屬性命名原則。 若要啟用此功能， JsonSerializerOptions 必須將 傳遞至 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 });

使用上述使用 JsonSerializerOptions的自定義 SnakeCaseUpper ，下列數據模型將會對應至下列 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],
}

使用分區鍵

在適用於 NoSQL 的 Azure Cosmos DB 連接器中，分割區索引鍵屬性預設為索引鍵屬性 - id。 AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> 類別中的 PartitionKeyPropertyName 屬性允許將不同的屬性指定為分割區索引鍵。

AzureCosmosDBNoSQLVectorStoreRecordCollection 類別支援兩種索引鍵類型：string 和 AzureCosmosDBNoSQLCompositeKey。 AzureCosmosDBNoSQLCompositeKey 是由 RecordKey 和 PartitionKey所組成。

如果未設定分割區索引鍵屬性（且使用預設索引鍵屬性），string 索引鍵可用於資料庫記錄的操作。 不過，如果指定分割區索引鍵屬性，建議使用 AzureCosmosDBNoSQLCompositeKey 來提供索引鍵和分割區索引鍵值。

指定分割區索引鍵屬性名稱：

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

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

取得分割區鍵：

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

即將推出

更多信息即將推出。

即將推出

更多信息即將推出。