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. O SDK nativo corre no processo da tua aplicação e não requer a CLI Local do Foundry nem um servidor local REST separado. 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 11, versão 24H2 (build 26100) ou posterior
• .NET 9.0 SDK ou posterior
• Um dispositivo x64 ou Arm64 com memória e espaço em disco suficientes para o modelo que selecionares
• Acesso à Internet para downloads iniciais do pacote inicial, modelo e componentes em tempo de execução

O SDK do Windows pode usar variantes compatíveis de CPU, GPU e modelo de NPU. Uma GPU, NPU ou Copilot+ PC dedicada não é necessária quando o modelo selecionado tem uma variante de CPU compatível. A aceleração e o desempenho disponíveis dependem do seu dispositivo, modelo e fornecedor de execução.

Opcional: Instalar a CLI local da Foundry

O fluxo de trabalho do SDK neste quickstart não requer a linha de comando. Instale-o apenas se também quiser inspecionar e gerir modelos a partir de um terminal:

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 Windows estável atual:

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

O pacote inclui o ChatMessage e os tipos relacionados utilizados pela API de chat nativa do Foundry Local. Seleciona uma variante de modelo compatível para o dispositivo atual e pode usar fornecedores de execução de ML Windows para aceleração de hardware.

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 the native in-process Foundry Local SDK.
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-4-mini")
        ?? throw new Exception(
            "Model 'phi-4-mini' not found in catalog. " +
            "Check your internet connection and available model aliases.");

    // 3. Download the model if it is not already cached.
    if (!await model.IsCachedAsync())
    {
        Console.Write("Downloading phi-4-mini...");
        await model.DownloadAsync(progress =>
        {
            Console.Write($"\rDownloading phi-4-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. " +
            "Try the request again or select another compatible model variant.");

    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 de modelo completo) para GetModelAsync que o Foundry Local possa selecionar uma variante de hardware compatível. Dependendo do modelo e dispositivo, pode ser uma variante QNN NPU no Snapdragon, uma variante CUDA na NVIDIA, ou uma variante com CPU.

Se instalaste a CLI opcional, executa-a para veres os alias disponíveis:

foundry model list

Por exemplo, use phi-4-mini para o modelo Microsoft Phi-4 Mini. O catálogo muda ao longo do tempo, por isso consulte o catálogo de modelos Foundry Local para os nomes atuais e variantes disponíveis.

Início rápido em Python

O Foundry Local também suporta Python, JavaScript (Node.js) e Rust. Aqui está o exemplo mínimo em Python para confirmar que o padrão funciona — o guia completo para as quatro linguagens está na documentação do Microsoft 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("phi-4-mini")
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 quick-start completo em Python — incluindo configuração do fornecedor de execução, tratamento de erros e listagem de modelos — veja Começar com o Foundry Local na documentação do Microsoft 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.

Para um guia completo da aplicação, continue para o tutorial do WinUI. Abrange consentimento explícito para download do modelo, progresso, cancelamento, acessibilidade e revisão de resultados.

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
Tente novamente o pedido e confirme se o modelo selecionado tem uma variante compatível para o seu dispositivo. Se o problema continuar, selecione um modelo mais pequeno ou uma variante de CPU e verifique se o dispositivo tem memória suficiente.

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
• Referência do SDK Foundry Local — Configuração do SDK e orientações sobre a 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