Arayüzü kullanın IEmbeddingGenerator

IEmbeddingGenerator<TInput,TEmbedding> arabirimi, eklemelerin genel bir oluşturucusunu temsil eder. Genel tür parametreleri için, TInput katıştırılan giriş değerlerinin türüdür ve TEmbedding sınıfından devralan Embedding ise oluşturulan katıştırma türüdür.

Embedding sınıfı, bir IEmbeddingGeneratortarafından oluşturulan eklemeler için temel sınıf görevi görür. Eklemelerle ilişkili meta verileri ve verileri depolamak ve yönetmek için tasarlanmıştır. gibi Embedding<T>türetilmiş türler somut ekleme vektör verilerini sağlar. Örneğin, bir Embedding<float>, gömülü verilerine erişim sağlamak için bir ReadOnlyMemory<float> Vector { get; } özelliği sunar.

IEmbeddingGenerator arabirimi, isteğe bağlı yapılandırma ve iptal desteğiyle bir giriş değerleri koleksiyonu için zaman uyumsuz olarak eklemeler oluşturmak için bir yöntem tanımlar. Ayrıca oluşturucuyu açıklayan meta veriler sağlar ve oluşturucu veya temel hizmetleri tarafından sağlanabilecek türü kesin belirlenmiş hizmetlerin elde edilmesine olanak tanır.

Gömüler oluştur

bir IEmbeddingGenerator<TInput,TEmbedding> ile gerçekleştirilen birincil işlem, GenerateAsync yöntemiyle gerçekleştirilen ekleme oluşturma işlemidir.

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

Hızlandırıcı uzantısı yöntemleri, tek bir girişten ekleme vektöru oluşturma gibi yaygın durumları basitleştirmek için de mevcuttur.

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

İşlevsellik işlem hatları

IChatClientgibi IEmbeddingGenerator uygulamaları katmanlanabilir. Microsoft.Extensions.AI , önbelleğe alma ve telemetri için IEmbeddingGenerator bir temsilci uygulaması sağlar.

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

IEmbeddingGenerator, bir IEmbeddingGeneratorişlevselliğini genişleten özel ara yazılım oluşturulmasını sağlar. DelegatingEmbeddingGenerator<TInput,TEmbedding> sınıfı, işlemlerini başka bir IEmbeddingGenerator<TInput, TEmbedding> örneğine devreden ekleme oluşturucuları oluşturmak için temel sınıf görevi görecek IEmbeddingGenerator<TInput, TEmbedding> arabiriminin bir uygulamasıdır. Birden çok üreteci herhangi bir sırayla zincirlemenize ve çağrıları alttaki bir üretece iletmenize olanak tanır. sınıfı, GenerateAsync ve Disposegibi yöntemler için çağrıları iç oluşturucu örneğine ileterek esnek ve modüler ekleme oluşturmayı sağlayan varsayılan uygulamalar sağlar.

Aşağıda, ekleme oluşturma isteklerini sınırlayan bu tür bir temsilci ekleme oluşturucusunun örnek uygulaması verilmiştir:

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

Herhangi bir IEmbeddingGenerator<string, Embedding<float>> etrafında katmanlandırılarak tüm ekleme oluşturma işlemlerinin hızını sınırlamak için kullanılabilir.

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

Bu şekilde, RateLimitingEmbeddingGenerator hız sınırlama işlevselliği sağlamak için diğer IEmbeddingGenerator<string, Embedding<float>> örneklerle oluşturulabilir.

Uygulama örneği

Çoğu kullanıcının IEmbeddingGenerator arabirimini uygulamasına gerek yoktur. Ancak, kitaplık yazarıysanız bu uygulama örneklerine bakmak yararlı olabilir.

Aşağıdaki kod, SampleEmbeddingGenerator sınıfının IEmbeddingGenerator<TInput,TEmbedding> arabirimini nasıl uyguladığını gösterir. Oluşturucuyu tanımlamak için kullanılan bir uç nokta ve model kimliği kabul eden bir birincil oluşturucuya sahiptir. Ayrıca, GenerateAsync(IEnumerable<TInput>, EmbeddingGenerationOptions, CancellationToken) yöntemini giriş değerleri koleksiyonu için yerleştirmeler oluşturmak amacıyla uygular.

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() { }
}

Bu örnek uygulama yalnızca rastgele ekleme vektörleri oluşturur. Daha gerçekçi ve somut bir uygulama için bkz. OpenTelemetryEmbeddingGenerator.cs.