Implementation:Microsoft Semantic kernel IEmbeddingGenerator GenerateAsync

Overview

This page documents the IEmbeddingGenerator<string, Embedding<float>>.GenerateAsync method, which converts text input into dense vector embeddings for storage in vector stores and for use as query vectors in similarity search.

Source Reference

File: dotnet/samples/GettingStartedWithVectorStores/Step1_Ingest_Data.cs (line 49)
Type: Wrapper Doc

API Reference

Method Signature

Task<GeneratedEmbeddings<Embedding<float>>> GenerateAsync(
    IEnumerable<string> input,
    CancellationToken cancellationToken = default);

Aspect	Detail
Interface	`IEmbeddingGenerator<string, Embedding<float>>`
Namespace	`Microsoft.Extensions.AI`
Returns	`Task<GeneratedEmbeddings<Embedding<float>>>`
Parameters	`input` — one or more strings to embed; `cancellationToken` — optional cancellation token

Accessing the Vector

The returned GeneratedEmbeddings collection contains Embedding<float> objects. To extract the raw vector for storage in a data model property:

ReadOnlyMemory<float> vector = (await embeddingGenerator.GenerateAsync(text)).Vector;

The .Vector property returns a ReadOnlyMemory<float>, which is the type expected by [VectorStoreVector] properties on data model classes.

Usage: Single Text Embedding

The most common usage during ingestion is embedding a single text field from a record:

// Generate embedding for a single definition
entry.DefinitionEmbedding = (await embeddingGenerator.GenerateAsync(entry.Definition)).Vector;

This pattern:

Passes the text content (entry.Definition) to the embedding model
Awaits the asynchronous response
Extracts the .Vector property (a ReadOnlyMemory<float>)
Assigns it to the record's vector property

Usage: Query Embedding

At query time, the same method embeds the user's search query:

// Embed the search query
var searchVector = (await embeddingGenerator.GenerateAsync(query)).Vector;

// Use the vector for similarity search
await foreach (var result in collection.SearchAsync(searchVector, top: 5))
{
    Console.WriteLine($"{result.Record.Term}: {result.Score}");
}

It is critical that the same embedding model instance (or at minimum, the same model) is used for both ingestion and query embedding. Using different models produces incomparable vectors.

Usage: Batch Embedding

When ingesting multiple records, you can batch the embedding requests:

// Collect all texts to embed
var texts = glossaryEntries.Select(e => e.Definition).ToList();

// Generate all embeddings in a single call
var embeddings = await embeddingGenerator.GenerateAsync(texts);

// Assign embeddings to records
for (int i = 0; i < glossaryEntries.Count; i++)
{
    glossaryEntries[i].DefinitionEmbedding = embeddings[i].Vector;
}

Batch embedding is more efficient than individual calls because it reduces network round-trips to the embedding service.

Obtaining an IEmbeddingGenerator Instance

The IEmbeddingGenerator interface is implemented by various providers. Common ways to obtain an instance:

Via Semantic Kernel Builder

var kernel = Kernel.CreateBuilder()
    .AddOpenAITextEmbeddingGeneration("text-embedding-ada-002", apiKey)
    .Build();

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

Via Direct Construction

var embeddingGenerator = new OpenAITextEmbeddingGenerationService(
    modelId: "text-embedding-ada-002",
    apiKey: apiKey);

Via Dependency Injection

services.AddOpenAITextEmbeddingGeneration("text-embedding-ada-002", apiKey);

// Later, injected via constructor
public class MyService(IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator)
{
    // Use embeddingGenerator
}

Return Type Breakdown

The full return type chain:

GenerateAsync(input)
  └─ returns Task<GeneratedEmbeddings<Embedding<float>>>
       └─ GeneratedEmbeddings<T> implements IList<T>
            └─ Embedding<float>
                 └─ .Vector → ReadOnlyMemory<float>

GeneratedEmbeddings<T>: A collection of embedding results, one per input string. Implements IList<T> so you can index into it.
Embedding<float>: A single embedding result containing the vector and optional metadata.
.Vector: The actual ReadOnlyMemory<float> containing the floating-point values.

When a single string is passed, the result collection has one element. The shorthand .Vector directly on the collection accesses the first (and only) element's vector.

Error Scenarios

Scenario	Behavior
Empty input string	Returns a valid embedding (model-dependent, often a zero-like vector)
Input exceeds model context window	Provider-specific error (truncation or exception)
Network failure	`HttpRequestException` or provider-specific exception
Invalid API key	Authentication exception from the provider

Relationship to Principle

This implementation page corresponds to the Embedding Generation principle, which explains the role of embeddings in the vector store pipeline and the importance of model consistency.

Principle:Microsoft_Semantic_kernel_Embedding_Generation

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment