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ů – běží zcela na vašem vlastním hardwaru. 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 pro Foundry Local, včetně rozhraní příkazového řádku, správy modelů, rozhraní REST API, sady PYTHON SDK a dalších, se udržuje v dokumentaci k Azure AI 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ší
GPU s podporou DirectX 12 (integrované nebo diskrétní). Balíček WinML používá hardwarovou akceleraci a vyžaduje skutečný hardware GPU – virtuální počítače bez průchodu GPU se nepodporují.

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

Nainstalujte rozhraní příkazového řádku pomocí wingetu:

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 balíček WinML, který automaticky využívá nejlepší dostupný hardware (Qualcomm NPU, NVIDIA GPU, nebo CPU) prostřednictvím ONNX Runtime.

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

Balíček Betalgo.Ranul.OpenAI poskytuje ChatMessage a další související typy používané rozhraním API pro místní chat Foundry.

Note

Pokud potřebujete cílit na jiné platformy než Windows, použijte místo toho Microsoft.AI.Foundry.Local. Rozhraní API je identické; tento balíček vynechá hardwarovou akceleraci specifické pro Windows.

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

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) do GetModelAsync, aby Foundry Local automaticky vybral nejlepší hardwarovou variantu — například variantu QNN NPU na Snapdragonu, variantu CUDA na NVIDIA nebo použití CPU všude jinde.

Spuštěním rozhraní příkazového řádku zobrazte dostupné aliasy:

foundry model list

Běžné aliasy: phi-3.5-mini, , phi-4qwen2.5-0.5b(nejmenší – vhodné pro rychlé testování), qwen2.5-7b, . deepseek-r1-7b Úplný katalog je na foundrylocal.ai/models.

rychlý start pro Python

Foundry Local také podporuje Python, JavaScript (Node.js) a Rust. Tady je minimální Python příklad pro potvrzení fungování vzoru – úplný návod pro všechny čtyři jazyky je v dokumentaci Azure AI 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("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()

Spusťte ho:

python app.py

Úplný rychlý průvodce Pythonem, včetně nastavení poskytovatele provádění, zpracování chyb a výpisu modelů, najdete v tématu Začněte s Foundry Local v dokumentaci k Azure AI 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.

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.
Back-end WinML vyžaduje GPU podporující DirectX 12. Virtuální počítače bez průchodu GPU vrátí úspěšnou odpověď s prázdným obsahem. Běží na fyzickém hardwaru s diskrétním nebo integrovaným GPU.

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.

Místní dokumentace ke služběFull Foundry – CLI, REST API, Python SDK, správa modelů
Referenční informace k místní sadě SDK pro Foundry v jazyce C# – kompletní referenční dokumentace k rozhraní API
Windows ML – používejte vlastní model ONNX s úplným řízením EP
Vyberte si vaše Windows AI řešení — porovnejte všechny možnosti Windows AI

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-11