Geração de incorporação de texto no kernel semântico

Com a geração de incorporação de texto, você pode usar um modelo de IA para gerar vetores (também conhecidos como incorporações). Estes vetores codificam o significado semântico do texto de tal forma que equações matemáticas podem ser usadas em dois vetores para comparar a semelhança do texto original. Isso é útil para cenários como o Retrieval Augmented Generation (RAG), onde queremos pesquisar um banco de dados de informações para texto relacionado a uma consulta do usuário. Qualquer informação correspondente pode ser fornecida como entrada para a conclusão do bate-papo, para que o modelo de IA tenha mais contexto ao responder à consulta do usuário.

Ao escolher um modelo de incorporação, você precisará considerar o seguinte:

Qual é o tamanho dos vetores gerados pelo modelo, e é configurável, pois isso afetará seu custo de armazenamento vetorial.
Que tipo de elementos os vetores gerados contêm, por exemplo, float32, float16, etc, pois isso afetará seu custo de armazenamento vetorial.
Com que rapidez gera vetores?
Quanto custa a geração?

Dica

Para obter mais informações sobre como armazenar e pesquisar vetores, consulte O que são conectores do Semantic Kernel Vetor Store?

Dica

Para obter mais informações sobre como usar o RAG com armazenamentos vetoriais no Kernel Semântico, consulte Como usar repositórios vetoriais com o Kernel Semântico e O que são plugins de Pesquisa de Texto do Kernel Semântico?

Configurando seu ambiente local

Alguns dos Serviços de IA podem ser hospedados localmente e podem exigir alguma configuração. Abaixo estão instruções para aqueles que apoiam isso.

Nenhuma configuração local.

Para executar o Ollama localmente usando o docker, use o seguinte comando para iniciar um contêiner usando a CPU.

docker run -d -v "c:\temp\ollama:/root/.ollama" -p 11434:11434 --name ollama ollama/ollama

Para executar o Ollama localmente usando o docker, use o seguinte comando para iniciar um contêiner usando GPUs.

docker run -d --gpus=all -v "c:\temp\ollama:/root/.ollama" -p 11434:11434 --name ollama ollama/ollama

Depois que o contêiner for iniciado, inicie uma janela do Terminal para o contêiner do docker, por exemplo, se estiver usando a área de trabalho do docker, escolha Open in Terminal das ações.

A partir deste terminal, faça o download dos modelos necessários, por exemplo, aqui estamos baixando o modelo de incorporação mxbai-embed-large.

ollama pull mxbai-embed-large

Clone o repositório que contém o modelo ONNX que você gostaria de usar.

git clone https://huggingface.co/TaylorAI/bge-micro-v2

Instalando os pacotes necessários

Antes de adicionar a geração de embeddings ao seu kernel, será necessário instalar os pacotes necessários. Abaixo estão os pacotes que você precisará instalar para cada provedor de serviços de IA.

dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI

dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI

dotnet add package Microsoft.SemanticKernel.Connectors.MistralAI --prerelease

dotnet add package Microsoft.SemanticKernel.Connectors.Google --prerelease

dotnet add package Microsoft.SemanticKernel.Connectors.HuggingFace --prerelease

dotnet add package Microsoft.SemanticKernel.Connectors.Ollama --prerelease

dotnet add package Microsoft.SemanticKernel.Connectors.Onnx --prerelease

Criação de serviços de geração de incorporação de texto

Agora que você instalou os pacotes necessários, você pode criar um serviço de geração de incorporação de texto. Abaixo estão as várias maneiras de criar serviços de geração de incorporação de texto usando o Kernel Semântico.

Adicionando diretamente ao kernel

Para adicionar um serviço de geração de incorporação de texto, você pode usar o código a seguir para adicioná-lo ao provedor de serviços interno do kernel.

Importante

