Compilar modelos do Hugging Face para execução no Foundry Local

O Foundry Local executa modelos ONNX em seu dispositivo. Use o Olive converter e otimizar modelos do Hugging Face (Safetensors ou PyTorch) para ONNX, para que você possa executá-los com o Foundry Local.

Importante

A CLI de Olive e as configurações de otimização mudam ao longo do tempo e um único exemplo de linha de comando pode não funcionar para cada modelo, dispositivo ou provedor de execução.

Para obter os exemplos mais confiáveis e atualizados, comece com o repositório Receitas de Oliva. Ele fornece um conjunto de receitas direcionadas para vários modelos, otimizadas para hardwares diferentes com configurações de otimização diferentes.

Este guia mostra como:

  • Converta e otimize modelos do Hugging Face para serem executados no Foundry Local. Os exemplos usam o modelo Llama-3.2-1B-Instruct, mas muitos modelos da Hugging Face podem funcionar.
  • Execute seus modelos otimizados com o Foundry Local.

Pré-requisitos

  • Python 3.10 ou posterior (necessário para compilação de Olive)
  • Uma conta da Hugging Face e um token com acesso a meta-llama/Llama-3.2-1B-Instruct

Instale o Olive e suas dependências

Olive otimiza modelos e os converte no formato ONNX.

pip install olive-ai
pip install transformers onnxruntime-genai

Dica

Instale o Olive em um ambiente virtual usando venv ou conda.

Verifique a instalação: olive --help imprime as informações de uso.

Faça login no Hugging Face

O modelo Llama-3.2-1B-Instruct exige autenticação com Hugging Face.

hf auth login

Nota

Crie um token do Hugging Face e solicite acesso ao modelo antes de continuar.

Dica

Se hf não for encontrado, instale-o executando pip install -U huggingface_hub.

Compilar o modelo

Esta seção percorre uma compilação manual. O comando Olive optimize baixa, converte, quantiza e otimiza o modelo.

Nota

Este é um exemplo manual que pode exigir ajustes para diferentes modelos ou destinos de hardware.

  1. Execute o comando 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

    O comando usa os seguintes parâmetros:

    Parâmetro Descrição
    model_name_or_path Origem do modelo: Hugging Face ID, caminho local ou ID do registro de modelo do IA do Azure
    output_path Onde salvar o modelo otimizado
    device Hardware de destino: cpu, gpuou npu
    provider Provedor de execução (por exemplo, CPUExecutionProvider, CUDAExecutionProvider)
    precision Precisão do modelo: fp16, , fp32int4ouint8

    Dica

    Se você tiver uma cópia local do modelo, use um caminho local em vez do ID da Hugging Face. Por exemplo, --model_name_or_path models/llama-3.2-1B-Instruct. Olive manipula automaticamente a conversão, a otimização e a quantização.

    Nota

    O processo de compilação leva cerca de 60 segundos, além do tempo de download.

  2. Exponha o modelo ao Foundry Local criando inference_model.json um arquivo no diretório do modelo.

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

    Execute o script:

    python generate_inference_model.py

    Verifique se o arquivo existe: models/llama/inference_model.json.

Executar o modelo compilado

Use o SDK do Foundry Local C# para carregar e executar seu modelo compilado com a API de conclusões de chat nativa. Essa abordagem não requer um servidor REST – o SDK se comunica diretamente com o runtime.

Pré-requisitos

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

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

Os exemplos de C# no repositório GitHub são projetos pré-configurados. Se você estiver criando do zero, leia a referência do SDK Local do Foundry para obter mais detalhes sobre como configurar seu projeto em C# com o Foundry Local.

Executar inferência no modelo compilado

Substitua o conteúdo de Program.cs com o seguinte código:

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

Execute o aplicativo:

dotnet run

Use o SDK local do JavaScript da Foundry para carregar e executar seu modelo compilado com a API nativa de autocompletar do chat.

Pré-requisitos

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

npm install foundry-local-sdk-winml openai

Executar inferência no modelo compilado

Copie e cole o seguinte código em um arquivo JavaScript chamado 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();

Execute o aplicativo:

node app.js

Use o SDK do Python Local do Foundry para carregar e executar seu modelo compilado com a API de conclusões de chat nativa.

Pré-requisitos

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

pip install foundry-local-sdk-winml openai

Executar inferência no modelo compilado

Copie e cole o seguinte código em um arquivo de Python chamado 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())

Execute o aplicativo:

python app.py

Use o SDK do Foundry Local Rust para carregar e executar seu modelo compilado com a API nativa de autocompletar do chat.

Pré-requisitos

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

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

Executar inferência no modelo compilado

Substitua o conteúdo de src/main.rs com o seguinte código:

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

Execute o aplicativo:

cargo run

Solucionando problemas

  • Se olive optimize apresentar um erro de autenticação ou acesso, verifique se o seu token do Hugging Face está válido e se a solicitação de acesso ao modelo foi aprovada.
  • Se o comando hf não for encontrado, instale-o executando pip install -U huggingface_hub.
  • Se o modelo compilado não for encontrado na lista de modelos armazenados em cache, verifique se o caminho ModelCacheDir em Configuration aponta para o diretório pai que contém a pasta do modelo.
  • Caso você encontre erros de build do .NET referenciando a net8.0, instale o SDK do .NET 8.0.

Conteúdo relacionado

  • Last updated on