Introdução ao Foundry Local

O Foundry Local permite a execução local de grandes modelos de linguagem (LLMs) diretamente no seu dispositivo Windows, como parte do Microsoft Foundry em Windows. É uma boa alternativa quando precisas de ir mais fundo do que as APIs de IA do Windows, ou quando precisas de suportar hardware que não seja um Copilot+ PC. Não são necessárias permissões especiais nem tokens de desbloqueio — corre inteiramente no seu próprio hardware. O mesmo padrão funciona numa aplicação de consola, numa aplicação WinUI 3, numa aplicação WPF ou em qualquer outro host .NET.

Prerequisites

• Windows 10 build 26100 ou posterior (recomendado Windows 11 24H2 ou posterior)
• .NET 9.0 SDK ou posterior
• Uma GPU compatível com DirectX 12 (integrada ou discreta). O WinML pacote utiliza aceleração por hardware e requer hardware real de GPU — máquinas virtuais sem passthrough de GPU não são suportadas.

Instalar o CLI local da Foundry

Instale a CLI usando o winget:

winget install Microsoft.FoundryLocal

Depois fecha e reabre o terminal para que o foundry comando fique no teu PATH. Verificar:

foundry --version

Criar um projeto

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

O pacote NuGet inclui binários nativos do Windows, pelo que o projeto precisa de um framework de destino Windows e identificadores de tempo de execução. Abra FoundryLocalDemo.csproj e substitua o <PropertyGroup> bloco por:

<PropertyGroup>
  <OutputType>Exe</OutputType>
  <TargetFramework>net9.0-windows10.0.26100.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <RuntimeIdentifiers>win-x64;win-arm64</RuntimeIdentifiers>
</PropertyGroup>

Depois restaura para gerar o ficheiro de assets para o novo alvo:

dotnet restore

Instalar o pacote NuGet

Instale o pacote WinML, que utiliza automaticamente o melhor hardware disponível (Qualcomm NPU, NVIDIA GPU ou CPU) através do ONNX Runtime:

dotnet add package Microsoft.AI.Foundry.Local.WinML --version 1.0.0
dotnet add package Betalgo.Ranul.OpenAI --version 9.1.0

O pacote Betalgo.Ranul.OpenAI fornece o tipo ChatMessage e tipos relacionados utilizados pela API de chat local da Foundry.

Início rápido: executar um modelo

Substitua o conteúdo de Program.cs pelo seguinte, depois execute dotnet run. O programa inicializa o Foundry Local, descarrega o modelo se necessário, executa um chat e limpa tudo.

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

// 1. Initialize Foundry Local. The SDK starts the service automatically if needed.
await FoundryLocalManager.CreateAsync(
    new Configuration { AppName = "my-app" },
    NullLogger.Instance);

var manager = FoundryLocalManager.Instance;
try
{
    // 2. Look up the model in the catalog by alias.
    var catalog = await manager.GetCatalogAsync();
    var model = await catalog.GetModelAsync("phi-3.5-mini")
        ?? throw new Exception(
            "Model 'phi-3.5-mini' not found in catalog. " +
            "Ensure Foundry Local is installed and has internet access.");

    // 3. Download the model if it is not already cached (2.53 GB).
    if (!await model.IsCachedAsync())
    {
        Console.Write("Downloading phi-3.5-mini...");
        await model.DownloadAsync(progress =>
        {
            Console.Write($"\rDownloading phi-3.5-mini  {progress,5:F1}%");
        });
        Console.WriteLine();
    }

    // 4. Load the model into memory.
    await model.LoadAsync();

    // 5. Run a chat completion.
    var chatClient = await model.GetChatClientAsync();
    var response = await chatClient.CompleteChatAsync(new[]
    {
        new ChatMessage { Role = "system", Content = "You are a helpful assistant." },
        new ChatMessage { Role = "user", Content = "Explain async/await in C# in two sentences." }
    });

    if (!response.Successful)
        throw new Exception(
            $"Chat completion failed: {response.Error?.Message ?? "unknown error"} " +
            $"(code: {response.Error?.Code})");

    var content = response.Choices![0].Message.Content;
    if (string.IsNullOrEmpty(content))
        throw new Exception(
            "Model returned empty content. " +
            "Verify that your device has a DirectX 12-capable GPU. " +
            "Virtual machines without GPU passthrough are not supported.");

    Console.WriteLine(content);
}
finally
{
    // 6. Clean up — always runs even if an earlier step throws.
    manager.Dispose();
}

Respostas de streaming

Para uma melhor experiência de utilizador nas aplicações de interface, transmita a resposta token a token. Este excerto continua do início rápido acima — chatClient vem do passo 5:

using var cts = new CancellationTokenSource();

