Kom igång med Foundry Local

Foundry Local möjliggör lokal körning av stora språkmodeller (LLM: er) direkt på din Windows enhet, som en del av Microsoft Foundry på Windows. Det är ett bra alternativ när du behöver gå djupare än Windows AI-API:er, eller behöver stödja maskinvara som inte är en Copilot+ PC. Inga särskilda behörigheter eller upplåsningstoken krävs – de körs helt på din egen maskinvara. Samma mönster fungerar i en konsolapp, en WinUI 3-app, en WPF-app eller någon annan .NET värd.

Prerequisites

• Windows 11 version 24H2 (version 26100) eller senare
• .NET 9.0 SDK eller senare
• En DirectX 12-kompatibel GPU (integrerad eller diskret). Paketet WinML använder maskinvaruacceleration och kräver verklig GPU-maskinvara – virtuella datorer utan GPU-genomströmning stöds inte.

Installera Foundry Local CLI

Installera CLI med winget:

winget install Microsoft.FoundryLocal

Stäng och öppna sedan terminalen igen så att foundry kommandot finns på din PATH. Kontrollera:

foundry --version

Skapa ett projekt

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

NuGet-paketet innehåller interna Windows binärfiler, så projektet behöver ett Windows målramverk och körningsidentifierare. Öppna FoundryLocalDemo.csproj och ersätt <PropertyGroup> blocket med:

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

Återställ sedan för att generera tillgångsfilen för det nya målet:

dotnet restore

Installera NuGet-paketet

Installera WinML-paketet, som automatiskt använder den bästa tillgängliga maskinvaran (Qualcomm NPU, NVIDIA GPU eller CPU) via ONNX Runtime:

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

Paketet Betalgo.Ranul.OpenAI innehåller de ChatMessage och relaterade typer som används av Foundry Local chat-API:et.

Snabbstart: kör en modell

Ersätt innehållet i Program.cs med följande och kör dotnet runsedan . Programmet initierar Foundry Local, laddar ned modellen om det behövs, kör en chatt och rensar upp.

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

Direktuppspelningssvar

För en bättre användarupplevelse i UI-appar kan du strömma svaret token för token. Det här kodfragmentet fortsätter från snabbstarten ovan – chatClient kommer från steg 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();

Justera genereringsparametrar

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

Modell-alias

Skicka ett modellalias (inte ett fullständigt modell-ID) till GetModelAsync så att Foundry Local automatiskt väljer den bästa maskinvaruvarianten, till exempel en QNN NPU-variant på Snapdragon, en CUDA-variant på NVIDIA eller ett CPU-alternativ i alla andra fall.

Kör CLI för att se tillgängliga alias:

foundry model list

Vanliga alias: phi-3.5-mini, phi-4, qwen2.5-0.5b (minsta – bra för snabb testning), qwen2.5-7b, deepseek-r1-7b. Den fullständiga katalogen finns på foundrylocal.ai/models.

Python snabbstart

Foundry Local stöder även Python, JavaScript (Node.js) och Rust. Här är det minimala Python exemplet för att bekräfta att mönstret fungerar – den fullständiga genomgången för alla fyra språken finns i Azure AI Foundry docs.

Installera något av följande – installera inte båda eftersom de har motstridiga onnxruntime-core beroenden:

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

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

Kör den:

python app.py

Fullständig Python snabbstart – inklusive konfiguration av körningsprovider, felhantering och modelllista – finns i Komma igång med Foundry Local i Azure AI Foundry dokument.

Använda från en WinUI 3- eller WPF-app

Initiera en gång i App.xaml.cs eller App.cs:

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

FoundryLocalManager.Instance Lös sedan var som helst i appen. Anropa Dispose() i appens avslutningshanterare.

Omkoppling till molnet

Kombinera Foundry Local med Windows AI API:er och Azure OpenAI för ett motståndskraftigt flernivåmönster. Se Välj din Windows AI-lösning för ett fullständigt kompilerbart exempel.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Dessa varningar visas när programmet har avslutats och är godartade. De kommer från det underliggande ONNX Runtime GenAI-bibliotekets interna resursspårning. Dina utdata är korrekta. varningarna tyder inte på något problem med koden.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Den här varningen från ONNX Runtime innebär att biblioteket inte känner igen ARM SoC för identifiering av CPU-funktioner. Den återgår till säkra standardvärden och slutsatsdragningen körs normalt. Ingen åtgärd krävs.

Model '...' not found in catalog
SDK:et hämtar modellkatalogen från Internet. Kontrollera nätverksanslutningen. Om det inte finns något specifikt modellalias kan du köra foundry model list för att se tillgängliga alias eller bläddra i den fullständiga katalogen på foundrylocal.ai/models.

Modellen returnerar tomt innehåll
WinML-serverdelen kräver en DirectX 12-kompatibel GPU. Virtuella datorer utan GPU-genomströmning returnerar ett lyckat svar med tomt innehåll. Kör på fysisk maskinvara med en diskret eller integrerad GPU.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Den här pip-beroendekonflikten innebär att både foundry-local-sdk-winml och foundry-local-sdk installeras – de låser olika versioner av onnxruntime-core och kan inte existera samtidigt. Avinstallera en av dessa:

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

Installera sedan om den du vill ha. Om du använder en virtuell miljö undviker du problemet helt och hållet.

• Full Foundry Local-dokumentation – CLI, REST API, Python SDK, modellhantering
• Foundry Local C# SDK-referens – fullständig API-referens
• Windows ML – ta med din egen ONNX-modell med fullständig EP-kontroll
• Välj din Windows AI-lösning – jämför alla Windows AI-alternativ