Introdução ao Foundry Local

O Foundry Local permite a execução local de LLMs (modelos de linguagem grande) diretamente em seu dispositivo Windows, como parte do Microsoft Foundry no Windows. É uma boa alternativa quando você precisa ir mais fundo do que as APIs de IA Windows ou precisa dar suporte a hardware que não é um Copilot+ PC. Não são necessárias permissões especiais ou tokens de desbloqueio — ele é executado inteiramente em seu próprio hardware. O mesmo padrão funciona em um aplicativo de console, um aplicativo WinUI 3, um aplicativo WPF ou qualquer outro host .NET.

Prerequisites

• Windows 10 build 26100 ou posterior (Windows 11 24H2 ou posterior recomendado)
• .NET SDK 9.0 ou posterior
• Uma GPU compatível com DirectX 12 (integrada ou discreta). O WinML pacote usa aceleração de hardware e requer hardware de GPU real – máquinas virtuais sem passagem de GPU não têm suporte.

Instalar a CLI Local do Foundry

Instale a CLI usando winget:

winget install Microsoft.FoundryLocal

Em seguida, feche e reabra o terminal para que o foundry comando esteja em seu PATH. Verificar:

foundry --version

Criar um projeto

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

O pacote NuGet inclui binários de Windows nativos, portanto, o projeto precisa de uma estrutura de destino Windows e identificadores de runtime. 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>

Em seguida, restaure para gerar o arquivo de ativos para o novo destino:

dotnet restore

Instalar o pacote NuGet

Instale o pacote WinML, que usa automaticamente o melhor hardware disponível (Qualcomm NPU, NVIDIA GPU ou CPU) por meio 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 os tipos ChatMessage e relacionados usados pela API de chat local do Foundry.

Início rápido: executar um modelo

Substitua o conteúdo do Program.cs com o seguinte e execute dotnet run. O programa inicializa o Foundry Local, baixa o modelo, se necessário, executa uma tarefa de conclusão de chat e realiza a limpeza.

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 em streaming

Para oferecer uma melhor experiência do usuário em aplicativos de IU, transmita a resposta token por token. Este trecho continua da introdução rápida acima — chatClient vem da etapa 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();

Ajustar parâmetros de geração

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

Apelidos de modelo

Passe um alias de modelo (não uma ID completa do modelo) para GetModelAsync para que o Foundry Local selecione automaticamente a melhor variante de hardware — por exemplo, uma variante de NPU QNN no Snapdragon, uma variante CUDA na NVIDIA ou um fallback de CPU nos demais casos.

Execute a CLI para ver os aliases disponíveis:

foundry model list

Aliases comuns: phi-3.5-mini, , phi-4qwen2.5-0.5b(menor – bom para teste rápido), qwen2.5-7b, deepseek-r1-7b. O catálogo completo está em foundrylocal.ai/models.

Início Rápido do Python

O Foundry Local também dá suporte a Python, JavaScript (Node.js) e Rust. Aqui está o exemplo mínimo de Python para confirmar se o padrão funciona: o passo a passo completo para todos os quatro idiomas está nos documentos Fábrica de IA do Azure.

Instale um dos seguintes – não instale ambos, pois eles têm dependências conflitantes onnxruntime-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()

Execute-o:

python app.py

Para obter o início rápido do Python completo, incluindo a configuração do provedor de execução, o tratamento de erros e a listagem de modelos, consulte Comece com o Foundry Local na documentação do Fábrica de IA do Azure.

Usar de um aplicativo WinUI 3 ou WPF

Inicie uma vez dentro de 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);
    // ...
}

Em seguida, resolva FoundryLocalManager.Instance em qualquer lugar do aplicativo. Utilize Dispose() no controlador de saída do aplicativo.

Fallback para a nuvem

Combine o Foundry Local com APIs de IA Windows e Azure OpenAI para um padrão de várias camadas resiliente. Consulte Choose sua solução de IA Windows para obter um exemplo completo compilável.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Esses avisos aparecem após a saída do programa e são benignos. Eles vêm do monitoramento de recursos nativos da biblioteca ONNX Runtime GenAI (OGA) subjacente. Sua saída está correta; os avisos não indicam um problema com seu código.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Esse aviso do ONNX Runtime significa que a biblioteca não reconhece o ARM SoC para detecção de recursos de CPU. Ele volta para padrões seguros e a inferência é executada normalmente. Nenhuma ação é necessária.

Model '...' not found in catalog
O SDK busca o catálogo de modelos da Internet. Verifique sua conexão de rede. Se um alias de modelo específico não for encontrado, execute foundry model list para ver os aliases disponíveis ou navegue pelo catálogo completo em foundrylocal.ai/models.

O modelo retorna conteúdo vazio
O back-end do WinML requer uma GPU compatível com DirectX 12. Máquinas virtuais sem passagem de GPU retornam uma resposta bem-sucedida com conteúdo vazio. Execute 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
Esse conflito de dependência pip significa que tanto foundry-local-sdk-winml quanto foundry-local-sdk estão instalados, já que eles fixam diferentes versões de onnxruntime-core e não podem coexistir. Desinstalar um aplicativo:

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

Em seguida, reinstale o que você deseja. O uso de um ambiente virtual evita totalmente esse problema.

• documentação Full Foundry Local — CLI, API REST, SDK Python, gerenciamento de modelos
• Referência do SDK do C# local do Foundry — referência de API completa
• Windows ML — traga seu próprio modelo ONNX com controle EP completo
• Conseque sua solução de IA Windows — compare todas as opções de IA Windows