Generación de incrustaciones de texto con Foundry Local

El SDK local de Foundry proporciona una API de inserción que convierte texto en vectores numéricos en el dispositivo. Use estos vectores para la búsqueda, clasificación, agrupación en clústeres y generación aumentada de recuperación (RAG).

El SDK admite tanto la generación de incrustaciones de entrada individual como la por lotes a través de un cliente de incrustación dedicado.

Requisitos previos

Repositorio de ejemplos

El código de ejemplo completo de este artículo está disponible en el repositorio foundry-samples GitHub. Cómo clonar el repositorio y acceder al directorio de ejemplo:

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

Instalación de paquetes

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el runtime Windows ML, proporcionando la misma superficie de API con una mayor amplitud de aceleración de hardware.

pip install foundry-local-sdk-winml openai

Generación de incrustaciones de texto

Copie y pegue el código siguiente en un archivo de Python denominado 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()

Ejecute el código mediante el comando siguiente:

python app.py

Solución de problemas

  • ModuleNotFoundError: No module named 'foundry_local_sdk': instale el SDK ejecutando pip install foundry-local-sdk.
  • Model not found: ejecute el fragmento de código de lista de modelos opcional para buscar un alias disponible en el dispositivo y, a continuación, actualice el alias pasado a get_model.
  • Primera ejecución lenta: las descargas de modelos pueden tardar la primera vez que ejecute la aplicación.

Requisitos previos

Repositorio de ejemplos

Puede encontrar el código de ejemplo completo de este artículo en el repositorio de ejemplos de Foundry GitHub. Para clonar el repositorio e ir al ejemplo, utilice:

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

Instalación de paquetes

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el runtime Windows ML, proporcionando la misma superficie de API con una mayor amplitud de aceleración de hardware.

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

Los ejemplos de C# del repositorio de GitHub son proyectos preconfigurados. Si va a compilar desde cero, debe leer la referencia del SDK local de Foundry para obtener más detalles sobre cómo configurar el proyecto de C# con Foundry Local.

Generación de incrustaciones de texto

Copie y pegue el código siguiente en un archivo de C# denominado 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.");

Ejecute el código mediante el comando siguiente:

dotnet run

Solución de problemas

  • Errores de compilación que hacen referencia a net8.0: instale el SDK de .NET 8.0 y recompile la aplicación.
  • Model not found: ejecute el fragmento de código de lista de modelos opcional para buscar un alias disponible en el dispositivo y, a continuación, actualice el alias pasado a GetModelAsync.
  • Primera ejecución lenta: las descargas de modelos pueden tardar la primera vez que ejecute la aplicación.

Requisitos previos

Repositorio de ejemplos

El código de ejemplo completo de este artículo está disponible en el repositorio foundry-samples GitHub. Cómo clonar el repositorio y acceder al directorio de ejemplo:

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

Instalación de paquetes

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el runtime Windows ML, proporcionando la misma superficie de API con una mayor amplitud de aceleración de hardware.

npm install foundry-local-sdk-winml openai

Generación de incrustaciones de texto

Copie y pegue el código siguiente en un archivo javaScript denominado 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');

Ejecute el código mediante el comando siguiente:

node app.js

Solución de problemas

  • Cannot find module 'foundry-local-sdk': ejecute npm install foundry-local-sdk para instalar el SDK.
  • Model not found: compruebe que el alias del modelo es correcto. Use manager.catalog.getModels() para enumerar los modelos disponibles.
  • Primera ejecución lenta: las descargas de modelos pueden tardar la primera vez que ejecute la aplicación.

Requisitos previos

Repositorio de ejemplos

El código de ejemplo completo de este artículo está disponible en el repositorio foundry-samples GitHub. Cómo clonar el repositorio y acceder al directorio de ejemplo:

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

Instalación de paquetes

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el runtime Windows ML, proporcionando la misma superficie de API con una mayor amplitud de aceleración de hardware.

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

Generación de incrustaciones de texto

Reemplace el contenido de main.rs por el código siguiente:

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

Ejecute el código mediante el comando siguiente:

cargo run

Solución de problemas

  • Errores de compilación: asegúrese de que tiene rust 1.70.0 o posterior instalado. Ejecute rustup update para obtener la versión más reciente.
  • Model not found: compruebe que el alias del modelo es correcto. Use manager.catalog().get_models().await? para enumerar los modelos disponibles.
  • Primera ejecución lenta: las descargas de modelos pueden tardar la primera vez que ejecute la aplicación.

Contenido relacionado

  • Last updated on