セマンティックカーネルベクターストアコネクタ向けの埋め込み生成

2025-05-20

警告

セマンティックカーネルベクターストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

警告

セマンティックカーネルベクターストアコネクタでは、埋め込みを生成する複数の方法がサポートされています。埋め込みを開発者が生成し、 VectorStoreCollection を使用するときにレコードの一部として渡すか、 VectorStoreCollectionに内部で生成できます。

ベクターストアに埋め込みを生成させる

ベクターストアに埋め込みジェネレーターを構成すると、アップサート操作と検索操作の両方で埋め込みを自動的に生成できるため、手動による前処理が不要になります。

アップサートでベクトルを自動的に生成できるようにするには、データモデルの vector プロパティがソース型 (文字列など) として定義されますが、 VectorStoreVectorPropertyAttributeで修飾されます。

    [VectorStoreVector(1536)]
    public string Embedding { get; set; }

アップサートする前に、 Embedding プロパティには、ベクターの生成元となる文字列が含まれている必要があります。データベースに格納されているベクターの型 (float32、float16 など) は、構成された埋め込みジェネレーターから派生します。

重要

これらのベクタープロパティは、生成されたベクターまたはベクターが生成された元のテキストの取得をサポートしていません。元のテキストも格納されません。元のテキストを格納する必要がある場合は、別の Data プロパティを追加して格納する必要があります。

Microsoft.Extensions.AI抽象化を実装する埋め込みジェネレーターはサポートされており、さまざまなレベルで構成できます。

ベクターストア: ベクターストア全体に対して既定の埋め込みジェネレーターを設定できます。このジェネレーターは、オーバーライドされない限り、すべてのコレクションとプロパティに使用されます。

using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel.Connectors.Qdrant;
using OpenAI;
using Qdrant.Client;

var embeddingGenerator = new OpenAIClient("your key")
    .GetEmbeddingClient("your chosen model")
    .AsIEmbeddingGenerator();

var vectorStore = new QdrantVectorStore(
    new QdrantClient("localhost"),
    ownsClient: true,
    new QdrantVectorStoreOptions
    {
         EmbeddingGenerator = embeddingGenerator
    });

コレクションの場合: 特定のコレクションの埋め込みジェネレーターを構成し、ストアレベルのジェネレーターをオーバーライドできます。

using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel.Connectors.Qdrant;
using OpenAI;
using Qdrant.Client;

var embeddingGenerator = new OpenAIClient("your key")
    .GetEmbeddingClient("your chosen model")
    .AsIEmbeddingGenerator();

var collectionOptions = new QdrantCollectionOptions
{
    EmbeddingGenerator = embeddingGenerator
};
var collection = new QdrantCollection<ulong, MyRecord>(
    new QdrantClient("localhost"),
    "myCollection",
    ownsClient: true,
    collectionOptions);

レコード定義: VectorStoreCollectionDefinitionを使用してプログラムでプロパティを定義する場合は、すべてのプロパティに埋め込みジェネレーターを指定できます。

using Microsoft.Extensions.AI;
using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.Qdrant;
using OpenAI;
using Qdrant.Client;

var embeddingGenerator = new OpenAIClient("your key")
    .GetEmbeddingClient("your chosen model")
    .AsIEmbeddingGenerator();

var definition = new VectorStoreCollectionDefinition
{
    EmbeddingGenerator = embeddingGenerator,
    Properties = new List<VectorStoreProperty>
    {
        new VectorStoreKeyProperty("Key", typeof(ulong)),
        new VectorStoreVectorProperty("DescriptionEmbedding", typeof(string), dimensions: 1536)
    }
};

var collectionOptions = new QdrantCollectionOptions
{
    Definition = definition
};
var collection = new QdrantCollection<ulong, MyRecord>(
    new QdrantClient("localhost"),
    "myCollection",
    ownsClient: true,
    collectionOptions);

ベクタープロパティ定義の場合: プログラムでプロパティを定義する場合は、埋め込みジェネレーターをプロパティに直接設定できます。

using Microsoft.Extensions.AI;
using Microsoft.Extensions.VectorData;
using OpenAI;

var embeddingGenerator = new OpenAIClient("your key")
    .GetEmbeddingClient("your chosen model")
    .AsIEmbeddingGenerator();

var vectorProperty = new VectorStoreVectorProperty("DescriptionEmbedding", typeof(string), dimensions: 1536)
{
     EmbeddingGenerator = embeddingGenerator
};

使用例

次の例では、埋め込みジェネレーターを使用して、アップサート操作と検索操作の両方でベクトルを自動的に生成する方法を示します。この方法では、埋め込みを手動で事前に計算する必要がなくなり、ワークフローが簡略化されます。


// The data model
internal class FinanceInfo
{
    [VectorStoreKey]
    public string Key { get; set; } = string.Empty;

    [VectorStoreData]
    public string Text { get; set; } = string.Empty;

    // Note that the vector property is typed as a string, and
    // its value is derived from the Text property. The string
    // value will however be converted to a vector on upsert and
    // stored in the database as a vector.
    [VectorStoreVector(1536)]
    public string Embedding => this.Text;
}

// Create an OpenAI embedding generator.
var embeddingGenerator = new OpenAIClient("your key")
    .GetEmbeddingClient("your chosen model")
    .AsIEmbeddingGenerator();

// Use the embedding generator with the vector store.
var vectorStore = new InMemoryVectorStore(new() { EmbeddingGenerator = embeddingGenerator });
var collection = vectorStore.GetCollection<string, FinanceInfo>("finances");
await collection.EnsureCollectionExistsAsync();

