Compiler des modèles Hugging Face et les exécuter sur Foundry Local

Foundry Local exécute des modèles ONNX sur votre appareil. Utilisez Olive pour convertir et optimiser les modèles de Hugging Face (Safetensors ou PyTorch) en ONNX afin de pouvoir les exécuter avec Foundry Local.

Important

Les paramètres d’interface cli et d’optimisation Olive changent au fil du temps, et un exemple de ligne de commande unique peut ne pas fonctionner pour chaque modèle, appareil ou fournisseur d’exécution.

Pour des exemples les plus fiables et à jour, commencez par le dépôt Olive Recipes. Il fournit un ensemble de recettes ciblées pour différents modèles, optimisés pour différents matériels avec différents paramètres d’optimisation.

Ce guide montre comment :

  • Convertissez et optimisez les modèles de Hugging Face pour qu’ils s’exécutent dans Foundry Local. Les exemples utilisent le modèle Llama-3.2-1B-Instruct, mais de nombreux modèles Hugging Face peuvent fonctionner.
  • Exécutez vos modèles optimisés avec Foundry Local.

Conditions préalables

  • Python 3.10 ou version ultérieure (obligatoire pour la compilation Olive)
  • Un compte et un jeton Hugging Face avec accès à meta-llama/Llama-3.2-1B-Instruct

Installer Olive et les dépendances

Olive optimise les modèles et les convertit au format ONNX.

pip install olive-ai
pip install transformers onnxruntime-genai

Conseil

Installez Olive dans un environnement virtuel à l’aide de venv ou conda.

Vérifiez l’installation : olive --help imprime les informations d’utilisation.

Se connecter à Hugging Face

Le Llama-3.2-1B-Instruct modèle nécessite l’authentification Hugging Face.

hf auth login

Note

Créez un jeton Hugging Face et demandez l’accès au modèle avant de continuer.

Conseil

Si hf n'est pas trouvé, installez-le en exécutant pip install -U huggingface_hub.

Compiler le modèle

Cette section décrit une compilation manuelle. La commande Olive optimize peut télécharger, convertir, quantiser et optimiser le modèle.

Note

Le script suivant est un exemple manuel qui peut nécessiter des ajustements pour différents modèles ou cibles matérielles.

  1. Exécutez la commande Olive optimize :

    olive optimize \
    --model_name_or_path meta-llama/Llama-3.2-1B-Instruct \
    --trust_remote_code \
    --output_path models/llama \
    --device cpu \
    --provider CPUExecutionProvider \
    --precision int4 \
    --log_level 1

    La commande utilise les paramètres suivants :

    Paramètre Description
    model_name_or_path Source du modèle : ID de Hugging Face, chemin local ou ID de registre de modèle AI Azure
    output_path Où enregistrer le modèle optimisé
    device Matériel cible : cpu, gpuou npu
    provider Fournisseur d’exécution (par exemple, , CPUExecutionProviderCUDAExecutionProvider)
    precision Précision du modèle : fp16, , fp32int4ouint8

    Conseil

    Si vous disposez d’une copie locale du modèle, utilisez un chemin local au lieu de l’ID Hugging Face. Par exemple, --model_name_or_path models/llama-3.2-1B-Instruct. Olive gère automatiquement la conversion, l’optimisation et la quantisation.

    Note

    Le processus de compilation prend environ 60 secondes, plus le temps de téléchargement.

  2. Exposez le modèle à Foundry Local en créant inference_model.json un fichier dans le répertoire du modèle.

    # generate_inference_model.py
import json
import os

model_path = "models/llama"

json_template = {
  "Name": "llama-3.2:1"  # set the model name as you like, the default version is 1
}

json_file = os.path.join(model_path, "inference_model.json")

with open(json_file, "w") as f:
    json.dump(json_template, f, indent=2)

    Exécutez le script :

    python generate_inference_model.py

    Vérifiez que le fichier existe : models/llama/inference_model.json.

Exécuter le modèle compilé

