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. L'SDK nativo viene eseguito nel processo dell'app e non richiede l'interfaccia della riga di comando locale foundry o un server REST locale separato. 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 11 versione 24H2 (build 26100) o successiva
• .NET 9.0 SDK o versione successiva
• Un dispositivo x64 o Arm64 con memoria e spazio su disco sufficiente per il modello selezionato
• Accesso a Internet per il pacchetto iniziale, il modello e i download dei componenti di runtime

L'SDK di Windows può usare varianti di modello di CPU, GPU e NPU compatibili. Una GPU dedicata, una NPU o Copilot+ PC non è necessaria quando il modello selezionato ha una variante della CPU compatibile. L'accelerazione e le prestazioni disponibili dipendono dal dispositivo, dal modello e dal provider di esecuzione.

Facoltativo: installare la CLI locale di Foundry

Il flusso di lavoro dell'SDK in questa guida rapida non richiede la CLI. Installarlo solo se si vuole controllare e gestire i modelli da un terminale:

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 di Windows stabile corrente:

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

Il pacchetto include i ChatMessage tipi correlati e usati dall'API di chat nativa di Foundry Local. Seleziona una variante del modello compatibile per il dispositivo corrente e può usare i provider di esecuzione di Windows ML per l'accelerazione hardware.

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

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 possa selezionare una variante hardware compatibile. A seconda del modello e del dispositivo, può trattarsi di una variante QNN per NPU su Snapdragon, di una variante CUDA su NVIDIA o di una variante per CPU.

Se hai installato la CLI opzionale, eseguila per visualizzare gli alias disponibili:

foundry model list

Ad esempio, usare phi-4-mini per il modello Microsoft Phi-4 Mini. Il catalogo cambia nel tempo, quindi consulta il catalogo dei modelli di Foundry Local per gli alias attuali e le varianti disponibili.

Python avvio rapido

Foundry Local supporta anche Python, JavaScript (Node.js) e Rust. Ecco l'esempio minimo Python per confermare il funzionamento del modello. La procedura dettagliata completa per tutte e quattro le lingue è disponibile nella documentazione di Microsoft Foundry.

Installare una delle opzioni seguenti: non installare entrambe, perché presentano dipendenze in conflitto onnxruntime-core :

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

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

Eseguilo:

python app.py

Per la guida introduttiva completa Python, inclusa la configurazione del provider di esecuzione, la gestione degli errori e l'elenco di modelli, vedere Introduzione a Foundry Local nella documentazione di Microsoft Foundry.

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.

Per una guida completa dell'applicazione, prosegui con l'esercitazione su WinUI. Copre il consenso esplicito al download dei modelli, l'avanzamento, l'annullamento, l'accessibilità e la revisione dei risultati.

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
Provare di nuovo la richiesta e verificare che il modello selezionato abbia una variante compatibile per il dispositivo. Se il problema persiste, selezionare un modello più piccolo o una variante della CPU e verificare che il dispositivo disponga di memoria disponibile sufficiente.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Questo conflitto di dipendenza pip significa che sia foundry-local-sdk-winml sia foundry-local-sdk sono installati — essi fissano versioni diverse di onnxruntime-core e non possono coesistere. Disinstalla uno:

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

Reinstallare quindi quello desiderato. L'uso di un ambiente virtuale evita completamente questo problema.

• Documentazione locale di Foundry completa - Interfaccia della riga di comando, API REST, Python SDK, gestione dei modelli
• Informazioni di riferimento su Foundry Local SDK - Guida alla configurazione e all'API dell'SDK
• 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