O conector de geração de embeddings do Azure OpenAI é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0010.

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0010
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddAzureOpenAITextEmbeddingGeneration(
    deploymentName: "NAME_OF_YOUR_DEPLOYMENT", // Name of deployment, e.g. "text-embedding-ada-002".
    endpoint: "YOUR_AZURE_ENDPOINT",           // Name of Azure OpenAI service endpoint, e.g. https://myaiservice.openai.azure.com.
    apiKey: "YOUR_API_KEY",
    modelId: "MODEL_ID",          // Optional name of the underlying model if the deployment name doesn't match the model name, e.g. text-embedding-ada-002.
    serviceId: "YOUR_SERVICE_ID", // Optional; for targeting specific services within Semantic Kernel.
    httpClient: new HttpClient(), // Optional; if not provided, the HttpClient from the kernel will be used.
    dimensions: 1536              // Optional number of dimensions to generate embeddings with.
);
Kernel kernel = kernelBuilder.Build();

Importante

O conector de geração de embeddings da OpenAI é experimental neste momento. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0010.

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0010
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddOpenAITextEmbeddingGeneration(
    modelId: "MODEL_ID",          // Name of the embedding model, e.g. "text-embedding-ada-002".
    apiKey: "YOUR_API_KEY",
    orgId: "YOUR_ORG_ID",         // Optional organization id.
    serviceId: "YOUR_SERVICE_ID", // Optional; for targeting specific services within Semantic Kernel
    httpClient: new HttpClient(), // Optional; if not provided, the HttpClient from the kernel will be used
    dimensions: 1536              // Optional number of dimensions to generate embeddings with.
);
Kernel kernel = kernelBuilder.Build();

Importante

O conector de geração de incorporação do Mistral é experimental atualmente. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0070
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddMistralTextEmbeddingGeneration(
    modelId: "NAME_OF_MODEL",           // Name of the embedding model, e.g. "mistral-embed".
    apiKey: "API_KEY",
    endpoint: new Uri("YOUR_ENDPOINT"), // Optional uri endpoint including the port where MistralAI server is hosted. Default is https://api.mistral.ai.
    serviceId: "SERVICE_ID",            // Optional; for targeting specific services within Semantic Kernel
    httpClient: new HttpClient()        // Optional; for customizing HTTP client
);
Kernel kernel = kernelBuilder.Build();

Importante

O conector de geração de embeddings do Google é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.Google;

#pragma warning disable SKEXP0070
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddGoogleAIEmbeddingGeneration(
    modelId: "NAME_OF_MODEL",       // Name of the embedding model, e.g. "models/text-embedding-004".
    apiKey: "API_KEY",
    apiVersion: GoogleAIVersion.V1, // Optional
    serviceId: "SERVICE_ID",        // Optional; for targeting specific services within Semantic Kernel
    httpClient: new HttpClient()    // Optional; for customizing HTTP client
);
Kernel kernel = kernelBuilder.Build();

Importante

O conector de geração de incorporação Hugging Face é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0070
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddHuggingFaceTextEmbeddingGeneration(
    model: "NAME_OF_MODEL",             // Name of the embedding model.
    apiKey: "API_KEY",
    endpoint: new Uri("YOUR_ENDPOINT"), // Optional
    serviceId: "SERVICE_ID",            // Optional; for targeting specific services within Semantic Kernel
    httpClient: new HttpClient()        // Optional; for customizing HTTP client
);
Kernel kernel = kernelBuilder.Build();

Importante

O conector de geração de embeddings Ollama está em fase experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0070
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddOllamaTextEmbeddingGeneration(
    modelId: "NAME_OF_MODEL",           // E.g. "mxbai-embed-large" if mxbai-embed-large was downloaded as described above.
    endpoint: new Uri("YOUR_ENDPOINT"), // E.g. "http://localhost:11434" if Ollama has been started in docker as described above.
    serviceId: "SERVICE_ID"             // Optional; for targeting specific services within Semantic Kernel
);
Kernel kernel = kernelBuilder.Build();

Importante

