Transitioning to new Extensions AI IEmbeddingGenerator interface

As Semantic Kernel shifts its foundational abstractions to Microsoft.Extensions.AI, we are obsoleting and moving away from our experimental embeddings interfaces to the new standardized abstractions that provide a more consistent and powerful way to work with AI services across the .NET ecosystem.

The Evolution of Embedding Generation in Semantic Kernel

Semantic Kernel has always aimed to provide a unified way to interact with AI services, including embedding generation. Our initial approach used the ITextEmbeddingGenerationService interface, which served us well during the experimental phase. However, as the AI landscape has matured, so have our abstractions.

With Microsoft.Extensions.AI now generally available (no longer in preview), we’re standardizing on the more robust IEmbeddingGenerator<string, Embedding<float>> interface, which offers several advantages over our previous approach.

Why Make the Change?

The transition to Microsoft.Extensions.AI.IEmbeddingGenerator brings several benefits:

1. Standardization: Aligns with broader .NET ecosystem patterns and Microsoft.Extensions conventions
2. Type Safety: Stronger typing with the generic Embedding<float> return type
3. Flexibility: Support for different input types and embedding formats
4. Consistency: Uniform approach across different AI service providers
5. Integration: Seamless integration with other Microsoft.Extensions libraries

Code Comparison: Before and After

Let’s look at how this transition affects your code:

Before: Using ITextEmbeddingGenerationService

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Embeddings;

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

// Build the kernel
var kernel = builder.Build();

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

After: Using 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");

// Build the kernel
var kernel = builder.Build();

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

Key Differences

1. Method Names: GenerateEmbeddingsAsync becomes GenerateAsync
2. Return Type: Instead of returning IList<ReadOnlyMemory<float>>, the new interface returns GeneratedEmbeddings<Embedding<float>>
3. Options: The new interface accepts an optional EmbeddingGenerationOptions parameter for more control
4. Dimensions: Setting dimensions is now handled through options rather than attributes

Migrating Your Code

If you’re currently using ITextEmbeddingGenerationService, here’s how to migrate:

1. Update your package references to include the latest Semantic Kernel packages
2. Replace ITextEmbeddingGenerationService with IEmbeddingGenerator<string, Embedding<float>>
3. Update service registration to use the new embedding generator classes (e.g., OpenAIEmbeddingGenerator instead of OpenAITextEmbeddingGenerationService)
4. Update method calls from GenerateEmbeddingsAsync to GenerateAsync
5. Update how you access the embedding vectors (now through the .Vector property)

Transitional Support

To ease the transition, we’ve provided extension methods that allow you to convert between the old and new interfaces:

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

// Create a kernel with both old and new embedding services
var builder = Kernel.CreateBuilder();

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

// Build the kernel
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");

Connector Support

All our connectors have been updated to support the new interface:

• OpenAI and Azure OpenAI
• Google AI and Vertex AI
• Amazon Bedrock
• Hugging Face
• MistralAI
• And more…

Each connector now provides both the legacy service (marked as obsolete) and the new generator implementation.

Conclusion

The transition to Microsoft.Extensions.AI represents an important step in the maturation of Semantic Kernel. By aligning with broader .NET ecosystem patterns, we’re making it easier for developers to integrate AI capabilities into their applications with a consistent, type-safe approach.

We encourage all Semantic Kernel users to migrate to the new IEmbeddingGenerator<string, Embedding<float>> interface as soon as possible. The old interface will continue to work for now but is marked as obsolete and will be removed in a future release.

For more information about Microsoft.Extensions.AI, check out the official announcement.