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. Das systemeigene SDK wird in Ihrem App-Prozess ausgeführt und erfordert nicht die lokale Cli für Foundry oder einen separaten lokalen REST-Server. Dasselbe Muster funktioniert in einer Konsolen-App, einer WinUI 3-App, einer WPF-App oder einem anderen .NET-Host.

Logos von Technologien im Zusammenhang mit Foundry Local

Note

Vollständige Dokumentation für Foundry Local – einschließlich CLI, Modellverwaltung, optionaler REST-Server, Python SDK und vieles mehr – wird in der Microsoft Foundry-Dokumentation verwaltet. Links auf dieser Seite bringen Sie bei Bedarf dorthin. Verwenden Sie die Zurück-Schaltfläche Ihres Browsers oder den Navigationspfad, um jederzeit zu den Windows AI-Dokumenten zurückzukehren.

Wenn Sie nicht sicher sind, ob Foundry Local die richtige Wahl für Ihr Szenario ist, lesen Sie Choose Ihrer Windows AI-Lösung, bevor Sie fortfahren.

Prerequisites

  • Windows 11, Version 24H2 (Build 26100) oder höher
  • .NET 9.0 SDK oder höher
  • Ein x64- oder Arm64-Gerät mit genügend Arbeitsspeicher und Speicherplatz für das ausgewählte Modell
  • Internetzugriff für das Herunterladen des ersten Pakets, des Modells und der Laufzeitkomponenten

Das Windows SDK kann kompatible CPU-, GPU- und NPU-Modellvarianten verwenden. Eine dedizierte GPU, NPU oder Copilot+ PC ist nicht erforderlich, wenn das ausgewählte Modell über eine kompatible CPU-Variante verfügt. Die verfügbare Beschleunigung und Leistung hängen von Ihrem Gerät, Modell und Ausführungsanbieter ab.

Note

Diese Schnellstartanleitung verwendet Phi-4 Mini, derzeit das neueste Microsoft Phi-Modell, das über den Foundry Local Alias phi-4-miniverfügbar ist. Foundry Local-Katalogaliase und empfohlene Modelle können sich ändern, wenn sich der Katalog weiterentwickelt.

Phi-4 Mini unterscheidet sich von Phi Silica, dem Windows AI-API-Modell, das mit Windows ausgeliefert wird. Phi Silica bleibt ein Feature für eingeschränkten Zugriff und erfordert ein Entsperrtoken. Es wird geplant, durch Aion Instruct ersetzt zu werden, was kein Token für eingeschränkten Zugriff erfordert. Informationen zum Zugriff und zum Zeitplan für die Umstellung finden Sie unter Erste Schritte mit Phi Silica.

Optional: Installieren der lokalen CLI für Foundry

Der SDK-Workflow in dieser Schnellstartanleitung erfordert keine CLI. Installieren Sie es nur, wenn Sie modelle auch über ein Terminal prüfen und verwalten möchten:

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>

Führen Sie dann eine Wiederherstellung durch, um die Assetdatei für das neue Ziel zu generieren.

dotnet restore

Installieren des NuGet-Pakets

Installieren Sie das aktuelle stabile Windows Paket:

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

Das Paket enthält den ChatMessage und zugehörige Typen, die von der nativen Chat-API von Foundry Local verwendet werden. Es wählt eine kompatible Modellvariante für das aktuelle Gerät aus und kann Windows ML-Ausführungsanbieter für die Hardwarebeschleunigung verwenden.

Note

Wenn Sie nicht auf Windows Plattformen abzielen müssen, verwenden Sie stattdessen Microsoft.AI.Foundry.Local. Sie stellt die gleiche lokale Findry-API-Oberfläche ohne die Windows ML-Integration bereit.

Mit dem obigen Befehl wird das aktuelle stabile Paket installiert. Das WinUI-Lernprogramm verwendet .NET 10- und pins-Paketversionen, sodass Sie die vollständige exemplarische Vorgehensweise reproduzieren können.

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

Antworten bei Streaming-Diensten

Um eine bessere Benutzererfahrung in UI-Apps zu erzielen, streamen Sie die 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 die vollständige Modell-ID) an GetModelAsync, damit Foundry Local eine kompatible Hardwarevariante auswählen kann. Je nach Modell und Gerät kann dies eine QNN NPU-Variante auf Snapdragon, eine CUDA-Variante auf NVIDIA oder eine CPU-Variante sein.

Wenn Sie die optionale CLI installiert haben, führen Sie sie aus, um verfügbare Aliase anzuzeigen:

foundry model list

Verwenden Sie phi-4-mini z. B. für das Microsoft Phi-4 Mini-Modell. Der Katalog ändert sich im Laufe der Zeit. Überprüfen Sie daher den Foundry Local-Modellkatalog auf die aktuellen Aliase und die verfügbaren Varianten.

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 der dokumentation Microsoft 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

Important

Das foundry-local Paket auf PyPI (ohne -sdk) ist ein nicht verwandtes Drittanbieterpaket. Installieren Sie foundry-local-sdk oder foundry-local-sdk-winml, um das Microsoft Foundry Local SDK abzurufen.

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

Ausführen:

python app.py

Den vollständigen Python-Schnellstart – einschließlich der Einrichtung des Execution-Providers, der Fehlerbehandlung und der Modellliste – finden Sie unter Erste Schritte mit Foundry Local in der Microsoft Foundry-Dokumentation.

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

Eine vollständige Schritt-für-Schritt-Anleitung zur App finden Sie im WinUI-Tutorial. Es behandelt explizite Zustimmung zum Modelldownload, Fortschritt, Abbruch, Barrierefreiheit und Ausgabeüberprüfung.

Hinzufügen lokaler KI zu einer WinUI-App

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.
Versuchen Sie die Anforderung erneut, und bestätigen Sie, dass das ausgewählte Modell über eine kompatible Variante für Ihr Gerät verfügt. Wenn das Problem weiterhin besteht, wählen Sie ein kleineres Modell oder eine CPU-Variante aus, und überprüfen Sie, ob das Gerät über genügend Arbeitsspeicher verfügt.

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 heften unterschiedliche Versionen von onnxruntime-core an 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.

  • Zuletzt aktualisiert um