O conector de geração de incorporação ONNX é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0070
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddBertOnnxTextEmbeddingGeneration(
    onnxModelPath: "PATH_ON_DISK",       // Path to the model on disk e.g. C:\Repos\huggingface\microsoft\TaylorAI\bge-micro-v2\onnx\model.onnx
    vocabPath: "VOCABULARY_PATH_ON_DISK",// Path to the vocabulary file on disk, e.g. C:\Repos\huggingface\TailorAI\bge-micro-v2\vocab.txt
    serviceId: "SERVICE_ID"              // Optional; for targeting specific services within Semantic Kernel
);
Kernel kernel = kernelBuilder.Build();

Usando injeção de dependência

Se você estiver usando a injeção de dependência, provavelmente desejará adicionar seus serviços de geração de incorporação de texto diretamente ao provedor de serviços. Isto é útil se quiseres criar singletons dos teus serviços de geração de embeddings e reutilizá-los em kernels transitórios.

Importante

O conector de geração de incorporação do Azure OpenAI é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0010.

using Microsoft.SemanticKernel;

var builder = Host.CreateApplicationBuilder(args);

#pragma warning disable SKEXP0010
builder.Services.AddAzureOpenAITextEmbeddingGeneration(
    deploymentName: "NAME_OF_YOUR_DEPLOYMENT", // Name of deployment, e.g. "text-embedding-ada-002".
    endpoint: "YOUR_AZURE_ENDPOINT",           // Name of Azure OpenAI service endpoint, e.g. https://myaiservice.openai.azure.com.
    apiKey: "YOUR_API_KEY",
    modelId: "MODEL_ID",          // Optional name of the underlying model if the deployment name doesn't match the model name, e.g. text-embedding-ada-002.
    serviceId: "YOUR_SERVICE_ID", // Optional; for targeting specific services within Semantic Kernel.
    dimensions: 1536              // Optional number of dimensions to generate embeddings with.
);

builder.Services.AddTransient((serviceProvider)=> {
    return new Kernel(serviceProvider);
});

Importante

O conector de geração de embeddings OpenAI é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0010.

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0010
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddOpenAITextEmbeddingGeneration(
    modelId: "MODEL_ID",          // Name of the embedding model, e.g. "text-embedding-ada-002".
    apiKey: "YOUR_API_KEY",
    orgId: "YOUR_ORG_ID",         // Optional organization id.
    serviceId: "YOUR_SERVICE_ID", // Optional; for targeting specific services within Semantic Kernel
    dimensions: 1536              // Optional number of dimensions to generate embeddings with.
);

builder.Services.AddTransient((serviceProvider)=> {
    return new Kernel(serviceProvider);
});

Importante

O conector de geração de embeddings Mistral é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

var builder = Host.CreateApplicationBuilder(args);

#pragma warning disable SKEXP0070
builder.Services.AddMistralTextEmbeddingGeneration(
    modelId: "NAME_OF_MODEL",           // Name of the embedding model, e.g. "mistral-embed".
    apiKey: "API_KEY",
    endpoint: new Uri("YOUR_ENDPOINT"), // Optional uri endpoint including the port where MistralAI server is hosted. Default is https://api.mistral.ai.
    serviceId: "SERVICE_ID"             // Optional; for targeting specific services within Semantic Kernel
);

builder.Services.AddTransient((serviceProvider)=> {
    return new Kernel(serviceProvider);
});

Importante

Atualmente, o conector de geração de incorporação do Google é experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.Google;

var builder = Host.CreateApplicationBuilder(args);

#pragma warning disable SKEXP0070
builder.Services.AddGoogleAIEmbeddingGeneration(
    modelId: "NAME_OF_MODEL",       // Name of the embedding model, e.g. "models/text-embedding-004".
    apiKey: "API_KEY",
    apiVersion: GoogleAIVersion.V1, // Optional
    serviceId: "SERVICE_ID"         // Optional; for targeting specific services within Semantic Kernel
);

builder.Services.AddTransient((serviceProvider)=> {
    return new Kernel(serviceProvider);
});

Importante

O conector de geração de embeddings Hugging Face é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

var builder = Host.CreateApplicationBuilder(args);

