Introduzione a Foundry Local

Foundry Local consente l'esecuzione locale di modelli di linguaggio di grandi dimensioni direttamente nel dispositivo Windows, come parte di Microsoft Foundry in Windows. È un'alternativa valida quando è necessario approfondire le API di intelligenza artificiale Windows o dover supportare l'hardware che non è un Copilot+ PC. Non sono necessarie autorizzazioni speciali o token di sblocco, che vengono eseguiti interamente sul proprio hardware. Lo stesso modello funziona in un'app console, in un'app WinUI 3, in un'app macchine virtuali Windows o in qualsiasi altro host .NET.

Prerequisites

• Windows 10 build 26100 o successiva (Windows 11 24H2 o versione successiva consigliata)
• .NET 9.0 SDK o versione successiva
• GPU con supporto per DirectX 12 (integrata o discreta). Il pacchetto usa l'accelerazione hardware e richiede hardware GPU reale. Le WinML macchine virtuali senza pass-through GPU non sono supportate.

Installare la CLI locale di Foundry

Installare l'interfaccia della riga di comando usando winget:

winget install Microsoft.FoundryLocal

Quindi chiudere e riaprire il terminale così il comando foundry sia nel PATH. Verificare:

foundry --version

Creare un progetto

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Il pacchetto NuGet include file binari nativi Windows, quindi il progetto necessita di un framework di destinazione Windows e identificatori di runtime. Aprire FoundryLocalDemo.csproj e sostituire il <PropertyGroup> blocco con:

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

Eseguire quindi il ripristino per generare il file di asset per la nuova destinazione:

dotnet restore

Installare il pacchetto NuGet

Installare il pacchetto WinML, che usa automaticamente il miglior hardware disponibile (Qualcomm NPU, NVIDIA GPU o CPU) tramite il runtime ONNX:

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

Il Betalgo.Ranul.OpenAI pacchetto fornisce i ChatMessage tipi correlati e usati dall'API chat locale Foundry.

Avvio rapido: eseguire un modello

Sostituire il contenuto di Program.cs con il codice seguente, quindi eseguire dotnet run. Il programma inizializza Foundry Local, scarica il modello, se necessario, esegue un completamento della chat e pulisce.

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

Risposte in streaming

Per un'esperienza utente migliore nelle app dell'interfaccia utente, trasmetti il token di risposta token per token. Questo frammento di codice prosegue dall'avvio rapido sopra menzionato: chatClient proviene dal passaggio 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();

Regolare i parametri di generazione

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

Alias del modello

Passare un alias del modello (non un ID modello completo) a GetModelAsync in modo che Foundry Local selezioni automaticamente la variante hardware migliore, ad esempio una variante di NPU QNN su Snapdragon, una variante CUDA su NVIDIA o un fallback della CPU in ogni altro caso.

Eseguire l'interfaccia della riga di comando per visualizzare gli alias disponibili:

foundry model list

Alias comuni: phi-3.5-mini, phi-4, qwen2.5-7b, deepseek-r1-7b. Il catalogo completo si trova in foundrylocal.ai/models.

Usare da un'app WinUI 3 o macchine virtuali Windows

Inizializza una volta in App.xaml.cs o App.cs:

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

Quindi risolvi FoundryLocalManager.Instance ovunque nell'app. Chiamare Dispose() nel gestore di uscita dell'app.

Fallback nel cloud

Combinare Foundry Local con Windows API di intelligenza artificiale e Azure OpenAI per un modello multilivello resiliente. Per un esempio compilabile completo, vedere Scegliere la soluzione di intelligenza artificiale Windows.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Questi avvisi vengono visualizzati dopo l'uscita del programma e non sono dannosi. Provengono dal rilevamento delle risorse nativo della libreria ONNX Runtime GenAI (OGA) sottostante. L'output è corretto; gli avvisi non indicano un problema con il codice.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Questo avviso del Runtime ONNX indica che la libreria non riconosce il SoC ARM per il rilevamento delle funzionalità della CPU. Il sistema torna alle impostazioni predefinite sicure, e l'esecuzione dell'inferenza avviene normalmente. Non è richiesta alcuna azione.

Model '...' not found in catalog
L'SDK recupera il catalogo dei modelli da Internet. Controllare la connessione di rete. Se non viene trovato un alias di modello specifico, eseguire foundry model list per visualizzare gli alias disponibili o esplorare il catalogo completo in foundrylocal.ai/models.

Il modello restituisce contenuto vuoto
Il back-end WinML richiede una GPU con supporto per DirectX 12. Le macchine virtuali senza pass-through GPU restituiscono una risposta positiva con contenuto vuoto. Può essere eseguito su hardware fisico con una GPU discreta o integrata.

• Documentazione locale di Foundry completa - Interfaccia della riga di comando, API REST, Python SDK, gestione dei modelli
• Informazioni di riferimento su Foundry Local C# SDK - Informazioni di riferimento complete sulle API
• Windows ML — porta il tuo modello ONNX con pieno controllo EP
• Scegliere la soluzione di intelligenza artificiale Windows: confrontare tutte le opzioni di intelligenza artificiale Windows