Začínáme s Foundry Local

Foundry Local umožňuje místní spouštění rozsáhlých jazykových modelů (LLM) přímo na zařízení Windows v rámci Microsoft Foundry na Windows. Je to dobrá alternativa, pokud potřebujete jít hlouběji než Windows rozhraní API AI nebo potřebujete podporovat hardware, který není Copilot+ PC. Nejsou vyžadována žádná zvláštní oprávnění ani odemykání tokenů. Nativní sada SDK běží v procesu aplikace a nevyžaduje místní rozhraní příkazového řádku Foundry ani samostatný místní server REST. Stejný vzor funguje v konzolové aplikaci, aplikaci WinUI 3, aplikaci WPF (Windows Presentation Foundation) nebo jiném hostiteli .NET.

Loga technologií spojených s Foundry Local

Note

Úplná dokumentace k Foundry Local , včetně rozhraní příkazového řádku, správy modelů, volitelného serveru REST, sady Python SDK a dalších, se udržuje v dokumentaci k Microsoft Foundry. Odkazy na této stránce vás tam zavedou, když je to potřeba. Pomocí tlačítka Zpět vašeho prohlížeče nebo navigační struktury se můžete kdykoliv vrátit do dokumentace pro Windows AI.

Pokud si nejste jistí, zda je Foundry Local pro váš scénář správnou volbou, přečtěte si téma Výběr řešení Windows AI a teprve potom pokračujte.

Prerequisites

  • Windows 11 verze 24H2 (build 26100) nebo novější
  • .NET 9.0 SDK nebo novější
  • Zařízení x64 nebo Arm64 s dostatečnou pamětí a místem na disku pro vybraný model
  • Přístup k internetu pro počáteční balíček, model a stahování komponent modulu runtime

Sada Windows SDK může používat kompatibilní varianty modelů CPU, GPU a NPU. Pokud má vybraný model kompatibilní variantu procesoru, není vyžadován vyhrazený GPU, NPU nebo Copilot+ PC. Dostupná akcelerace a výkon závisí na vašem zařízení, modelu a poskytovateli spouštění.

Note

V tomto rychlém startu se používá Phi-4 Mini, aktuálně nejnovější model Microsoft Phi dostupný prostřednictvím aliasu phi-4-miniFoundry Local . Aliasy místního katalogu Foundry a doporučené modely se můžou při vývoji katalogu změnit.

Phi-4 Mini je oddělený od Phi Silica, model rozhraní API Windows AI, který se dodává s Windows. Phi Silica zůstává funkcí omezeného přístupu a vyžaduje token odemknutí. Je naplánováno, že bude nahrazen službou Aion Instruct, která nebude vyžadovat token pro funkci s omezeným přístupem. Podrobnosti o přístupu a časovou osu přechodu najdete v tématu Začínáme s Phi Silica .

Volitelné: Instalace místního rozhraní příkazového řádku Foundry

Pracovní postup sady SDK v tomto rychlém startu nevyžaduje rozhraní příkazového řádku. Nainstalujte ho jenom v případě, že chcete zkontrolovat a spravovat modely z terminálu:

winget install Microsoft.FoundryLocal

Poté zavřete a znovu otevřete terminál, aby se příkaz foundry dostal do vašeho PATH. Ověřit:

foundry --version

Vytvoření projektu

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Balíček NuGet obsahuje nativní binární soubory Windows, takže projekt potřebuje Windows cílové rozhraní a identifikátory modulu runtime. Otevřete FoundryLocalDemo.csproj a nahraďte <PropertyGroup> blok:

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

Potom obnovte a vygenerujte soubor prostředků (assets file) pro nový cíl:

dotnet restore

Instalace balíčku NuGet

Nainstalujte aktuální stabilní balíček Windows:

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

Balíček obsahuje ChatMessage a související typy používané v nativním chatovacím rozhraní API Foundry Local. Vybere kompatibilní variantu modelu pro aktuální zařízení a může použít poskytovatele spouštění Windows ML pro hardwarovou akceleraci.

Note

Pokud potřebujete cílit na jiné platformy než Windows, použijte místo toho Microsoft.AI.Foundry.Local. Poskytuje stejnou plochu místního rozhraní API Foundry bez integrace Windows ML.

Výše uvedený příkaz nainstaluje aktuální stabilní balíček. Kurz WinUI používá .NET 10 a připíná verze balíčků, abyste mohli reprodukovat kompletní návod.

Rychlý start: Spuštění modelu

