Aan de slag met Foundry Local

Foundry Local maakt lokale uitvoering van grote taalmodellen (LLM's) rechtstreeks op uw Windows apparaat mogelijk, als onderdeel van Microsoft Foundry op Windows. Het is een goed alternatief als u dieper moet gaan dan de Windows AI-API's of hardware moet ondersteunen die geen Copilot+ PC is. Er zijn geen speciale machtigingen of ontgrendelingstokens vereist. De systeemeigen SDK wordt uitgevoerd in uw app-proces en vereist geen lokale CLI van Foundry of een afzonderlijke lokale REST-server. Hetzelfde patroon werkt in een console-app, een WinUI 3-app, een WPF-app of een andere .NET host.

Logo's van technologieën die zijn gekoppeld aan Foundry Local

Note

Volledige documentatie voor Foundry Local, waaronder de CLI, modelbeheer, de optionele REST-server, Python SDK en meer, wordt onderhouden in de Microsoft Foundry-documentatie. Links op deze pagina brengen je daar indien nodig. Gebruik de knop Terug van uw browser of de breadcrumb om op elk gewenst moment terug te keren naar de Windows AI-documenten.

Als u niet zeker weet of Foundry Local de juiste keuze is voor uw scenario, raadpleegt u Choose uw Windows AI-oplossing voordat u doorgaat.

Prerequisites

  • Windows 11, versie 24H2 (build 26100) of hoger
  • .NET SDK 9.0 of hoger
  • Een x64- of Arm64-apparaat met voldoende geheugen en schijfruimte voor het model dat u selecteert
  • Internettoegang voor het downloaden van het eerste pakket, model en runtimecomponent

De Windows SDK kan compatibele varianten voor CPU-, GPU- en NPU-modellen gebruiken. Een toegewezen GPU, NPU of Copilot+ PC is niet vereist wanneer het geselecteerde model een compatibele CPU-variant heeft. De beschikbare versnelling en prestaties zijn afhankelijk van uw apparaat, model en uitvoeringsprovider.

Note

Deze quickstart maakt gebruik van Phi-4 Mini, momenteel het nieuwste Microsoft Phi-model dat beschikbaar is via de Foundry Local-aliasphi-4-mini. Foundry Local catalog aliassen en aanbevolen modellen kunnen veranderen naarmate de catalogus zich ontwikkelt.

Phi-4 Mini is gescheiden van PhiSilium, het Windows AI API-model dat wordt geleverd met Windows. PhiSilium blijft een beperkte toegangsfunctie en vereist een ontgrendelingstoken. Het is gepland om te worden vervangen door Aion Instruct, waarvoor geen token voor beperkte toegang is vereist. Zie Aan de slag met Phi Silicium voor toegangsdetails en de tijdlijn voor overgangen.

Optioneel: De lokale CLI van Foundry installeren

Voor de SDK-werkstroom in deze quickstart is de CLI niet vereist. Installeer deze alleen als u ook modellen vanuit een terminal wilt inspecteren en beheren:

winget install Microsoft.FoundryLocal

Sluit de terminal en open deze opnieuw, zodat de foundry opdracht op uw PATH staat. Controleren:

foundry --version

Een project maken

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Het NuGet-pakket bevat systeemeigen Windows binaire bestanden, dus het project heeft een Windows doelframework en runtime-id's nodig. Het FoundryLocalDemo.csproj blok openen en vervangen door <PropertyGroup> :

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

Voer vervolgens het herstelproces uit om het assetsbestand voor het nieuwe doel te genereren.

dotnet restore

Installeer het NuGet-pakket

Installeer het huidige stabiele Windows-pakket:

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

Het pakket bevat ChatMessage en verwante typen die worden gebruikt door de native chat-API van Foundry Local. Het selecteert een compatibele modelvariant voor het huidige apparaat en kan Windows ML-uitvoeringsproviders gebruiken voor hardwareversnelling.

Note

Als u niet-Windows platforms wilt gebruiken, gebruikt u in plaats daarvan Microsoft.AI.Foundry.Local. Het biedt hetzelfde Local API-oppervlak van Foundry zonder de Windows ML-integratie.

Met de bovenstaande opdracht wordt het huidige stabiele pakket geïnstalleerd. De WinUI-zelfstudie maakt gebruik van .NET 10 en legt pakketversies vast, zodat u de volledige stapsgewijze uitleg kunt reproduceren.

Snel aan de slag: een model uitvoeren

Vervang de inhoud van Program.cs met het volgende en voer vervolgens dotnet run uit. Het programma initialiseert Foundry Local, downloadt het model indien nodig, voert een chatvoltooiing uit en schoont het op.

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

Streamingantwoorden

Voor een betere gebruikerservaring in UI-apps streamt u het antwoordtoken per token. Dit fragment bouwt voort op de snelstart hierboven — chatClient afkomstig uit stap 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();

Parameters voor generatie afstemmen

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

Model-aliassen

Geef een modelalias (geen volledige model-id) door zodat GetModelAsync Foundry Local een compatibele hardwarevariant kan selecteren. Afhankelijk van het model en het apparaat kan dit een QNN NPU-variant op Snapdragon, een CUDA-variant op NVIDIA of een CPU-variant zijn.

Als u de optionele CLI hebt geïnstalleerd, voert u deze uit om de beschikbare aliassen te zien:

foundry model list

Gebruik bijvoorbeeld phi-4-mini voor het Microsoft Phi-4 Mini-model. De catalogus verandert in de loop van de tijd, dus controleer de lokale modelcatalogus van Foundry voor de huidige aliassen en beschikbare varianten.

Python snelstart

Foundry Local ondersteunt ook Python, JavaScript (Node.js) en Rust. Hier volgt het minimale Python voorbeeld om te bevestigen dat het patroon werkt. De volledige handleiding voor alle vier talen staat in de documentatie van Microsoft Foundry.

Installeer een van de volgende: installeer beide niet, omdat ze conflicterende onnxruntime-core afhankelijkheden hebben:

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

Belangrijk

Het foundry-local pakket op PyPI (zonder -sdk) is een niet-gerelateerd pakket van derden. Installeer foundry-local-sdk of foundry-local-sdk-winml om de Microsoft Local SDK voor Foundry op te halen.

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

Voer het uit:

python app.py

Zie voor de volledige Python-snelstartgids — inclusief het configureren van de uitvoeringsprovider, foutafhandeling en de modellenlijst — Aan de slag met Foundry Local in de Microsoft Foundry-documentatie.

Gebruiken vanuit een WinUI 3- of WPF-app

Initialiseer eenmaal in App.xaml.cs of App.cs:

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

Los FoundryLocalManager.Instance vervolgens overal in de app op. Roep Dispose() aan bij de afsluithandler van de app.

Ga voor een volledige stapsgewijze uitleg van de toepassing door naar de WinUI-zelfstudie. Het behandelt expliciete toestemming voor het downloaden van modellen, voortgang, annulering, toegankelijkheid en uitvoerbeoordeling.

Lokale AI toevoegen aan een WinUI-app

Terugval naar de cloud

Combineer Foundry Local met Windows AI-API's en Azure OpenAI voor een tolerant patroon met meerdere lagen. Zie Kies uw AI-oplossing voor Windows voor een volledig compileerbaar voorbeeld.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Deze waarschuwingen worden weergegeven nadat het programma is afgesloten en zijn onschadelijk. Ze komen uit de systeemeigen resource-tracking van de onderliggende ONNX Runtime GenAI (OGA)-bibliotheek. Uw uitvoer is juist; de waarschuwingen geven geen probleem aan met uw code.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Deze waarschuwing van ONNX Runtime betekent dat de bibliotheek uw ARM SoC niet herkent voor detectie van CPU-functies. Het valt terug op veilige standaardwaarden en inference draait normaal. Geen actie nodig.

Model '...' not found in catalog
De SDK haalt de modelcatalogus op van internet. Controleer de netwerkverbinding. Als er geen specifieke modelalias wordt gevonden, voert u deze uit foundry model list om beschikbare aliassen te zien of bladert u door de volledige catalogus op foundrylocal.ai/models.

Model retourneert lege inhoud
Probeer de aanvraag opnieuw en controleer of het geselecteerde model een compatibele variant voor uw apparaat heeft. Als het probleem zich blijft voordoen, selecteert u een kleiner model of een CPU-variant en controleert u of het apparaat voldoende beschikbaar geheugen heeft.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Dit pip-afhankelijkheidsconflict betekent dat zowel foundry-local-sdk-winml als foundry-local-sdk zijn geïnstalleerd en ze zetten verschillende versies van onnxruntime-core vast, waardoor ze niet naast elkaar kunnen bestaan. Verwijder er een:

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

Installeer vervolgens de gewenste versie opnieuw. Het gebruik van een virtuele omgeving voorkomt dit probleem volledig.

  • Laatst bijgewerkt om