Bien démarrer avec Foundry Local

Foundry Local permet l’exécution locale de modèles de langage volumineux (LLMs) directement sur votre appareil Windows, dans le cadre de Microsoft Foundry sur Windows. C'est une bonne alternative lorsque vous devez aller plus loin que les API d'IA Windows, ou que vous devez prendre en charge du matériel qui n'est pas un Copilot+ PC. Aucune autorisation spéciale ni jetons de déverrouillage n’est nécessaire. Le SDK natif s’exécute dans votre processus d’application et ne nécessite pas l’interface CLI locale Foundry ou un serveur REST local distinct. Le même modèle fonctionne dans une application console, une application WinUI 3, une application WPF ou tout autre hôte .NET.

Logos des technologies associées à Foundry Local

Note

La documentation complète de Foundry Local ( y compris l’interface CLI, la gestion des modèles, le serveur REST facultatif, Python SDK, etc.) est conservée dans la documentation Microsoft Foundry. Les liens sur cette page vous dirigent là-bas lorsque nécessaire. Utilisez le bouton Précédent de votre navigateur ou le fil d'Ariane pour revenir aux documents Windows AI à tout moment.

Si vous ne savez pas si Foundry Local est le bon choix pour votre scénario, consultez Choisissez votre solution IA Windows avant de continuer.

Prerequisites

  • Windows 11, version 24H2 (build 26100) ou ultérieure
  • .NET sdk 9.0 ou version ultérieure
  • Un appareil x64 ou Arm64 avec suffisamment de mémoire et d’espace disque pour le modèle que vous sélectionnez
  • Accès Internet pour les téléchargements du package initial, du modèle et du composant runtime

Le sdk Windows peut utiliser des variantes de modèle processeur, GPU et NPU compatibles. Un GPU dédié, un NPU ou un Copilot+ PC n'est pas nécessaire lorsque le modèle sélectionné a une variante de processeur compatible. L’accélération et les performances disponibles dépendent de votre appareil, de votre modèle et de votre fournisseur d’exécution.

Note

Ce guide de démarrage rapide utilise Phi-4 Mini, actuellement le plus récent modèle Phi de Microsoft disponible via l’alias Foundry Local phi-4-mini. Les alias du catalogue Foundry Local et les modèles recommandés peuvent changer à mesure que le catalogue évolue.

Phi-4 Mini est séparé de Phi Silicon, le modèle d’API IA Windows qui est fourni avec Windows. Phi Silicon reste une fonctionnalité d’accès limité et nécessite un jeton de déverrouillage. Il est planifié pour être remplacé par Aion Instruct, qui ne nécessite pas de jeton de fonctionnalité d’accès limité. Pour plus d’informations sur l’accès et la chronologie de la transition, consultez Prise en main de Phi Silicon .

Facultatif : installer l’interface CLI locale Foundry

Le flux de travail du Kit de développement logiciel (SDK) de ce guide de démarrage rapide ne nécessite pas l’interface CLI. Installez-le uniquement si vous souhaitez également inspecter et gérer des modèles à partir d’un terminal :

winget install Microsoft.FoundryLocal

Fermez et rouvrez ensuite votre terminal afin que la foundry commande soit sur votre chemin d’accès. Vérifier:

foundry --version

Création d’un projet

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Le package NuGet inclut des fichiers binaires Windows natifs. Le projet a donc besoin d’un framework cible Windows et d’identificateurs d’exécution. Ouvrez FoundryLocalDemo.csproj et remplacez le <PropertyGroup> bloc par :

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

Restaurez ensuite pour générer le fichier de ressources pour la nouvelle cible :

dotnet restore

Installer le package NuGet

Installez le package Windows stable actuel :

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

Le package inclut les ChatMessage types associés utilisés par l’API de conversation native Foundry Local. Il sélectionne une variante de modèle compatible pour l’appareil actuel et peut utiliser les fournisseurs d’exécution Windows ML pour l’accélération matérielle.

Note

Si vous devez cibler des plateformes non Windows, utilisez Microsoft.AI.Foundry.Local à la place. Il fournit la même surface d’API locale Foundry sans l’intégration Windows ML.

La commande ci-dessus installe le package stable actuel. Le tutoriel WinUI utilise .NET 10 et fixe les versions des packages afin que vous puissiez reproduire l’intégralité du guide pas à pas.

Démarrage rapide : exécuter un modèle

