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. O SDK nativo é executado em seu processo de aplicativo e não requer a CLI Local do Foundry ou um servidor REST local separado. O mesmo padrão funciona em um aplicativo de console, um aplicativo WinUI 3, um aplicativo WPF ou qualquer outro host .NET.

Logotipos de tecnologias associadas ao Foundry Local

Note

A documentação completa do Foundry Local , incluindo a CLI, o gerenciamento de modelos, o servidor REST opcional, Python SDK e muito mais, é mantida na documentação do Microsoft Foundry. Os links nesta página o levam para lá quando necessário. Você pode usar o botão Voltar do navegador ou o caminho de navegação para retornar aos documentos de IA do Windows a qualquer momento.

Se você não tiver certeza se o Foundry Local é a opção certa para o seu cenário, consulte Escolha sua solução de IA do Windows antes de continuar.

Prerequisites

  • Windows 11, versão 24H2 (build 26100) ou posterior
  • .NET SDK 9.0 ou posterior
  • Um dispositivo x64 ou Arm64 com memória e espaço em disco suficientes para o modelo selecionado
  • Acesso à Internet para downloads iniciais de pacote, modelo e componente de runtime

O SDK do Windows pode usar variantes de modelo de CPU, GPU e NPU compatíveis. Uma GPU dedicada, NPU ou Copilot+ PC 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 provedor de execução.

Note

Este guia de início rápido usa o Phi-4 Mini, atualmente o modelo Phi mais recente da Microsoft disponível por meio do alias Foundry Local phi-4-mini. Os aliases do catálogo local do Foundry e os modelos recomendados podem ser alterados conforme o catálogo evolui.

O Phi-4 Mini é separado do Phi Silica, o modelo de API de IA Windows que é fornecido com Windows. O Phi Silica continua sendo um recurso de acesso limitado e requer um token de desbloqueio. Está previsto que seja substituído pelo Aion Instruct, que não exigirá um token do recurso Limited Access Feature. Consulte Introdução ao Phi Silica para obter detalhes de acesso e a linha do tempo de transição.

Opcional: instalar a CLI local do Foundry

O fluxo de trabalho do SDK neste início rápido não requer a CLI. Instale-o somente se você também quiser inspecionar e gerenciar modelos de um terminal:

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

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

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

Note

Se você precisar direcionar plataformas não Windows, use Microsoft.AI.Foundry.Local em vez disso. Ele fornece a mesma interface da API Local do Foundry, sem a integração com o Windows ML.

O comando acima instala o pacote estável atual. O tutorial do WinUI usa o .NET 10 e fixa as versões dos pacotes para que você possa reproduzir todo o passo a passo.

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

Para oferecer uma melhor experiência do usuário em aplicativos de interface, 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 de modelo completa) para GetModelAsync que o Foundry Local possa selecionar uma variante de hardware compatível. Dependendo do modelo e do dispositivo, isso pode ser uma variante de NPU QNN no Snapdragon, uma variante CUDA na NVIDIA ou uma variante de CPU.

Se você instalou a CLI opcional, execute-a para ver os aliases disponíveis:

foundry model list

Por exemplo, use phi-4-mini para o modelo Phi-4 Mini Microsoft. O catálogo muda ao longo do tempo, portanto, verifique o catálogo de modelos local do Foundry para obter os aliases atuais e as variantes disponíveis.

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á na documentação do Microsoft Foundry.

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

Importante

O foundry-local pacote no PyPI (sem -sdk) é um pacote de terceiros não relacionado. Instale foundry-local-sdk ou foundry-local-sdk-winml para obter o SDK Local do Microsoft Foundry.

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

Execute-o:

python app.py

Para obter o início rápido Python completo, incluindo a configuração do provedor de execução, o tratamento de erros e a listagem de modelos, consulte Introdução ao Foundry Local na documentação do Microsoft Foundry.

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.

Para obter um passo a passo completo do aplicativo, continue para o tutorial do WinUI. Ele aborda consentimento explícito para download do modelo, progresso do download, cancelamento, acessibilidade e revisão do resultado.

Adicionar IA local a um aplicativo WinUI

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

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.

  • Última atualização em