Utilisez le SDK C# local Foundry pour charger et exécuter votre modèle compilé avec l'API native de complétion de chat. Cette approche ne nécessite pas de serveur REST : le KIT de développement logiciel (SDK) communique directement avec le runtime.

Conditions préalables

Installer des packages

Si vous développez ou expédiez sur Windows, sélectionnez l'onglet Windows. Le package Windows s’intègre au runtime Windows ML . Il fournit la même surface d’surface d’API avec une étendue plus large d’accélération matérielle.

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

Les exemples C# dans le référentiel GitHub sont des projets préconfigurés. Si vous développez depuis le début, vous devriez lire la référence du SDK Foundry Local pour plus d'informations sur la configuration de votre projet C# avec Foundry Local.

Exécuter l’inférence sur le modèle compilé

Remplacez le contenu du Program.cs code suivant :

using Microsoft.AI.Foundry.Local;
using Betalgo.Ranul.OpenAI.ObjectModels.RequestModels;
using Microsoft.Extensions.Logging;

CancellationToken ct = CancellationToken.None;

// Point ModelCacheDir at the directory containing your compiled model
var config = new Configuration
{
    AppName = "run-compiled-model",
    LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
    ModelCacheDir = "../models"
};

using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();

await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;

var catalog = await mgr.GetCatalogAsync();

// List cached models to find your compiled model
var cachedModels = await catalog.GetCachedModelsAsync();
Console.WriteLine("Cached models:");
foreach (var m in cachedModels)
{
    Console.WriteLine($"  {m.Id}");
}

// Select your compiled model from the cached list
var model = cachedModels.FirstOrDefault(m => m.Id.Contains("llama-3.2:1"))
    ?? throw new Exception("Compiled model not found. Verify the ModelCacheDir path.");

await model.LoadAsync();

// Use native chat completions
var chatClient = await model.GetChatClientAsync();

List<ChatMessage> messages = new()
{
    new ChatMessage { Role = "user", Content = "What is the golden ratio?" }
};

var streamingResponse = chatClient.CompleteChatStreamingAsync(messages, ct);
await foreach (var chunk in streamingResponse)
{
    Console.Write(chunk.Choices[0].Delta.Content);
    Console.Out.Flush();
}
Console.WriteLine();

await model.UnloadAsync();

Exécutez l’application :

dotnet run

Utilisez le SDK JavaScript local Foundry pour charger et exécuter votre modèle compilé avec l'API de complétion de chat native.

Conditions préalables

Installer des packages

Si vous développez ou expédiez sur Windows, sélectionnez l'onglet Windows. Le package Windows s’intègre au runtime Windows ML . Il fournit la même surface d’surface d’API avec une étendue plus large d’accélération matérielle.

npm install foundry-local-sdk-winml openai

Exécuter l’inférence sur le modèle compilé

Copiez et collez le code suivant dans un fichier JavaScript nommé app.js:

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

// Initialize the Foundry Local SDK with custom model cache directory
const manager = FoundryLocalManager.create({
    appName: 'run-compiled-model',
    logLevel: 'info',
    modelCacheDir: '../models'
});

// List cached models to find your compiled model
const cachedModels = await manager.catalog.getCachedModels();
console.log('Cached models:');
for (const m of cachedModels) {
    console.log(`  ${m.id}`);
}

// Select your compiled model from the cached list
const model = cachedModels.find(m => m.id.includes('llama-3.2:1'));
if (!model) {
    throw new Error('Compiled model not found. Verify the modelCacheDir path.');
}

// Load the model
await model.load();

// Create a chat client
const chatClient = model.createChatClient();

// Generate a response
const completion = await chatClient.completeChat([
    { role: 'user', content: 'What is the golden ratio?' }
]);

console.log(completion.choices[0]?.message?.content);

// Unload the model
await model.unload();

Exécutez l’application :

node app.js

Utilisez le SDK Python local de Foundry pour charger et exécuter votre modèle compilé à l’aide de l’API native de saisie semi-automatique dans le chat.

Conditions préalables

Installer des packages

Si vous développez ou expédiez sur Windows, sélectionnez l'onglet Windows. Le package Windows s’intègre au runtime Windows ML . Il fournit la même surface d’surface d’API avec une étendue plus large d’accélération matérielle.

