Gerar embeddings de texto com o Foundry Local

O Foundry Local SDK fornece uma API de incorporação que converte texto em vetores numéricos no dispositivo. Use estes vetores para pesquisa por similaridade, classificação, agrupamento e geração aumentada por recuperação (RAG).

O SDK suporta a geração de embeddings de entrada única e em lote através de um cliente de embeddings dedicado.

Pré-requisitos

Python 3.11 ou posteriores instalados.

Repositório de samples

O código de exemplo completo deste artigo está disponível no repositório foundry-samples do GitHub. Para clonar o repositório e navegar até ao exemplo de uso:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/python/foundry-local/embeddings

Pacotes de instalação

Se estiver a desenvolver ou a enviar no Windows, selecione o separador Windows. O pacote Windows integra-se com o runtime Windows ML — fornece a mesma área de superfície da API com uma maior amplitude de aceleração por hardware.

Windows
Multiplataforma

pip install foundry-local-sdk-winml openai

pip install foundry-local-sdk openai

Gerar embeddings de texto

Copie e cole o seguinte código num ficheiro Python chamado app.py:

from foundry_local_sdk import Configuration, FoundryLocalManager



def main():
    # Initialize the Foundry Local SDK
    config = Configuration(app_name="foundry_local_samples")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    # Select and load an embedding model from the catalog
    model = manager.catalog.get_model("qwen3-embedding-0.6b")
    model.download(
        lambda progress: print(
            f"\rDownloading model: {progress:.2f}%",
            end="",
            flush=True,
        )
    )
    print()
    model.load()
    print("Model loaded and ready.")

    # Get an embedding client
    client = model.get_embedding_client()

    # Generate a single embedding
    print("\n--- Single Embedding ---")
    response = client.generate_embedding("The quick brown fox jumps over the lazy dog")
    embedding = response.data[0].embedding
    print(f"Dimensions: {len(embedding)}")
    print(f"First 5 values: {embedding[:5]}")

    # Generate embeddings for multiple inputs
    print("\n--- Batch Embeddings ---")
    batch_response = client.generate_embeddings(
        [
            "Machine learning is a subset of artificial intelligence",
            "The capital of France is Paris",
            "Rust is a systems programming language",
        ]
    )

    print(f"Number of embeddings: {len(batch_response.data)}")
    for i, data in enumerate(batch_response.data):
        print(f"  [{i}] Dimensions: {len(data.embedding)}")

    # Clean up
    model.unload()
    print("\nModel unloaded.")


if __name__ == "__main__":
    main()

Execute o código usando o seguinte comando:

python app.py

Resolução de problemas

ModuleNotFoundError: No module named 'foundry_local_sdk': Instale o SDK executando pip install foundry-local-sdk.
Model not found: Executa o excerto opcional de listagem de modelos para encontrar um alias disponível no teu dispositivo, depois atualiza o alias passado para get_model.
Primeira execução lenta: Os downloads de modelos podem demorar à primeira vez que executas a aplicação.

Pré-requisitos

.NET 8.0 SDK ou versão posterior instalada.

Repositório de samples

Pode encontrar o código de exemplo completo deste artigo no repositório de exemplos do Foundry no GitHub. Para clonar o repositório e navegar até à amostra, utilize:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/csharp/foundry-local/embeddings

dotnet add package Microsoft.AI.Foundry.Local.WinML
dotnet add package OpenAI

dotnet add package Microsoft.AI.Foundry.Local
dotnet add package OpenAI

Os exemplos de C# no repositório GitHub são projetos pré-configurados. Se está a construir do zero, deve ler a referência do Foundry Local SDK para mais detalhes sobre como configurar o seu projeto C# com o Foundry Local.

Gerar embeddings de texto

Copie e cole o seguinte código num ficheiro C# chamado Program.cs:

using Microsoft.AI.Foundry.Local;

var config = new Configuration
{
    AppName = "foundry_local_samples",
    LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information
};

// Initialize the singleton instance.
await FoundryLocalManager.CreateAsync(config, Utils.GetAppLogger());
var mgr = FoundryLocalManager.Instance;

// Get the model catalog
var catalog = await mgr.GetCatalogAsync();

// Get an embedding model
var model = await catalog.GetModelAsync("qwen3-embedding-0.6b") ?? throw new Exception("Embedding model not found");

