Erste Schritte mit Foundry Local

Foundry Local ermöglicht die lokale Ausführung großer Sprachmodelle (LLMs) direkt auf Ihrem Windows Gerät, im Rahmen von Microsoft Foundry auf Windows. Es ist eine gute Alternative, wenn Sie tiefer als die Windows AI-APIs gehen müssen oder Hardware unterstützen müssen, die keine Copilot+ PC ist. Es sind keine speziellen Berechtigungen oder Entsperrungstoken erforderlich – sie wird vollständig auf Ihrer eigenen Hardware ausgeführt. Dasselbe Muster funktioniert in einer Konsolen-App, einer WinUI 3-App, einer WPF-App oder einem anderen .NET-Host.

Prerequisites

• Windows 10 Build 26100 oder höher (Windows 11 24H2 oder höher empfohlen)
• .NET 9.0 SDK oder höher
• Eine DirectX 12-fähige GPU (integriert oder diskret). Das WinML Paket verwendet Hardwarebeschleunigung und erfordert reale GPU-Hardware. Virtuelle Computer ohne GPU-Passthrough werden nicht unterstützt.

Installieren der lokalen CLI für Foundry

Installieren Sie die CLI mit Winget:

winget install Microsoft.FoundryLocal

Schließen Sie das Terminal, und öffnen Sie es erneut, damit sich der foundry Befehl auf Ihrem PATH befindet. Überprüfen:

foundry --version

Projekt erstellen

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Das NuGet-Paket enthält systemeigene Windows Binärdateien, sodass das Projekt ein Windows Zielframework und Laufzeit-IDs benötigt. Öffnen Sie FoundryLocalDemo.csproj und ersetzen Sie den <PropertyGroup> Block durch:

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

Stellen Sie dann wieder her, um die Assets-Datei für das neue Ziel zu generieren.

dotnet restore

Installieren des NuGet-Pakets

Installieren Sie das WinML-Paket, das automatisch die beste verfügbare Hardware (Qualcomm NPU, NVIDIA GPU oder CPU) über ONNX Runtime verwendet:

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

Das Betalgo.Ranul.OpenAI-Paket stellt ChatMessage und die zugehörigen Typen zur Verfügung, die von der Foundry Lokalen Chat-API verwendet werden.

Schnellstart: Ausführen eines Modells

Ersetzen Sie den Inhalt von Program.cs durch Folgendes und führen Sie dann dotnet run aus. Das Programm initialisiert Foundry Local, lädt bei Bedarf das Modell herunter, führt eine Chat-Vervollständigung aus und bereinigt.

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

Antworten bei Streaming-Diensten

Um eine bessere Benutzererfahrung in UI-Apps zu erzielen, streamen Sie das Antwort-Token für Token. Dieser Codeausschnitt wird vom obigen Schnellstart fortgesetzt – chatClient stammt aus Schritt 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();

Anpassen von Erzeugungsparametern

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

Modellaliase

Übergeben Sie einen Modellalias (nicht eine vollständige Modell-ID) an GetModelAsync damit Foundry Local automatisch die beste Hardwarevariante auswählt – z. B. eine QNN NPU-Variante auf Snapdragon, eine CUDA-Variante auf NVIDIA oder ein CPU-Fallback in allen anderen Fällen.

Führen Sie die CLI aus, um verfügbare Aliase anzuzeigen:

foundry model list

Allgemeine Aliase: phi-3.5-mini, , phi-4( qwen2.5-0.5b kleinste — gut für schnelle Tests), qwen2.5-7b, deepseek-r1-7b. Der vollständige Katalog befindet sich bei foundrylocal.ai/models.

Python-Schnellstart

Foundry Local unterstützt auch Python, JavaScript (Node.js) und Rust. Hier ist das minimale Python Beispiel, um die Funktionsweise des Musters zu bestätigen. Die vollständige exemplarische Vorgehensweise für alle vier Sprachen befindet sich in den Dokumenten Azure AI Foundry .

Installieren Sie eine der folgenden : Installieren Sie nicht beide, da sie konfliktesierende onnxruntime-core Abhängigkeiten haben:

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

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

Ausführen:

python app.py

Die vollständige Python-Schnellstartanleitung – einschließlich Einrichtung der Ausführungsumgebung, Fehlerbehandlung und Modellauflistung – finden Sie unter Get started with Foundry Local in der Dokumentation zu Azure AI Foundry .

Verwenden aus einer WinUI 3- oder WPF-App

Initialisieren Sie einmal in App.xaml.cs oder App.cs:

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

Lösen Sie dann FoundryLocalManager.Instance überall in der App auf. Rufen Sie im Exit-Handler der App Dispose() auf.

Fallback in die Cloud

Kombinieren Sie Foundry Local mit Windows AI-APIs und Azure OpenAI für ein robustes mehrstufiges Muster. Ein vollständiges kompilierbares Beispiel finden Sie unter Wählen Sie Ihre Windows AI-Lösung.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Diese Warnungen werden nach dem Beenden des Programms angezeigt und sind gutartig. Sie stammen aus dem systemeigenen Ressourcen-Tracking der zugrunde liegenden ONNX Runtime GenAI (OGA) Bibliothek. Ihre Ausgabe ist richtig; die Warnungen deuten nicht auf ein Problem mit Ihrem Code hin.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Diese Warnung von ONNX-Runtime bedeutet, dass die Bibliothek Ihren ARM SoC für die ERKENNUNG von CPU-Funktionen nicht erkennt. Es fällt auf sichere Standardwerte zurück, und die Ableitung wird normal ausgeführt. Es ist keine Aktion erforderlich.

Model '...' not found in catalog
Das SDK ruft den Modellkatalog aus dem Internet ab. Überprüfen Sie Ihre Netzwerkverbindung. Wenn ein bestimmter Modellalias nicht gefunden wird, führen Sie die Ausführung foundry model list aus, um verfügbare Aliase anzuzeigen, oder durchsuchen Sie den vollständigen Katalog unter foundrylocal.ai/models.

Das Modell gibt leeren Inhalt zurück.
Für das WinML-Back-End ist eine DirectX 12-fähige GPU erforderlich. Virtuelle Computer ohne GPU-Passthrough geben eine erfolgreiche Antwort mit leeren Inhalten zurück. Führen Sie die Ausführung auf physischer Hardware mit einer separaten oder integrierten GPU aus.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Dieser Pip-Abhängigkeitskonflikt bedeutet, dass foundry-local-sdk-winml und foundry-local-sdk beide installiert sind – sie fixieren unterschiedliche Versionen von onnxruntime-core und können nicht nebeneinander existieren. Deinstallieren Sie eine:

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

Installieren Sie dann das gewünschte neu. Die Verwendung einer virtuellen Umgebung vermeidet dieses Problem vollständig.

• Full Foundry Local documentation — CLI, REST API, Python SDK, Modellverwaltung
• Foundry Local C# SDK-Referenz – vollständige API-Referenz
• Windows ML – Bringen Sie Ihr eigenes ONNX-Modell mit vollständiger EP-Kontrolle.
• Wählen Sie Ihre Windows KI-Lösung – vergleichen Sie alle Windows KI-Optionen.