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. Det interna SDK:t körs i din appprocess och kräver inte Foundry Local CLI eller en separat lokal REST-server. 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 x64- eller Arm64-enhet med tillräckligt med minne och diskutrymme för den modell du väljer
• Internetåtkomst för de första paket-, modell- och körningskomponentnedladdningarna

Windows SDK kan använda kompatibla processor-, GPU- och NPU-modellvarianter. En dedikerad GPU, NPU eller Copilot+ PC krävs inte när den valda modellen har en kompatibel PROCESSORvariant. Tillgänglig acceleration och prestanda beror på din enhet, modell och körningsprovider.

Valfritt: Installera Foundry Local CLI

SDK-arbetsflödet i den här snabbstarten kräver inte CLI. Installera den bara om du också vill inspektera och hantera modeller från en terminal:

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 det aktuella stabila Windows paketet:

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

Paketet innehåller de ChatMessage och relaterade typer som används av Foundry Locals interna chatt-API. Den väljer en kompatibel modellvariant för den aktuella enheten och kan använda Windows ML-körningsproviders för maskinvaruacceleration.

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

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 kan välja en kompatibel maskinvaruvariant. Beroende på modell och enhet kan detta vara en QNN NPU-variant på Snapdragon, en CUDA-variant på NVIDIA eller en CPU-variant.

Om du har installerat det valfria CLI:et kör du det för att se tillgängliga alias:

foundry model list

Använd till exempel phi-4-mini för minimodellen Microsoft Phi-4. Katalogen ändras över tid, så kontrollera foundry Local-modellkatalogen för aktuella alias och tillgängliga varianter.

Python snabbstart

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

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

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 dokumentationen om Microsoft Foundry.

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.

Om du vill ha en fullständig genomgång av programmet fortsätter du till WinUI-självstudien. Den omfattar explicit modellnedladdningsmedgivande, förlopp, annullering, tillgänglighet och utdatagranskning.

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
Försök igen och bekräfta att den valda modellen har en kompatibel variant för enheten. Om problemet kvarstår väljer du en mindre modell eller en CPU-variant och kontrollerar att enheten har tillräckligt med tillgängligt minne.

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 SDK-referens – SDK-konfiguration och API-vägledning
• 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