// Download the model (the method skips download if already cached)
await model.DownloadAsync(progress =>
{
    Console.Write($"\rDownloading model: {progress:F2}%");
    if (progress >= 100f)
    {
        Console.WriteLine();
    }
});

// Load the model
Console.Write($"Loading model {model.Id}...");
await model.LoadAsync();
Console.WriteLine("done.");

// Get an embedding client
var embeddingClient = await model.GetEmbeddingClientAsync();

// Generate a single embedding
Console.WriteLine("\n--- Single Embedding ---");
var response = await embeddingClient.GenerateEmbeddingAsync("The quick brown fox jumps over the lazy dog");
var embedding = response.Data[0].Embedding;
Console.WriteLine($"Dimensions: {embedding.Count}");
Console.WriteLine($"First 5 values: [{string.Join(", ", embedding.Take(5).Select(v => v.ToString("F6")))}]");

// Generate embeddings for multiple inputs
Console.WriteLine("\n--- Batch Embeddings ---");
var batchResponse = await embeddingClient.GenerateEmbeddingsAsync([
    "Machine learning is a subset of artificial intelligence",
    "The capital of France is Paris",
    "Rust is a systems programming language"
]);

Console.WriteLine($"Number of embeddings: {batchResponse.Data.Count}");
for (var i = 0; i < batchResponse.Data.Count; i++)
{
    Console.WriteLine($"  [{i}] Dimensions: {batchResponse.Data[i].Embedding.Count}");
}

// Tidy up - unload the model
await model.UnloadAsync();
Console.WriteLine("\nModel unloaded.");

Execute o código usando o seguinte comando:

dotnet run

Resolução de problemas

Erros de compilação referentes a net8.0: Instala o SDK .NET 8.0 e depois reconstrói a aplicação.
Model not found: Executa o excerto opcional de listagem de modelos para encontrar um alias disponível no teu dispositivo, depois atualiza o alias passado para GetModelAsync.
Primeira execução lenta: Os downloads de modelos podem demorar à primeira vez que executas a aplicação.

Pré-requisitos

Node.js 20 ou mais recentes instalados.

Repositório de samples

O código de exemplo completo deste artigo está disponível no repositório foundry-samples do GitHub. Para clonar o repositório e navegar até ao exemplo de uso:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/javascript/foundry-local/embeddings

Pacotes de instalação

Windows
Multiplataforma

npm install foundry-local-sdk-winml openai

npm install foundry-local-sdk openai

Gerar embeddings de texto

Copie e cole o seguinte código num ficheiro JavaScript chamado app.js:

import { FoundryLocalManager } from 'foundry-local-sdk';

// Initialize the Foundry Local SDK
console.log('Initializing Foundry Local SDK...');

const manager = FoundryLocalManager.create({
    appName: 'foundry_local_samples',
    logLevel: 'info'
});
console.log('✓ SDK initialized successfully');

// Get an embedding model
const modelAlias = 'qwen3-embedding-0.6b';
const model = await manager.catalog.getModel(modelAlias);

// Download the model
console.log(`\nDownloading model ${modelAlias}...`);
await model.download((progress) => {
    process.stdout.write(`\rDownloading... ${progress.toFixed(2)}%`);
});
console.log('\n✓ Model downloaded');

// Load the model
console.log(`\nLoading model ${modelAlias}...`);
await model.load();
console.log('✓ Model loaded');

// Create embedding client
console.log('\nCreating embedding client...');
const embeddingClient = model.createEmbeddingClient();
console.log('✓ Embedding client created');

// Generate a single embedding
console.log('\n--- Single Embedding ---');
const response = await embeddingClient.generateEmbedding(
    'The quick brown fox jumps over the lazy dog'
);

const embedding = response.data[0].embedding;
console.log(`Dimensions: ${embedding.length}`);
console.log(`First 5 values: [${embedding.slice(0, 5).map(v => v.toFixed(6)).join(', ')}]`);

// Generate embeddings for multiple inputs
console.log('\n--- Batch Embeddings ---');
const batchResponse = await embeddingClient.generateEmbeddings([
    'Machine learning is a subset of artificial intelligence',
    'The capital of France is Paris',
    'Rust is a systems programming language'
]);

console.log(`Number of embeddings: ${batchResponse.data.length}`);
for (let i = 0; i < batchResponse.data.length; i++) {
    console.log(`  [${i}] Dimensions: ${batchResponse.data[i].embedding.length}`);
}

