Utilizar a interface IEmbeddingGenerator

A interface IEmbeddingGenerator<TInput,TEmbedding> representa um gerador genérico de incorporações. Para os parâmetros de tipo genéricos, TInput é o tipo de valores de entrada que estão sendo incorporados e TEmbedding é o tipo de incorporação gerada, que herda da Embedding classe.

A classe Embedding serve como uma classe base para incorporações geradas por um IEmbeddingGenerator. Ele foi projetado para armazenar e gerenciar os metadados e dados associados às incorporações. Tipos derivados, como Embedding<T>, fornecem os dados vetoriais de incorporação de concreto. Por exemplo, um Embedding<float> expõe uma ReadOnlyMemory<float> Vector { get; } propriedade para acesso aos seus dados incorporados.

A interface IEmbeddingGenerator define um método para gerar incorporações de forma assíncrona para uma coleção de valores de entrada, com suporte opcional a configuração e cancelamento. Ele também fornece metadados que descrevem o gerador e permite a recuperação de serviços fortemente tipados que podem ser fornecidos pelo gerador ou seus serviços subjacentes.

Criar incorporações

A principal operação realizada com um IEmbeddingGenerator<TInput,TEmbedding> é a geração de inserções, que é efetuada através do seu método GenerateAsync.

using Microsoft.Extensions.AI;
using OllamaSharp;

IEmbeddingGenerator<string, Embedding<float>> generator =
    new OllamaApiClient(new Uri("http://localhost:11434/"), "phi3:mini");

foreach (Embedding<float> embedding in
    await generator.GenerateAsync(["What is AI?", "What is .NET?"]))
{
    Console.WriteLine(string.Join(", ", embedding.Vector.ToArray()));
}

Os métodos de extensão do acelerador também existem para simplificar casos comuns, como a geração de um vetor de incorporação a partir de uma única entrada.

ReadOnlyMemory<float> vector = await generator.GenerateVectorAsync("What is AI?");

Cadeias de funcionalidade

Tal como acontece com IChatClient, IEmbeddingGenerator implementações podem ser colocadas em camadas. Microsoft.Extensions.AI fornece uma implementação de delegação para IEmbeddingGenerator para a cache e telemetria.

using Microsoft.Extensions.AI;
using Microsoft.Extensions.Caching.Distributed;
using Microsoft.Extensions.Caching.Memory;
using Microsoft.Extensions.Options;
using OllamaSharp;
using OpenTelemetry.Trace;

// Configure OpenTelemetry exporter
string sourceName = Guid.NewGuid().ToString();
TracerProvider tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
    .AddSource(sourceName)
    .AddConsoleExporter()
    .Build();

// Explore changing the order of the intermediate "Use" calls to see
// what impact that has on what gets cached and traced.
IEmbeddingGenerator<string, Embedding<float>> generator = new EmbeddingGeneratorBuilder<string, Embedding<float>>(
        new OllamaApiClient(new Uri("http://localhost:11434/"), "phi3:mini"))
    .UseDistributedCache(
        new MemoryDistributedCache(
            Options.Create(new MemoryDistributedCacheOptions())))
    .UseOpenTelemetry(sourceName: sourceName)
    .Build();

GeneratedEmbeddings<Embedding<float>> embeddings = await generator.GenerateAsync(
[
    "What is AI?",
    "What is .NET?",
    "What is AI?"
]);

foreach (Embedding<float> embedding in embeddings)
{
    Console.WriteLine(string.Join(", ", embedding.Vector.ToArray()));
}

O IEmbeddingGenerator permite a criação de middleware personalizado que estende a funcionalidade de um IEmbeddingGenerator. A classe DelegatingEmbeddingGenerator<TInput,TEmbedding> é uma implementação da interface IEmbeddingGenerator<TInput, TEmbedding> que serve como uma classe base para criar geradores de incorporação que delegam suas operações a outra instância IEmbeddingGenerator<TInput, TEmbedding>. Ele permite encadear vários geradores em qualquer ordem, redirecionando chamadas para um gerador subjacente. A classe fornece implementações padrão para métodos como GenerateAsync e Dispose, que encaminham as chamadas para a instância interna do gerador, permitindo a geração de incorporação flexível e modular.

