ITextEmbeddingGenerationService から IEmbeddingGenerator への移行

2025-05-28

セマンティックカーネルが基本的な抽象化を Microsoft.Extensions.AI に移行するにつれて、実験用の埋め込みインターフェイスから、.NET エコシステム全体で AI サービスを操作するための一貫した強力な方法を提供する新しい標準化された抽象化に、旧式化および移行しています。

このガイドは、古い ITextEmbeddingGenerationService インターフェイスから新しい Microsoft.Extensions.AI.IEmbeddingGenerator<string, Embedding<float>> インターフェイスに移行するのに役立ちます。

変更を加える理由

Microsoft.Extensions.AI.IEmbeddingGeneratorへの移行には、次のような利点があります。

標準化: より広範な .NET エコシステムパターンと Microsoft.Extensions の規則に準拠
型の安全性: ジェネリックEmbedding<float>型の戻り値を用いることでより強力な型指定
柔軟性: さまざまな入力タイプと埋め込み形式のサポート
一貫性: 異なる AI サービスプロバイダー間の均一なアプローチ
統合: 他の Microsoft.Extensions ライブラリとのシームレスな統合

パッケージの更新

コードを移行する前に、セマンティックカーネル 1.51.0 以降のパッケージがあることを確認します。

カーネルビルダーの移行

初めに: ITextEmbeddingGenerationServiceの使用について

using Microsoft.SemanticKernel;
#pragma warning disable SKEXP0010

// Create a kernel builder
var builder = Kernel.CreateBuilder();

// Add the OpenAI embedding service
builder.Services.AddOpenAITextEmbeddingGeneration(
    modelId: "text-embedding-ada-002",
    apiKey: "your-api-key");

後: IEmbeddingGeneratorの使用方法

using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel;

// Create a kernel builder
var builder = Kernel.CreateBuilder();

// Add the OpenAI embedding generator
builder.Services.AddOpenAIEmbeddingGenerator(
    modelId: "text-embedding-ada-002",
    apiKey: "your-api-key");

依存関係の挿入/サービスコレクションの移行

Before: Using ITextEmbeddingGenerationService

using Microsoft.SemanticKernel;
#pragma warning disable SKEXP0010

// Create or use an existing service collection (WebApplicationBuilder.Services)
var services = new ServiceCollection();

// Add the OpenAI embedding service
services.AddOpenAITextEmbeddingGeneration(
    modelId: "text-embedding-ada-002",
    apiKey: "your-api-key");

後に: IEmbeddingGeneratorの使用

using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel;

// Create or use an existing service collection (WebApplicationBuilder.Services)
var services = new ServiceCollection();

// Add the OpenAI embedding generator
services.AddOpenAIEmbeddingGenerator(
    modelId: "text-embedding-ada-002",
    apiKey: "your-api-key");

インターフェイスの使用状況の移行

ITextEmbeddingGenerationService を使用する前に

using Microsoft.SemanticKernel.Embeddings;

// Get the embedding service from the kernel
var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

// Generate embeddings
var text = "Semantic Kernel is a lightweight SDK that integrates Large Language Models (LLMs) with conventional programming languages.";
var embedding = await embeddingService.GenerateEmbeddingAsync(text);

// Work with the embedding vector
Console.WriteLine($"Generated embedding with {embedding.Length} dimensions");

次の内容: IEmbeddingGeneratorの使用

using Microsoft.Extensions.AI;

// Get the embedding generator from the kernel
var embeddingGenerator = kernel.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();

// Generate embeddings
var text = "Semantic Kernel is a lightweight SDK that integrates Large Language Models (LLMs) with conventional programming languages.";
var embedding = await embeddingGenerator.GenerateAsync(text);

// Work with the embedding vector
Console.WriteLine($"Generated embedding with {embedding.Vector.Length} dimensions");

主な違い

メソッド名: GenerateEmbeddingAsync は次のようになります GenerateAsync
戻り値の型: ReadOnlyMemory<float>を返す代わりに、新しいインターフェイスはGeneratedEmbeddings<Embedding<float>>を返します。
ベクターアクセス: Embedding<float> クラスの.Vector プロパティを使用して埋め込みReadOnlyMemory<float>にアクセスする
オプション: 新しいインターフェイスは、より詳細な制御のために省略可能な EmbeddingGenerationOptions パラメーターを受け取ります

複数のエンベディングマイグレーション

前: 複数の埋め込みを生成する

using Microsoft.SemanticKernel.Embeddings;

var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

var texts = new[]
{
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
};

IList<ReadOnlyMemory<float>> embeddings = await embeddingService.GenerateEmbeddingsAsync(texts);

foreach (var embedding in embeddings)
{
    Console.WriteLine($"Generated embedding with {embedding.Length} dimensions");
}

後: 複数の埋め込みを生成する

using Microsoft.Extensions.AI;

var embeddingGenerator = kernel.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();

var texts = new[]
{
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
};

var embeddings = await embeddingGenerator.GenerateAsync(texts);

foreach (var embedding in embeddings)
{
    Console.WriteLine($"Generated embedding with {embedding.Vector.Length} dimensions");
}

移行のサポート

移行を容易にするために、セマンティックカーネルには、古いインターフェイスと新しいインターフェイスの間で変換できる拡張メソッドが用意されています。

using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Embeddings;

// Create a kernel with the old embedding service
var builder = Kernel.CreateBuilder();

#pragma warning disable SKEXP0010
builder.Services.AddOpenAITextEmbeddingGeneration(
    modelId: "text-embedding-ada-002",
    apiKey: "your-api-key");
#pragma warning restore SKEXP0010

var kernel = builder.Build();

// Get the old embedding service
var oldEmbeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

// Convert from old to new using extension method
IEmbeddingGenerator<string, Embedding<float>> newGenerator =
    oldEmbeddingService.AsEmbeddingGenerator();