// Unload the model
console.log('\nUnloading model...');
await model.unload();
console.log('✓ Model unloaded');

Execute o código usando o seguinte comando:

node app.js

Resolução de problemas

Cannot find module 'foundry-local-sdk': Execute npm install foundry-local-sdk para instalar o SDK.
Model not found: Verifique se o alias do modelo está correto. Use manager.catalog.getModels() para listar os modelos disponíveis.
Primeira execução lenta: Os downloads de modelos podem demorar à primeira vez que executas a aplicação.

Pré-requisitos

Rust and Cargo instalado (Rust 1.70.0 ou posterior).

Repositório de samples

O código de exemplo completo deste artigo está disponível no repositório foundry-samples do GitHub. Para clonar o repositório e navegar até ao exemplo de uso:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/rust/foundry-local/embeddings

Pacotes de instalação

Windows
Multiplataforma

cargo add foundry-local-sdk --features winml
cargo add tokio --features full
cargo add tokio-stream anyhow

cargo add foundry-local-sdk
cargo add tokio --features full
cargo add tokio-stream anyhow

Gerar embeddings de texto

Substitua o conteúdo de main.rs pelo seguinte código:

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

const ALIAS: &str = "qwen3-embedding-0.6b";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Native Embeddings");
    println!("=================\n");

    // ── 1. Initialise the manager ────────────────────────────────────────
    let manager = FoundryLocalManager::create(FoundryLocalConfig::new("foundry_local_samples"))?;

    // ── 2. Pick a model and ensure it is downloaded ─────────────────────
    let model = manager.catalog().get_model(ALIAS).await?;
    println!("Model: {} (id: {})", model.alias(), model.id());

    if !model.is_cached().await? {
        println!("Downloading model...");
        model
            .download(Some(|progress: f64| {
                print!("\r  {progress:.1}%");
                std::io::Write::flush(&mut std::io::stdout()).ok();
            }))
            .await?;
        println!();
    }

    println!("Loading model...");
    model.load().await?;
    println!("✓ Model loaded\n");

    // ── 3. Create an embedding client ───────────────────────────────────
    let client = model.create_embedding_client();

    // ── 4. Single embedding ─────────────────────────────────────────────
    println!("--- Single Embedding ---");
    let response = client
        .generate_embedding("The quick brown fox jumps over the lazy dog")
        .await?;

    let embedding = &response.data[0].embedding;
    println!("Dimensions: {}", embedding.len());
    println!(
        "First 5 values: {:?}",
        &embedding[..5]
    );

    // ── 5. Batch embeddings ─────────────────────────────────────────────
    println!("\n--- Batch Embeddings ---");
    let batch_response = client
        .generate_embeddings(&[
            "Machine learning is a subset of artificial intelligence",
            "The capital of France is Paris",
            "Rust is a systems programming language",
        ])
        .await?;

    println!("Number of embeddings: {}", batch_response.data.len());
    for (i, data) in batch_response.data.iter().enumerate() {
        println!("  [{i}] Dimensions: {}", data.embedding.len());
    }

    // ── 6. Unload the model ─────────────────────────────────────────────
    println!("\nUnloading model...");
    model.unload().await?;
    println!("Done.");

    Ok(())
}

Execute o código usando o seguinte comando:

cargo run

Resolução de problemas

Erros de compilação: Certifique-se de que tem o Rust 1.70.0 ou posterior instalado. Corre rustup update para obter a versão mais recente.
Model not found: Verifique se o alias do modelo está correto. Use manager.catalog().get_models().await? para listar os modelos disponíveis.
Primeira execução lenta: Os downloads de modelos podem demorar à primeira vez que executas a aplicação.

Comentários

Esta página foi útil?

Last updated on 2026-08-18

Gerar embeddings de texto com o Foundry Local

Pré-requisitos

Repositório de samples

Pacotes de instalação

Gerar embeddings de texto

Resolução de problemas

Pré-requisitos

Repositório de samples

Pacotes de instalação

Gerar embeddings de texto

Resolução de problemas

Pré-requisitos

Repositório de samples

Pacotes de instalação

Gerar embeddings de texto

Resolução de problemas

Pré-requisitos

Repositório de samples

Pacotes de instalação

Gerar embeddings de texto

Resolução de problemas

Conteúdo relacionado

Comentários

Recursos adicionais