Condividi tramite

Migrazione da ITextEmbeddingGenerationService a IEmbeddingGenerator

Man mano che il Kernel Semantico sposta le sue astrazioni fondamentali in Microsoft.Extensions.AI, stiamo rendendo obsolete e abbandonando le nostre interfacce di incorporamento sperimentali a favore delle nuove astrazioni standardizzate che offrono un modo più coerente e potente per lavorare con i servizi di intelligenza artificiale nell'ecosistema .NET.

Questa guida consente di eseguire la migrazione dall'interfaccia obsoleta ITextEmbeddingGenerationService alla nuova Microsoft.Extensions.AI.IEmbeddingGenerator<string, Embedding<float>> interfaccia.

Perché apportare la modifica?

La transizione a Microsoft.Extensions.AI.IEmbeddingGenerator offre diversi vantaggi:

  1. Standardizzazione: è in linea con modelli di ecosistema .NET più ampi e convenzioni Microsoft.Extensions
  2. Sicurezza dei tipi: Tipizzazione più rigorosa con il tipo di ritorno generico Embedding<float>
  3. Flessibilità: supporto per diversi tipi di input e formati di incorporamento
  4. Coerenza: approccio uniforme tra diversi provider di servizi di intelligenza artificiale
  5. Integrazione: integrazione facile con altre librerie Microsoft.Extensions

Aggiornamenti dei pacchetti

Prima di eseguire la migrazione del codice, assicurarsi di avere il kernel 1.51.0 semantico o i pacchetti successivi.

Migrazione di Kernel Builder

Prima: Uso di 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");

Dopo l'uso di 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");

Migrazione della raccolta di servizi/inserimento delle dipendenze

Prima: Uso di 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");

Dopo: Uso di 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");

Migrazione dell'utilizzo dell'interfaccia

Prima: Uso di 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");

Dopo: Utilizzo di 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");

Differenze principali

  1. Nomi dei metodi: GenerateEmbeddingAsync diventa GenerateAsync
  2. Tipo restituito: invece di restituire ReadOnlyMemory<float>, la nuova interfaccia restituisce GeneratedEmbeddings<Embedding<float>>
  3. Accesso vettoriale: accedere all'incorporamento ReadOnlyMemory<float> tramite la .Vector proprietà della Embedding<float> classe
  4. Opzioni: la nuova interfaccia accetta un parametro facoltativo EmbeddingGenerationOptions per un maggiore controllo

Migrazione di più incorporamenti

Prima: Generazione di più incorporamenti

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

Dopo: Generazione di più incorporamenti

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

Sostegno transitorio

Per semplificare la transizione, semantic kernel fornisce metodi di estensione che consentono di eseguire la conversione tra le interfacce precedenti e nuove:

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

Supporto del connettore

Tutti i connettori Semantic Kernel sono stati aggiornati per supportare la nuova interfaccia:

  • OpenAI e Azure OpenAI: usare AddOpenAIEmbeddingGenerator e AddAzureOpenAIEmbeddingGenerator
  • Google AI e Vertex AI: usare AddGoogleAIEmbeddingGenerator e AddVertexAIEmbeddingGenerator
  • Amazon Bedrock: Usa AddBedrockEmbeddingGenerator
  • Hugging Face:Use AddHuggingFaceEmbeddingGenerator
  • MistralAI: Usare AddMistralEmbeddingGenerator
  • Ollama: Utilizza AddOllamaEmbeddingGenerator
  • ONNX: Usare AddBertOnnxEmbeddingGenerator

Ogni connettore ora fornisce sia il servizio legacy (contrassegnato come obsoleto) che la nuova implementazione del generatore.

Esempio di OpenAI di Azure

Prima di: Azure OpenAI con 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>();

Dopo: Azure OpenAI con 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>>>();

Uso delle opzioni di generazione di embedding

La nuova interfaccia supporta opzioni aggiuntive per un maggiore controllo sulla generazione di incorporamenti.

Prima: Opzioni limitate

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

Dopo: Supporto delle opzioni avanzate

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

Lavorare con store vettoriali

La nuova IEmbeddingGenerator interfaccia si integra perfettamente con gli archivi vettoriali del kernel semantico:

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

Creazione di istanze di servizio diretto

Prima: Creazione diretta del servizio

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

Dopo: Uso di 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();

Passaggi successivi

  1. Aggiornare i riferimenti al pacchetto alle versioni più recenti del kernel semantico
  2. Sostituire ITextEmbeddingGenerationService con IEmbeddingGenerator<string, Embedding<float>>
  3. Aggiorna la registrazione del servizio per utilizzare i nuovi metodi del generatore di embedding (ad esempio, AddOpenAIEmbeddingGenerator)
  4. Aggiornare le chiamate al metodo da GenerateEmbeddingAsync/GenerateEmbeddingsAsync a GenerateAsync
  5. Aggiornare la modalità di accesso ai vettori di incorporamento (ora tramite la .Vector proprietà )
  6. Prendere in considerazione l'uso del nuovo parametro di opzioni per un controllo aggiuntivo
  7. Testare l'applicazione per assicurarsi che la migrazione sia riuscita

L'interfaccia precedente continuerà a funzionare per il momento, ma è contrassegnata come obsoleta e verrà rimossa in una versione futura. Si consiglia a tutti gli utenti del kernel semantico di eseguire la migrazione alla nuova IEmbeddingGenerator<string, Embedding<float>> interfaccia il prima possibile.

Per altre informazioni su Microsoft.Extensions.AI, vedere l'annuncio ufficiale.