Remplacez le contenu de Program.cs avec ce qui suit, puis exécutez dotnet run. Le programme initialise Foundry Local, télécharge le modèle si nécessaire, exécute une tâche de complétion de chat et nettoie.

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

Réponses en streaming

Pour une meilleure expérience utilisateur dans les applications d’interface utilisateur, diffusez en continu le jeton de réponse par jeton. Cet extrait de code se poursuit à partir du démarrage rapide ci-dessus : chatClient il provient de l’étape 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();

Ajuster les paramètres de génération

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

Alias de modèle

Transmettez un alias de modèle (pas un ID de modèle complet) pour GetModelAsync que Foundry Local puisse sélectionner une variante matérielle compatible. Selon le modèle et l’appareil, il peut s’agir d’une variante QNN pour NPU sur Snapdragon, d’une variante CUDA sur NVIDIA ou d’une variante CPU.

Si vous avez installé l’interface CLI facultative, exécutez-la pour afficher les alias disponibles :

foundry model list

Par exemple, utilisez phi-4-mini pour le modèle Microsoft Phi-4 Mini. Le catalogue change au fil du temps. Vérifiez donc le catalogue de modèles local Foundry pour connaître les alias actuels et les variantes disponibles.

démarrage rapide Python

Foundry Local prend également en charge Python, JavaScript (Node.js) et Rust. Voici l'exemple de Python minimal pour confirmer le modèle : la procédure pas à pas complète pour les quatre langues se trouve dans la documentation Microsoft Foundry.

Installez l’un des éléments suivants : n’installez pas les deux, car ils ont des dépendances en onnxruntime-core conflit :

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

Le foundry-local package sur PyPI (sans -sdk) est un package tiers non lié. Installez foundry-local-sdk ou foundry-local-sdk-winml pour obtenir le SDK local Microsoft Foundry.

Créez 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()

Exécutez-le :

python app.py

Pour obtenir le guide de démarrage rapide complet Python, notamment l’installation du fournisseur d’exécution, la gestion des erreurs et la liste des modèles, consultez Prise en main de Foundry Local dans la documentation Microsoft Foundry.

Utiliser à partir d’une application WinUI 3 ou WPF

Initialiser une fois dans App.xaml.cs ou App.cs:

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

Résolvez ensuite FoundryLocalManager.Instance n’importe où dans l’application. Appelez Dispose() dans le gestionnaire de sortie de l'application.

Pour une procédure pas à pas complète de l’application, passez au didacticiel WinUI. Il couvre le consentement explicite au téléchargement du modèle, l’avancement, l’annulation, l’accessibilité et la vérification du résultat.

Ajouter l’IA locale à une application WinUI

Basculement vers le cloud

Combinez Foundry Local avec Windows API IA et Azure OpenAI pour un modèle multiniveau résilient. Consultez Choose votre solution IA Windows pour obtenir un exemple compilé complet.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Ces avertissements apparaissent après la sortie du programme et sont bénins. Ils proviennent du suivi des ressources natives de la bibliothèque OGA (ONNX Runtime GenAI) sous-jacente. Votre sortie est correcte ; les avertissements n’indiquent pas de problème avec votre code.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Cet avertissement du runtime ONNX signifie que la bibliothèque ne reconnaît pas votre soC ARM pour la détection des fonctionnalités du processeur. Elle revient aux valeurs par défaut sécurisées et l'inférence s'exécute normalement. Aucune action n’est nécessaire.

Model '...' not found in catalog
Le Kit de développement logiciel (SDK) extrait le catalogue de modèles à partir d’Internet. Vérifiez votre connexion réseau. Si un alias de modèle spécifique n’est pas trouvé, exécutez foundry model list pour afficher les alias disponibles ou parcourez le catalogue complet à foundrylocal.ai/models.

Le modèle retourne du contenu vide
Réessayez la demande et vérifiez que le modèle sélectionné a une variante compatible pour votre appareil. Si le problème persiste, sélectionnez un modèle plus petit ou une variante de processeur et vérifiez que l’appareil dispose de suffisamment de mémoire disponible.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Ce conflit de dépendance pip signifie que foundry-local-sdk-winml et foundry-local-sdk sont tous deux installés — ils nécessitent des versions différentes de onnxruntime-core et ne peuvent pas coexister. Désinstallez-en une :

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

Réinstallez ensuite celui que vous souhaitez. L’utilisation d’un environnement virtuel évite entièrement ce problème.

  • Last updated on