A seguir está um exemplo de implementação de tal gerador de incorporação delegando que limita a taxa de incorporação de solicitações de geração:

using Microsoft.Extensions.AI;
using System.Threading.RateLimiting;

public class RateLimitingEmbeddingGenerator(
    IEmbeddingGenerator<string, Embedding<float>> innerGenerator, RateLimiter rateLimiter)
        : DelegatingEmbeddingGenerator<string, Embedding<float>>(innerGenerator)
{
    public override async Task<GeneratedEmbeddings<Embedding<float>>> GenerateAsync(
        IEnumerable<string> values,
        EmbeddingGenerationOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        using var lease = await rateLimiter.AcquireAsync(permitCount: 1, cancellationToken)
            .ConfigureAwait(false);

        if (!lease.IsAcquired)
        {
            throw new InvalidOperationException("Unable to acquire lease.");
        }

        return await base.GenerateAsync(values, options, cancellationToken);
    }

    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            rateLimiter.Dispose();
        }

        base.Dispose(disposing);
    }
}

Isso pode então ser colocado em camadas em torno de um limite arbitrário IEmbeddingGenerator<string, Embedding<float>> para taxa de todas as operações de geração de incorporação.

using Microsoft.Extensions.AI;
using OllamaSharp;
using System.Threading.RateLimiting;

IEmbeddingGenerator<string, Embedding<float>> generator =
    new RateLimitingEmbeddingGenerator(
        new OllamaApiClient(new Uri("http://localhost:11434/"), "phi3:mini"),
        new ConcurrencyLimiter(new()
        {
            PermitLimit = 1,
            QueueLimit = int.MaxValue
        }));

foreach (Embedding<float> embedding in
    await generator.GenerateAsync(["What is AI?", "What is .NET?"]))
{
    Console.WriteLine(string.Join(", ", embedding.Vector.ToArray()));
}

Dessa forma, o RateLimitingEmbeddingGenerator pode ser composto com outras IEmbeddingGenerator<string, Embedding<float>> instâncias para fornecer funcionalidade de limitação de taxa.

Exemplo de Implementação

A maioria dos usuários não precisa implementar a IEmbeddingGenerator interface. No entanto, se é autor de bibliotecas, pode ser útil consultar estes exemplos de implementação.

O código seguinte mostra como a SampleEmbeddingGenerator classe implementa a IEmbeddingGenerator<TInput,TEmbedding> interface. Tem um construtor primário que aceita um endpoint e um ID de modelo, que são usados para identificar o gerador. Implementa também o GenerateAsync(IEnumerable<TInput>, EmbeddingGenerationOptions, CancellationToken) método para gerar embeddings para uma coleção de valores de entrada.

using Microsoft.Extensions.AI;

public sealed class SampleEmbeddingGenerator(
    Uri endpoint, string modelId)
        : IEmbeddingGenerator<string, Embedding<float>>
{
    private readonly EmbeddingGeneratorMetadata _metadata =
        new("SampleEmbeddingGenerator", endpoint, modelId);

    public async Task<GeneratedEmbeddings<Embedding<float>>> GenerateAsync(
        IEnumerable<string> values,
        EmbeddingGenerationOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        // Simulate some async operation.
        await Task.Delay(100, cancellationToken);

        // Create random embeddings.
        return [.. from value in values
            select new Embedding<float>(
                Enumerable.Range(0, 384)
                .Select(_ => Random.Shared.NextSingle()).ToArray())];
    }

    public object? GetService(Type serviceType, object? serviceKey) =>
        serviceKey is not null
        ? null
        : serviceType == typeof(EmbeddingGeneratorMetadata)
            ? _metadata
            : serviceType?.IsInstanceOfType(this) is true
                ? this
                : null;

    void IDisposable.Dispose() { }
}

Esta implementação de exemplo apenas gera vetores de embedding aleatórios. Para uma implementação mais realista e concreta, veja OpenTelemetryEmbeddingGenerator.cs.