Nahraďte obsah Program.cs následujícím kódem a spusťte dotnet runpříkaz . Program inicializuje Foundry Local, v případě potřeby stáhne model, spustí dokončení chatu a vyčistí.

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

Streamující odpovědi

Pro lepší uživatelské prostředí v UI aplikacích streamujte odpověď token po tokenu. Tento fragment kódu pokračuje z výše uvedeného rychlého startu – chatClient pochází z kroku 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();

Ladění parametrů generování

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

Aliasy modelů

Předejte alias modelu (nikoli úplné ID modelu), aby GetModelAsync Foundry Local mohl vybrat kompatibilní variantu hardwaru. V závislosti na modelu a zařízení může jít o variantu QNN NPU na platformě Snapdragon, variantu CUDA na platformě NVIDIA nebo variantu CPU.

Pokud jste nainstalovali volitelné rozhraní příkazového řádku, spusťte ho a zobrazte dostupné aliasy:

foundry model list

Použijte například phi-4-mini pro model Microsoft Phi-4 Mini. Katalog se v průběhu času mění, proto zkontrolujte katalog místních modelů Foundry pro aktuální aliasy a dostupné varianty.

rychlý start pro Python

Foundry Local také podporuje Python, JavaScript (Node.js) a Rust. Tady je minimální Python příklad k potvrzení fungování vzoru – úplný návod pro všechny čtyři jazyky je v dokumentaci Microsoft Foundry.

Nainstalujte jednu z následujících možností – nenainstalujte obojí, protože mají konfliktní onnxruntime-core závislosti:

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

Balíček foundry-local na PyPI (bez -sdk) je nesouvisející balíček třetí strany. Nainstalujte foundry-local-sdk nebo foundry-local-sdk-winml, abyste získali místní sadu SDK Microsoft Foundry.

Vytvořit 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()

Spusťte ho:

python app.py

Kompletní stručný úvod k Pythonu – včetně nastavení poskytovatele spuštění, zpracování chyb a seznamu modelů – najdete v článku Začínáme s Foundry Local v dokumentaci k Microsoft Foundry.

Použití z aplikace WinUI 3 nebo WPF (Windows Presentation Foundation)

Inicializujte jednou v App.xaml.cs nebo App.cs:

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

Poté vyřešte FoundryLocalManager.Instance kdekoli v aplikaci. Zavolejte Dispose() v obslužné rutině ukončení aplikace.

Úplný návod k aplikaci najdete v kurzu WinUI. Týká se explicitního souhlasu ke stažení modelu, průběhu, zrušení, přístupnosti a kontroly výstupu.

Přidání místní umělé inteligence do aplikace WinUI

Návrat do cloudu

Kombinujte Foundry Local s rozhraními API Windows AI a Azure OpenAI pro odolný vícevrstvý vzor. Najděte kompletní příklad, který lze zkompilovat, v části Vyberte řešení Windows AI.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Tato upozornění se zobrazí po ukončení programu a jsou neškodná. Pocházejí z nativního sledování prostředků základní knihovny ONNX Runtime GenAI (OGA). Váš výstup je správný; upozornění neoznačují problém s vaším kódem.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Toto upozornění z modulu runtime ONNX znamená, že knihovna nerozpozná vaši architekturu ARM SoC pro detekci funkcí procesoru. Vrátí se na bezpečné výchozí hodnoty a odvozování běží normálně. Není potřeba žádná akce.

Model '...' not found in catalog
Sada SDK načte katalog modelů z internetu. Zkontrolujte síťové připojení. Pokud se konkrétní alias modelu nenajde, spusťte příkaz foundry model list , abyste zobrazili dostupné aliasy, nebo si projděte úplný katalog na foundrylocal.ai/models.

Model vrací prázdný obsah.
Zkuste požadavek zopakovat a potvrďte, že vybraný model má kompatibilní variantu pro vaše zařízení. Pokud problém přetrvává, vyberte menší model nebo variantu procesoru a zkontrolujte, jestli má zařízení dostatek dostupné paměti.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Tento konflikt závislostí pip znamená, že jsou nainstalovány jak foundry-local-sdk-winml, tak foundry-local-sdk — upevňují různé verze onnxruntime-core a nemohou vedle sebe existovat. Odinstalujte jednu z nich:

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

Potom znovu nainstalujte požadovanou verzi. Použití virtuálního prostředí se tomuto problému zcela vyhne.

  • Poslední aktualizace v