// Create some test data.
string[] budgetInfo =
{
    "The budget for 2020 is EUR 100 000",
    "The budget for 2021 is EUR 120 000",
    "The budget for 2022 is EUR 150 000",
    "The budget for 2023 is EUR 200 000",
    "The budget for 2024 is EUR 364 000"
};

// Embeddings are generated automatically on upsert.
var records = budgetInfo.Select((input, index) => new FinanceInfo { Key = index.ToString(), Text = input });
await collection.UpsertAsync(records);

// Embeddings for the search is automatically generated on search.
var searchResult = collection.SearchAsync(
    "What is my budget for 2024?",
    top: 1);

// Output the matching result.
await foreach (var result in searchResult)
{
    Console.WriteLine($"Key: {result.Record.Key}, Text: {result.Record.Text}");
}

自分で埋め込みを生成する

埋め込みジェネレーターの構築

セマンティックカーネルインスタンスを構築する方法の例については、「ITextEmbeddingGenerationService」を参照してください。

埋め込み生成サービスを構築する方法については、 Microsoft.Extensions.AI.AbstractionsMicrosoft.Extensions.AI 参照してください。

セマンティックカーネルを使ってアップサート時に埋め込みを生成する `ITextEmbeddingGenerationService`

public async Task GenerateEmbeddingsAndUpsertAsync(
    ITextEmbeddingGenerationService textEmbeddingGenerationService,
    VectorStoreCollection<ulong, Hotel> collection)
{
    // Upsert a record.
    string descriptionText = "A place where everyone can be happy.";
    ulong hotelId = 1;

    // Generate the embedding.
    ReadOnlyMemory<float> embedding =
        await textEmbeddingGenerationService.GenerateEmbeddingAsync(descriptionText);

    // Create a record and upsert with the already generated embedding.
    await collection.UpsertAsync(new Hotel
    {
        HotelId = hotelId,
        HotelName = "Hotel Happy",
        Description = descriptionText,
        DescriptionEmbedding = embedding,
        Tags = new[] { "luxury", "pool" }
    });
}

セマンティックカーネルを使用した検索での埋め込みの生成 `ITextEmbeddingGenerationService`

public async Task GenerateEmbeddingsAndSearchAsync(
    ITextEmbeddingGenerationService textEmbeddingGenerationService,
    VectorStoreCollection<ulong, Hotel> collection)
{
    // Upsert a record.
    string descriptionText = "Find me a hotel with happiness in mind.";

    // Generate the embedding.
    ReadOnlyMemory<float> searchEmbedding =
        await textEmbeddingGenerationService.GenerateEmbeddingAsync(descriptionText);

    // Search using the already generated embedding.
    IAsyncEnumerable<VectorSearchResult<Hotel>> searchResult = collection.SearchAsync(searchEmbedding, top: 1);
    List<VectorSearchResult<Hotel>> resultItems = await searchResult.ToListAsync();

    // Print the first search result.
    Console.WriteLine("Score for first result: " + resultItems.FirstOrDefault()?.Score);
    Console.WriteLine("Hotel description for first result: " + resultItems.FirstOrDefault()?.Record.Description);
}

ヒント

埋め込みの生成の詳細については、「セマンティックカーネルでの埋め込みの生成」を参照してください。

埋め込み次元

ベクターデータベースでは、通常、コレクションの作成時に各ベクターに含まれる次元の数を指定する必要があります。通常、さまざまな埋め込みモデルでは、さまざまなディメンションサイズのベクターの生成がサポートされます。たとえば、OpenAI text-embedding-ada-002 は 1536 次元のベクトルを生成します。一部のモデルでは、開発者は出力ベクトルで必要な次元の数を選択することもできます。たとえば、Google text-embedding-004 では、既定で 768 次元のベクトルが生成されますが、開発者は 1 から 768 までの任意の数のディメンションを選択できます。

埋め込みモデルによって生成されるベクターの次元数が、データベース内の一致するベクターと同じになるようにすることが重要です。

セマンティックカーネルベクターストアの抽象化を使用してコレクションを作成する場合は、注釈またはレコード定義を使用して、各ベクタープロパティに必要な次元の数を指定する必要があります。ディメンションの数を 1536 に設定する両方の例を次に示します。

[VectorStoreVector(Dimensions: 1536)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 1536);

ヒント

データモデルに注釈を付ける方法の詳細については、「データモデルの定義」を参照してください。

ヒント

レコード定義の作成の詳細については、「レコード定義を使用してスキーマを定義するを参照してください。

間もなく利用できます

詳細については、近日公開予定です。

間もなく利用できます

詳細については、近日公開予定です。

次の方法で共有

セマンティック カーネル ベクター ストア コネクタ向けの埋め込み生成

ベクター ストアに埋め込みを生成させる

使用例

自分で埋め込みを生成する

埋め込みジェネレーターの構築

セマンティック カーネルを使ってアップサート時に埋め込みを生成する ITextEmbeddingGenerationService

セマンティック カーネルを使用した検索での埋め込みの生成 ITextEmbeddingGenerationService

埋め込み次元

間もなく利用できます

間もなく利用できます

その他のリソース

セマンティックカーネルベクターストアコネクタ向けの埋め込み生成

ベクターストアに埋め込みを生成させる

セマンティックカーネルを使ってアップサート時に埋め込みを生成する `ITextEmbeddingGenerationService`

セマンティックカーネルを使用した検索での埋め込みの生成 `ITextEmbeddingGenerationService`