#pragma warning disable SKEXP0070
builder.Services.AddHuggingFaceTextEmbeddingGeneration(
    model: "NAME_OF_MODEL",             // Name of the embedding model.
    apiKey: "API_KEY",
    endpoint: new Uri("YOUR_ENDPOINT"), // Optional
    serviceId: "SERVICE_ID",            // Optional; for targeting specific services within Semantic Kernel
    httpClient: new HttpClient()        // Optional; for customizing HTTP client
);

builder.Services.AddTransient((serviceProvider)=> {
    return new Kernel(serviceProvider);
});

Importante

O conector de geração de incorporação Ollama é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

var builder = Host.CreateApplicationBuilder(args);

#pragma warning disable SKEXP0070
builder.Services.AddOllamaTextEmbeddingGeneration(
    modelId: "NAME_OF_MODEL",           // E.g. "mxbai-embed-large" if mxbai-embed-large was downloaded as described above.
    endpoint: new Uri("YOUR_ENDPOINT"), // E.g. "http://localhost:11434" if Ollama has been started in docker as described above.
    serviceId: "SERVICE_ID"             // Optional; for targeting specific services within Semantic Kernel
);

builder.Services.AddTransient((serviceProvider)=> {
    return new Kernel(serviceProvider);
});

Importante

O conector de geração de embeddings ONNX é neste momento experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel;

var builder = Host.CreateApplicationBuilder(args);

#pragma warning disable SKEXP0070
builder.Services.AddBertOnnxTextEmbeddingGeneration(
    onnxModelPath: "PATH_ON_DISK",       // Path to the model on disk e.g. C:\Repos\huggingface\microsoft\TaylorAI\bge-micro-v2\onnx\model.onnx
    vocabPath: "VOCABULARY_PATH_ON_DISK",// Path to the vocabulary file on disk, e.g. C:\Repos\huggingface\TailorAI\bge-micro-v2\vocab.txt
    serviceId: "SERVICE_ID"              // Optional; for targeting specific services within Semantic Kernel
);

builder.Services.AddTransient((serviceProvider)=> {
    return new Kernel(serviceProvider);
});

Criação de instâncias autônomas

Por fim, você pode criar instâncias do serviço diretamente para que você possa adicioná-las a um kernel mais tarde ou usá-las diretamente em seu código sem nunca injetá-las no kernel ou em um provedor de serviços.

Importante

O conector de geração de embeddings do Azure OpenAI é experimental atualmente. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0010.

using Microsoft.SemanticKernel.Connectors.AzureOpenAI;

#pragma warning disable SKEXP0010
AzureOpenAITextEmbeddingGenerationService textEmbeddingGenerationService = new (
    deploymentName: "NAME_OF_YOUR_DEPLOYMENT", // Name of deployment, e.g. "text-embedding-ada-002".
    endpoint: "YOUR_AZURE_ENDPOINT",           // Name of Azure OpenAI service endpoint, e.g. https://myaiservice.openai.azure.com.
    apiKey: "YOUR_API_KEY",
    modelId: "MODEL_ID",          // Optional name of the underlying model if the deployment name doesn't match the model name, e.g. text-embedding-ada-002.
    httpClient: new HttpClient(), // Optional; if not provided, the HttpClient from the kernel will be used.
    dimensions: 1536              // Optional number of dimensions to generate embeddings with.
);

Importante

O conector para geração de embeddings da OpenAI é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0010.

#pragma warning disable SKEXP0010
using Microsoft.SemanticKernel.Connectors.OpenAI;
OpenAITextEmbeddingGenerationService textEmbeddingGenerationService = new (
    modelId: "MODEL_ID",          // Name of the embedding model, e.g. "text-embedding-ada-002".
    apiKey: "YOUR_API_KEY",
    organization: "YOUR_ORG_ID",  // Optional organization id.
    httpClient: new HttpClient(), // Optional; if not provided, the HttpClient from the kernel will be used
    dimensions: 1536              // Optional number of dimensions to generate embeddings with.
);

Importante

O conector de geração de incorporação Mistral é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel.Connectors.MistralAI;

