Generieren von Texteinbettungen mit "Foundry Local"

Das Foundry Local SDK bietet eine Einbettungs-API, die Text in numerische Vektoren auf dem Gerät konvertiert. Verwenden Sie diese Vektoren für die Ähnlichkeitssuche, Klassifizierung, Clustering und Retrieval-Augmented Generation (RAG).

Das SDK unterstützt sowohl die Einbettungsgenerierung für einzelne Eingaben als auch für Batches über einen dedizierten Einbettungs-Client.

Voraussetzungen

Beispiel-Repository

Der vollständige Beispielcode für diesen Artikel ist in den Gießereibeispielen GitHub Repository verfügbar. So klonen Sie das Repository und navigieren zur Beispielverwendung:

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

Installieren von Paketen

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

pip install foundry-local-sdk-winml openai

Generieren von Texteinbettungen

Kopieren Sie den folgenden Code, und fügen Sie ihn in eine Python Datei mit dem Namen app.py ein:

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

Führen Sie den Code mithilfe des folgenden Befehls aus:

python app.py

Problembehandlung

  • ModuleNotFoundError: No module named 'foundry_local_sdk': Installieren Sie das SDK, indem Sie es ausführen pip install foundry-local-sdk.
  • Model not found: Führen Sie den optionalen Codeausschnitt für die Modellauflistung aus, um einen Alias zu finden, der auf Ihrem Gerät verfügbar ist, um dann den gefundenen Alias zu aktualisieren, der an get_model übergeben wird.
  • Langsamer erster Start: Modelldownloads können etwas dauern, wenn Sie die App zum ersten Mal starten.

Voraussetzungen

Beispiel-Repository

Den vollständigen Beispielcode für diesen Artikel finden Sie in den Foundry-Beispielen GitHub Repository. Um das Repository zu klonen und zum Beispielprojekt zu wechseln, verwenden Sie folgenden Befehl:

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

Installieren von Paketen

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

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

Die C#-Beispiele im GitHub Repository sind vorkonfigurierte Projekte. Wenn Sie von Grund auf neu erstellen, sollten Sie die Referenz zum Foundry Local SDK lesen, um weitere Details zum Einrichten Ihres C#-Projekts mit Foundry Local zu erhalten.

Generieren von Texteinbettungen

Kopieren Sie den folgenden Code, und fügen Sie ihn in eine C#-Datei mit dem Namen Program.csein:

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.");

Führen Sie den Code mithilfe des folgenden Befehls aus:

dotnet run

Problembehandlung

  • Build-Fehler, die auf net8.0 verweisen: Installieren Sie das .NET 8.0 SDK, und erstellen Sie die App neu.
  • Model not found: Führen Sie den optionalen Codeausschnitt für die Modellauflistung aus, um einen Alias zu finden, der auf Ihrem Gerät verfügbar ist, um dann den gefundenen Alias zu aktualisieren, der an GetModelAsync übergeben wird.
  • Langsamer erster Start: Modelldownloads können etwas dauern, wenn Sie die App zum ersten Mal starten.

Voraussetzungen

Beispiel-Repository

Der vollständige Beispielcode für diesen Artikel ist in den Gießereibeispielen GitHub Repository verfügbar. So klonen Sie das Repository und navigieren zur Beispielverwendung:

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

Installieren von Paketen

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

npm install foundry-local-sdk-winml openai

Generieren von Texteinbettungen

Kopieren Sie den folgenden Code, und fügen Sie ihn in eine JavaScript-Datei mit dem Namen app.jsein:

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

Führen Sie den Code mithilfe des folgenden Befehls aus:

node app.js

Problembehandlung

  • Cannot find module 'foundry-local-sdk': Führen Sie die Ausführung npm install foundry-local-sdk aus, um das SDK zu installieren.
  • Model not found: Überprüfen Sie, ob der Modellalias korrekt ist. Verwenden Sie manager.catalog.getModels(), um verfügbare Modelle aufzulisten.
  • Langsamer erster Start: Modelldownloads können etwas dauern, wenn Sie die App zum ersten Mal starten.

Voraussetzungen

Beispiel-Repository

Der vollständige Beispielcode für diesen Artikel ist in den Gießereibeispielen GitHub Repository verfügbar. So klonen Sie das Repository und navigieren zur Beispielverwendung:

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

Installieren von Paketen

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

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

Generieren von Texteinbettungen

Ersetzen Sie den Inhalt von main.rs durch den folgenden Code:

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

Führen Sie den Code mithilfe des folgenden Befehls aus:

cargo run

Problembehandlung

  • Buildfehler: Stellen Sie sicher, dass Rust 1.70.0 oder höher installiert ist. Führen Sie rustup update aus, um die neueste Version abzurufen.
  • Model not found: Überprüfen Sie, ob der Modellalias korrekt ist. Verwenden Sie manager.catalog().get_models().await?, um verfügbare Modelle aufzulisten.
  • Langsamer erster Start: Modelldownloads können etwas dauern, wenn Sie die App zum ersten Mal starten.

Verwandte Inhalte

  • Last updated on