// Use the new generator
var newEmbedding = await newGenerator.GenerateAsync("Converting from old to new");
Console.WriteLine($"Generated embedding with {newEmbedding.Vector.Length} dimensions");

コネクタのサポート

新しいインターフェイスをサポートするために、すべてのセマンティックカーネルコネクタが更新されました。

OpenAI と Azure OpenAI: AddOpenAIEmbeddingGenerator と AddAzureOpenAIEmbeddingGenerator
Google AI と Vertex AI: AddGoogleAIEmbeddingGenerator と AddVertexAIEmbeddingGenerator
Amazon Bedrock: Use AddBedrockEmbeddingGenerator
Hugging Face: 使用 AddHuggingFaceEmbeddingGenerator
MistralAI: 使用 AddMistralEmbeddingGenerator
オラマ: AddOllamaEmbeddingGeneratorを使う
ONNX: 使用 AddBertOnnxEmbeddingGenerator

各コネクタは、レガシサービス (古いサービスとしてマーク) と新しいジェネレーターの実装の両方を提供するようになりました。

Azure OpenAI の例

前: Azure OpenAI with ITextEmbeddingGenerationService

using Microsoft.SemanticKernel;

var builder = Kernel.CreateBuilder();

#pragma warning disable SKEXP0010
builder.Services.AddAzureOpenAITextEmbeddingGeneration(
    deploymentName: "text-embedding-ada-002",
    endpoint: "https://myaiservice.openai.azure.com",
    apiKey: "your-api-key");
#pragma warning restore SKEXP0010

var kernel = builder.Build();
var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

Azure OpenAI と IEmbeddingGenerator の後

using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel;

var builder = Kernel.CreateBuilder();

builder.Services.AddAzureOpenAIEmbeddingGenerator(
    deploymentName: "text-embedding-ada-002",
    endpoint: "https://myaiservice.openai.azure.com",
    apiKey: "your-api-key");

var kernel = builder.Build();
var embeddingGenerator = kernel.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();

埋め込み生成オプションの使用

新しいインターフェイスでは、埋め込み生成をより詳細に制御するための追加オプションがサポートされています。

前: 制限付きオプション

// The old interface had limited options, mostly configured during service registration
var embedding = await embeddingService.GenerateEmbeddingAsync(text);

後: 豊富なオプションのサポート

using Microsoft.Extensions.AI;

// Example 1: Specify custom dimensions for the embedding
var options = new EmbeddingGenerationOptions
{
    Dimensions = 512  // Request a smaller embedding size for efficiency
};

var embedding = await embeddingGenerator.GenerateAsync(text, options);

// Example 2: Override the model for a specific request
var modelOptions = new EmbeddingGenerationOptions
{
    ModelId = "text-embedding-3-large"  // Use a different model than the default
};

var largeEmbedding = await embeddingGenerator.GenerateAsync(text, modelOptions);

// Example 3: Combine multiple options
var combinedOptions = new EmbeddingGenerationOptions
{
    Dimensions = 1024,
    ModelId = "text-embedding-3-small"
};

var customEmbedding = await embeddingGenerator.GenerateAsync(text, combinedOptions);

ベクターストアの操作

新しい IEmbeddingGenerator インターフェイスは、セマンティックカーネルのベクターストアとシームレスに統合されます。

using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel.Connectors.InMemory;

// Create an embedding generator
var embeddingGenerator = kernel.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();

// Use with vector stores
var vectorStore = new InMemoryVectorStore(new() { EmbeddingGenerator = embeddingGenerator });
var collection = vectorStore.GetCollection<string, MyRecord>("myCollection");

// The vector store will automatically use the embedding generator for text properties
await collection.UpsertAsync(new MyRecord
{
    Id = "1",
    Text = "This text will be automatically embedded"
});

internal class MyRecord
{
    [VectorStoreKey]
    public string Id { get; set; }

    [VectorStoreData]
    public string Text { get; set; }

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

ダイレクトサービスのインスタンス化

以前: 直接サービス作成

using Microsoft.SemanticKernel.Connectors.OpenAI;

#pragma warning disable SKEXP0010
var embeddingService = new OpenAITextEmbeddingGenerationService(
    modelId: "text-embedding-ada-002",
    apiKey: "your-api-key");
#pragma warning restore SKEXP0010

後: Microsoft.Extensions.AI.OpenAI の使用

using Microsoft.Extensions.AI;
using OpenAI;

// Create using the OpenAI SDK directly
var openAIClient = new OpenAIClient("your-api-key");
var embeddingGenerator = openAIClient
    .GetEmbeddingClient("text-embedding-ada-002")
    .AsIEmbeddingGenerator();

次のステップ

パッケージ参照を最新のセマンティックカーネルバージョンに更新する
ITextEmbeddingGenerationService を IEmbeddingGenerator<string, Embedding<float>> に置き換えます。
新しい埋め込みジェネレーターメソッドを使用するようにサービス登録を更新する (例: AddOpenAIEmbeddingGenerator)
GenerateEmbeddingAsync / GenerateEmbeddingsAsyncからGenerateAsyncへのメソッド呼び出しを更新する
埋め込みベクターへのアクセス方法を更新する ( .Vector プロパティを使用)
追加のコントロールに新しい options パラメーターを使用することを検討してください
アプリケーションをテストして移行が成功したことを確認する

古いインターフェイスは今のところ引き続き動作しますが、古いものとしてマークされており、今後のリリースで削除される予定です。すべてのセマンティックカーネルユーザーは、できるだけ早く新しい IEmbeddingGenerator<string, Embedding<float>> インターフェイスに移行することをお勧めします。

Microsoft.Extensions.AI の詳細については、公式発表を参照してください。