await foreach (var chunk in chatClient.CompleteChatStreamingAsync(
    new[] { new ChatMessage { Role = "user", Content = "Write a haiku about Windows." } },
    cts.Token))
{
    Console.Write(chunk.Choices?[0]?.Message?.Content);
}
Console.WriteLine();

Parâmetros de geração de sintonia

chatClient.Settings.Temperature = 0.7f;
chatClient.Settings.MaxTokens = 512;
chatClient.Settings.TopP = 0.9f;

Apelidos de modelos

Passe um alias de modelo (não um ID completo do modelo) para que o GetModelAsync Foundry Local selecione automaticamente a melhor variante de hardware — por exemplo, uma variante QNN NPU no Snapdragon, uma variante CUDA na NVIDIA, ou uma opção alternativa de CPU em todos os outros casos.

Execute o CLI para ver os alias disponíveis:

foundry model list

Alias comuns: phi-3.5-mini, phi-4, qwen2.5-0.5b (menor — bom para testes rápidos), qwen2.5-7b, deepseek-r1-7b. O catálogo completo encontra-se em foundrylocal.ai/models.

Início rápido em Python

O Foundry Local também suporta Python, JavaScript (Node.js) e Rust. Aqui está o exemplo mínimo de Python para confirmar que o padrão funciona — o guia completo para as quatro línguas está na documentação Azure AI Foundry.

Instale um dos seguintes — não instale ambos, pois têm dependências conflitantesonnxruntime-core:

pip install foundry-local-sdk-winml   # Windows — includes hardware acceleration (recommended on Windows)
pip install foundry-local-sdk         # macOS/Linux, or Windows without hardware acceleration

Criar app.py:

from foundry_local_sdk import Configuration, FoundryLocalManager

FoundryLocalManager.initialize(Configuration(app_name="my-app"))
manager = FoundryLocalManager.instance

model = manager.catalog.get_model("qwen2.5-0.5b")
model.download(lambda p: print(f"\rDownloading {p:.0f}%", end="", flush=True))
model.load()

client = model.get_chat_client()
for chunk in client.complete_streaming_chat([{"role": "user", "content": "Why is the sky blue?"}]):
    print(chunk.choices[0].delta.content or "", end="", flush=True)
print()

model.unload()

Executa:

python app.py

Para o início rápido completo do Python — incluindo configuração do fornecedor de execução, tratamento de erros e listagem de modelos — veja Comece com o Foundry Local na documentação Azure AI Foundry.

Utilização a partir de uma aplicação WinUI 3 ou WPF

Inicializar uma vez em App.xaml.cs ou App.cs:

protected override async void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    await FoundryLocalManager.CreateAsync(
        new Configuration { AppName = "MyWinUIApp" },
        NullLogger.Instance);
    // ...
}

Depois resolve FoundryLocalManager.Instance em qualquer parte da aplicação. Chame Dispose() no manipulador de saída da aplicação.

Recurso alternativo para a nuvem

Combine o Foundry Local com APIs de IA Windows e Azure OpenAI para um padrão resiliente multi-nível. Veja Escolha a sua solução de IA Windows para um exemplo compilado completo.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Estes avisos aparecem após o programa sair e são benignos. Eles provêm do rastreamento nativo de recursos da biblioteca ONNX Runtime GenAI (OGA) subjacente. O teu resultado está correto; Os avisos não indicam um problema com o seu código.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Este aviso do ONNX Runtime significa que a biblioteca não reconhece o seu SoC ARM para deteção de funcionalidades da CPU. Volta a valores padrão de segurança e a inferência corre normalmente. Não é preciso fazer nada.

Model '...' not found in catalog
O SDK recolhe o catálogo de modelos da internet. Verifique a sua ligação à rede. Se não for encontrado um alias específico do modelo, execute foundry model list para ver alias disponíveis ou consulte o catálogo completo em foundrylocal.ai/models.

O modelo devolve conteúdo vazio
O backend WinML requer uma GPU compatível com DirectX 12. Máquinas virtuais sem a funcionalidade de passthrough de GPU retornam uma resposta bem-sucedida com conteúdo vazio. Funciona em hardware físico com uma GPU discreta ou integrada.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Este conflito de dependência do pip significa que tanto foundry-local-sdk-winml como foundry-local-sdk estão instalados — eles fixam versões diferentes de onnxruntime-core, que não podem coexistir. Desinstalar um:

pip uninstall foundry-local-sdk        # if you want the winml (Windows) package
pip uninstall foundry-local-sdk-winml  # if you want the cross-platform package

Depois reinstala o que queres. Utilizar um ambiente virtual evita este problema por completo.

• Full Foundry Local documentation — CLI, REST API, Python SDK, gestão de modelos
• Foundry Local C# SDK referência — referência completa da API
• Windows ML — traga o seu próprio modelo ONNX com controlo total de EP
• Escolha a sua Windows solução de IA — compare todas as opções Windows IA