#pragma warning disable SKEXP0070
MistralAITextEmbeddingGenerationService textEmbeddingGenerationService = new (
    modelId: "NAME_OF_MODEL",           // Name of the embedding model, e.g. "mistral-embed".
    apiKey: "API_KEY",
    endpoint: new Uri("YOUR_ENDPOINT"), // Optional uri endpoint including the port where MistralAI server is hosted. Default is https://api.mistral.ai.
    httpClient: new HttpClient()        // Optional; for customizing HTTP client
);

Importante

O conector de geração de incorporação do Google é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel.Connectors.Google;

#pragma warning disable SKEXP0070
GoogleAITextEmbeddingGenerationService textEmbeddingGenerationService = new (
    modelId: "NAME_OF_MODEL",       // Name of the embedding model, e.g. "models/text-embedding-004".
    apiKey: "API_KEY",
    apiVersion: GoogleAIVersion.V1, // Optional
    httpClient: new HttpClient()    // Optional; for customizing HTTP client
);

Importante

O conector de geração de embeddings Hugging Face é atualmente experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel.Connectors.HuggingFace;

#pragma warning disable SKEXP0070
HuggingFaceTextEmbeddingGenerationService textEmbeddingGenerationService = new (
    model: "NAME_OF_MODEL",             // Name of the embedding model.
    apiKey: "API_KEY",
    endpoint: new Uri("YOUR_ENDPOINT"), // Optional
    httpClient: new HttpClient()        // Optional; for customizing HTTP client
);

Importante

O conector de geração de incorporação Ollama é de momento experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel.Embeddings;
using OllamaSharp;

#pragma warning disable SKEXP0070
using var ollamaClient = new OllamaApiClient(
    uriString: "YOUR_ENDPOINT"    // E.g. "http://localhost:11434" if Ollama has been started in docker as described above.
    defaultModel: "NAME_OF_MODEL" // E.g. "mxbai-embed-large" if mxbai-embed-large was downloaded as described above.
);

ITextEmbeddingGenerationService textEmbeddingGenerationService = ollamaClient.AsTextEmbeddingGenerationService();

Importante

O conector de geração de embeddings ONNX está em fase experimental. Para usá-lo, você precisará adicionar #pragma warning disable SKEXP0070.

using Microsoft.SemanticKernel.Connectors.Onnx;

#pragma warning disable SKEXP0070
BertOnnxTextEmbeddingGenerationService textEmbeddingGenerationService = await BertOnnxTextEmbeddingGenerationService.CreateAsync(
    onnxModelPath: "PATH_ON_DISK",       // Path to the model on disk e.g. C:\Repos\huggingface\microsoft\TaylorAI\bge-micro-v2\onnx\model.onnx
    vocabPath: "VOCABULARY_PATH_ON_DISK" // Path to the vocabulary file on disk, e.g. C:\Repos\huggingface\TailorAI\bge-micro-v2\vocab.txt
);

Usando serviços de geração de incorporação de texto

Todos os serviços de geração de incorporação de texto implementam o ITextEmbeddingGenerationService, que tem um único método GenerateEmbeddingsAsync capaz de gerar vetores ReadOnlyMemory<float> a partir dos valores string fornecidos. Um método de extensão GenerateEmbeddingAsync também está disponível para versões de valor único da mesma ação.

Aqui está um exemplo de como invocar o serviço com vários valores.

IList<ReadOnlyMemory<float>> embeddings =
    await textEmbeddingGenerationService.GenerateEmbeddingsAsync(
    [
        "sample text 1",
        "sample text 2"
    ]);

Aqui está um exemplo de como invocar o serviço com um único valor.

using Microsoft.SemanticKernel.Embeddings;

ReadOnlyMemory<float> embedding =
    await textEmbeddingGenerationService.GenerateEmbeddingAsync("sample text");

Brevemente

Mais informações em breve.

Brevemente

Mais informações em breve.

Last updated on 2025-03-07

Compartilhar via

Geração de incorporação de texto no kernel semântico

Configurando seu ambiente local

Instalando os pacotes necessários

Criação de serviços de geração de incorporação de texto

Adicionando diretamente ao kernel

Usando injeção de dependência

Criação de instâncias autônomas

Usando serviços de geração de incorporação de texto

Brevemente

Brevemente

Recursos adicionais