pip install foundry-local-sdk-winml openai

Exécuter l’inférence sur le modèle compilé

Copiez et collez le code suivant dans un fichier Python nommé app.py :

import asyncio
from foundry_local_sdk import Configuration, FoundryLocalManager


async def main():
    # Point model_cache_dir at the directory containing your compiled model
    config = Configuration(
        app_name="run-compiled-model",
        model_cache_dir="../models",
    )
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    # List cached models to find your compiled model
    cached_models = manager.catalog.get_cached_models()
    print("Cached models:")
    for m in cached_models:
        print(f"  {m.id}")

    # Select your compiled model from the cached list
    model = next((m for m in cached_models if "llama-3.2:1" in m.id), None)
    if model is None:
        raise Exception("Compiled model not found. Verify the model_cache_dir path.")

    # Load the model
    model.load()

    # Get a chat client
    client = model.get_chat_client()

    # Stream the response
    messages = [{"role": "user", "content": "What is the golden ratio?"}]
    for chunk in client.complete_streaming_chat(messages):
        content = chunk.choices[0].delta.content
        if content:
            print(content, end="", flush=True)
    print()

    # Tidy up - unload the model
    model.unload()


if __name__ == "__main__":
    asyncio.run(main())

Exécutez l’application :

python app.py

Utilisez le SDK Rust Local Foundry afin de charger et d'exécuter votre modèle compilé avec l'API de complétion de chat native.

Conditions préalables

Installer des packages

Si vous développez ou expédiez sur Windows, sélectionnez l'onglet Windows. Le package Windows s’intègre au runtime Windows ML . Il fournit la même surface d’surface d’API avec une étendue plus large d’accélération matérielle.

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

Exécuter l’inférence sur le modèle compilé

Remplacez le contenu du src/main.rs code suivant :

use foundry_local_sdk::{
    ChatCompletionRequestMessage, ChatCompletionRequestUserMessage,
    FoundryLocalConfig, FoundryLocalManager,
};
use std::io::Write;
use tokio_stream::StreamExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Point model_cache_dir at the directory containing your compiled model
    let config = FoundryLocalConfig::new("run-compiled-model")
        .with_model_cache_dir("../models");
    let manager = FoundryLocalManager::create(config)?;

    // List cached models to find your compiled model
    let cached_models = manager.catalog().get_cached_models().await?;
    println!("Cached models:");
    for m in &cached_models {
        println!("  {}", m.id());
    }

    // Select your compiled model from the cached list
    let model = cached_models
        .iter()
        .find(|m| m.id().contains("llama-3.2:1"))
        .ok_or_else(|| anyhow::anyhow!("Compiled model not found. Verify the model_cache_dir path."))?;

    // Load the model
    model.load().await?;

    // Create a chat client
    let client = model.create_chat_client().temperature(0.7).max_tokens(256);

    // Stream the response
    let messages: Vec<ChatCompletionRequestMessage> = vec![
        ChatCompletionRequestUserMessage::new("What is the golden ratio?").into(),
    ];

    let mut stream = client.complete_streaming_chat(&messages, None).await?;
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = &chunk.choices[0].delta.content {
            print!("{}", content);
            std::io::stdout().flush()?;
        }
    }
    println!();

    // Tidy up - unload the model
    model.unload().await?;

    Ok(())
}

Exécutez l’application :

cargo run

Dépannage

  • En olive optimize cas d’échec avec une erreur d’authentification ou d’accès, confirmez que votre jeton Hugging Face est correct et que la demande d’accès au modèle est approuvée.
  • Si la commande hf n'est pas trouvée, installez-la en exécutant pip install -U huggingface_hub.
  • Si le modèle compilé n’est pas trouvé dans la liste des modèles mis en cache, vérifiez que le chemin spécifié dans vos ModelCacheDir pointe vers le répertoire parent contenant le dossier du modèle.
  • Si vous rencontrez des erreurs de génération .NET référençant net8.0, installez le SDK .NET 8.0.

Contenu connexe

  • Last updated on