Generare incorporamenti di testo con Foundry Local

Foundry Local SDK fornisce un'API di incorporamento che converte il testo in vettori numerici sul dispositivo. Usare questi vettori per la ricerca di similarità, la classificazione, il clustering e la generazione aumentata da recupero (RAG).

L'SDK supporta la generazione di incorporazioni sia per input singolo sia in batch tramite un client dedicato alle incorporazioni.

Prerequisiti

Python 3.11 o versione successiva installata.

Repository di esempi

Il codice di esempio completo per questo articolo è disponibile nel repository foundry-samples GitHub. Per clonare il repository e navigare all'esempio:

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

Installare i pacchetti

Se si sviluppa o si esegue la spedizione in Windows, selezionare la scheda Windows. Il pacchetto Windows si integra con il runtime Windows ML, che fornisce la stessa area di attacco API con un'ampiezza più ampia di accelerazione hardware.

Windows
Multipiattaforma

pip install foundry-local-sdk-winml openai

pip install foundry-local-sdk openai

Generare incorporamenti di testo

Copiare e incollare il codice seguente in un file di Python denominato 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()

Eseguire il codice usando il comando seguente:

python app.py

Risoluzione dei problemi

ModuleNotFoundError: No module named 'foundry_local_sdk': installare l'SDK eseguendo pip install foundry-local-sdk.
Model not found: Esegui lo script facoltativo di elenco di modelli per trovare un alias disponibile nel tuo dispositivo, quindi aggiorna l'alias fornito a get_model.
Prima esecuzione lenta: i download dei modelli possono richiedere tempo alla prima esecuzione dell'app.

Prerequisiti

.NET 8.0 SDK o versioni successive installate.

Repository di esempi

È possibile trovare il codice di esempio completo per questo articolo nel repository degli esempi di Foundry GitHub. Per clonare il repository e passare all'esempio, usare:

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

Gli esempi C# nel repository GitHub sono progetti preconfigurati. Se stai iniziando da zero, dovresti leggere il riferimento dell'SDK locale di Foundry per maggiori dettagli su come configurare il tuo progetto C# con Foundry Local.

Generare incorporamenti di testo

Copiare e incollare il codice seguente in un file C# denominato 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.");

Eseguire il codice usando il comando seguente:

dotnet run

Risoluzione dei problemi

errori di Build che fanno riferimento a net8.0: Installare .NET 8.0 SDK e quindi ricompilare l'app.
Model not found: Esegui lo script facoltativo di elenco di modelli per trovare un alias disponibile nel tuo dispositivo, quindi aggiorna l'alias fornito a GetModelAsync.
Prima esecuzione lenta: i download dei modelli possono richiedere tempo alla prima esecuzione dell'app.

Prerequisiti

Node.js 20 o versione successiva installata.

Repository di esempi

Il codice di esempio completo per questo articolo è disponibile nel repository foundry-samples GitHub. Per clonare il repository e navigare all'esempio:

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

Installare i pacchetti

Windows
Multipiattaforma

npm install foundry-local-sdk-winml openai

npm install foundry-local-sdk openai

Generare incorporamenti di testo

Copiare e incollare il codice seguente in un file JavaScript denominato 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');

Eseguire il codice usando il comando seguente:

node app.js

Risoluzione dei problemi

Cannot find module 'foundry-local-sdk': eseguire npm install foundry-local-sdk per installare l'SDK.
Model not found: verificare che l'alias del modello sia corretto. Usare manager.catalog.getModels() per elencare i modelli disponibili.
Prima esecuzione lenta: i download dei modelli possono richiedere tempo alla prima esecuzione dell'app.

Prerequisiti

Rust e Cargo installati (Rust 1.70.0 o versione successiva).

Repository di esempi

Il codice di esempio completo per questo articolo è disponibile nel repository foundry-samples GitHub. Per clonare il repository e navigare all'esempio:

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

Installare i pacchetti

Windows
Multipiattaforma

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

Generare incorporamenti di testo

Sostituire il contenuto di main.rs con il codice seguente:

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

Eseguire il codice usando il comando seguente:

cargo run

Risoluzione dei problemi

Errori di compilazione: assicurarsi che Rust 1.70.0 o versione successiva sia installato. Eseguire rustup update per ottenere la versione più recente.
Model not found: verificare che l'alias del modello sia corretto. Usare manager.catalog().get_models().await? per elencare i modelli disponibili.
Prima esecuzione lenta: i download dei modelli possono richiedere tempo alla prima esecuzione dell'app.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-17

Generare incorporamenti di testo con Foundry Local

Prerequisiti

Repository di esempi

Installare i pacchetti

Generare incorporamenti di testo

Risoluzione dei problemi

Prerequisiti

Repository di esempi

Installare i pacchetti

Generare incorporamenti di testo

Risoluzione dei problemi

Prerequisiti

Repository di esempi

Installare i pacchetti

Generare incorporamenti di testo

Risoluzione dei problemi

Prerequisiti

Repository di esempi

Installare i pacchetti

Generare incorporamenti di testo

Risoluzione dei problemi

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive