{"id":4853,"date":"2025-05-21T07:46:46","date_gmt":"2025-05-21T14:46:46","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/semantic-kernel\/?p=4853"},"modified":"2025-05-21T07:46:46","modified_gmt":"2025-05-21T14:46:46","slug":"transitioning-to-new-iembeddinggenerator-interface","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/agent-framework\/transitioning-to-new-iembeddinggenerator-interface\/","title":{"rendered":"Transitioning to new Extensions AI IEmbeddingGenerator interface"},"content":{"rendered":"

\"Transitioning<\/a><\/center><\/p>\n

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.<\/p>\n

The Evolution of Embedding Generation in Semantic Kernel<\/h2>\n

Semantic Kernel has always aimed to provide a unified way to interact with AI services, including embedding generation. Our initial approach used the\u00a0ITextEmbeddingGenerationService<\/code>\u00a0interface, which served us well during the experimental phase. However, as the AI landscape has matured, so have our abstractions.<\/p>\n

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

Why Make the Change?<\/h2>\n

The transition to\u00a0Microsoft.Extensions.AI.IEmbeddingGenerator<\/code>\u00a0brings several benefits:<\/p>\n

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

    Code Comparison: Before and After<\/h2>\n

    Let’s look at how this transition affects your code:<\/p>\n

    Before: Using ITextEmbeddingGenerationService<\/h3>\n
    using<\/span> Microsoft.SemanticKernel;\r\nusing<\/span> Microsoft.SemanticKernel.Embeddings;\r\n\r\n\/\/ Create a kernel builder<\/span>\r\nvar<\/span> builder = Kernel.CreateBuilder();\r\n\r\n\/\/ Add the OpenAI embedding service<\/span>\r\nbuilder.Services.AddOpenAITextEmbeddingGeneration(\r\n    modelId: \"text-embedding-ada-002\"<\/span>,\r\n    apiKey: \"your-api-key\");\r\n\r\n\/\/ Build the kernel<\/span>\r\nvar<\/span> kernel = builder.Build();\r\n\r\n\/\/ Get the embedding service from the kernel<\/span>\r\nvar<\/span> embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();\r\n\r\n\/\/ Generate embeddings<\/span>\r\nvar<\/span> text = \"Semantic Kernel is a lightweight SDK that integrates Large Language Models (LLMs) with conventional programming languages.\"<\/span>;\r\nvar<\/span> embedding = await<\/span> embeddingService.GenerateEmbeddingAsync(text);\r\n\r\n\/\/ Work with the embedding vector<\/span>\r\nConsole.WriteLine($\"Generated embedding with {embedding.Length}<\/span> dimensions\"<\/span>);\r\n<\/code><\/pre>\n
    After: Using IEmbeddingGenerator<\/h3>\n
    using<\/span> Microsoft.Extensions.AI;\r\nusing<\/span> Microsoft.SemanticKernel;\r\n\r\n\/\/ Create a kernel builder<\/span>\r\nvar<\/span> builder = Kernel.CreateBuilder();\r\n\r\n\/\/ Add the OpenAI embedding generator<\/span>\r\nbuilder.Services.AddOpenAIEmbeddingGenerator(\r\n    modelId: \"text-embedding-ada-002\"<\/span>,\r\n    apiKey: \"your-api-key\");\r\n\r\n\/\/ Build the kernel<\/span>\r\nvar<\/span> kernel = builder.Build();\r\n\r\n\/\/ Get the embedding generator from the kernel<\/span>\r\nvar<\/span> embeddingGenerator = kernel.GetRequiredService<IEmbeddingGenerator<string<\/span>, Embedding<float<\/span>>>>();\r\n\r\n\/\/ Generate embeddings<\/span>\r\nvar<\/span> text = \"Semantic Kernel is a lightweight SDK that integrates Large Language Models (LLMs) with conventional programming languages.\"<\/span>;\r\nvar<\/span> embedding = await<\/span> embeddingGenerator.GenerateAsync(text);\r\n\r\n\/\/ Work with the embedding vector<\/span>\r\nConsole.WriteLine($\"Generated embedding with {embedding.Vector.Length}<\/span> dimensions\"<\/span>);\r\n<\/code><\/pre>\n
    Key Differences<\/h2>\n
      \n
    1. Method Names<\/strong>:\u00a0GenerateEmbeddingsAsync<\/code>\u00a0becomes\u00a0GenerateAsync<\/code><\/li>\n
    2. Return Type<\/strong>: Instead of returning\u00a0IList<ReadOnlyMemory<float>><\/code>, the new interface returns\u00a0GeneratedEmbeddings<Embedding<float>><\/code><\/li>\n
    3. Options<\/strong>: The new interface accepts an optional\u00a0EmbeddingGenerationOptions<\/code>\u00a0parameter for more control<\/li>\n
    4. Dimensions<\/strong>: Setting dimensions is now handled through options rather than attributes<\/li>\n<\/ol>\n
      Migrating Your Code<\/h2>\n
      If you’re currently using\u00a0ITextEmbeddingGenerationService<\/code>, here’s how to migrate:<\/p>\n
        \n
      1. Update your package references to include the latest Semantic Kernel packages<\/li>\n
      2. Replace\u00a0ITextEmbeddingGenerationService<\/code>\u00a0with\u00a0IEmbeddingGenerator<string, Embedding<float>><\/code><\/li>\n
      3. Update service registration to use the new embedding generator classes (e.g.,\u00a0OpenAIEmbeddingGenerator<\/code>\u00a0instead of\u00a0OpenAITextEmbeddingGenerationService<\/code>)<\/li>\n
      4. Update method calls from\u00a0GenerateEmbeddingsAsync<\/code>\u00a0to\u00a0GenerateAsync<\/code><\/li>\n
      5. Update how you access the embedding vectors (now through the\u00a0.Vector<\/code>\u00a0property)<\/li>\n<\/ol>\n
        Transitional Support<\/h2>\n
        To ease the transition, we’ve provided extension methods that allow you to convert between the old and new interfaces:<\/p>\n
        using<\/span> Microsoft.Extensions.AI;\r\nusing<\/span> Microsoft.SemanticKernel;\r\nusing<\/span> Microsoft.SemanticKernel.Embeddings;\r\n\r\n\/\/ Create a kernel with both old and new embedding services<\/span>\r\nvar<\/span> builder = Kernel.CreateBuilder();\r\n\r\n\/\/ Add the old OpenAI embedding service<\/span>\r\nbuilder.Services.AddOpenAITextEmbeddingGeneration(\r\n    modelId: \"text-embedding-ada-002\"<\/span>,\r\n    apiKey: \"your-api-key\");\r\n\r\n\/\/ Build the kernel<\/span>\r\nvar<\/span> kernel = builder.Build();\r\n\r\n\/\/ Get the old embedding service<\/span>\r\nvar<\/span> oldEmbeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();\r\n\r\n\/\/ Convert from old to new using extension method<\/span>\r\nIEmbeddingGenerator<string<\/span>, Embedding<float<\/span>>> newGenerator =\r\n    oldEmbeddingService.AsEmbeddingGenerator();\r\n\r\n\/\/ Use the new generator<\/span>\r\nvar<\/span> newEmbedding = await<\/span> newGenerator.GenerateAsync(\"Converting from old to new\"<\/span>);\r\nConsole.WriteLine($\"Generated embedding with {newEmbedding.Vector.Length}<\/span> dimensions\"<\/span>);\r\n<\/code><\/pre>\n
        Connector Support<\/h2>\n
        All our connectors have been updated to support the new interface:<\/p>\n