開始使用 Foundry Local

Foundry Local 允許直接在您的Windows裝置上執行大型語言模型（LLM），作為 Microsoft Foundry on Windows 的一部分。當你需要進一步深入探討 Windows AI API，或需要支援不屬於 Copilot+ PC 的硬體時，這是個不錯的替代方案。不需要特殊權限或解鎖代幣——遊戲完全在你自己的硬體上運行。同樣的模式在主控台應用程式、WinUI 3 應用程式、WPF 應用程式或其他任何 .NET 主機上都適用。

與 Foundry Local 相關聯的技術標誌

Note

Foundry Local 的完整文件——包括 CLI、模型管理、REST API、Python SDK 等——都在 Azure AI Foundry 文件中維護。本頁的連結會在需要時帶你前往。您可以隨時使用瀏覽器的返回鍵或麵包屑導航，返回 Windows AI 文件。

如果你不確定 Foundry Local 是否適合你的情境，請參考 Choose your Windows AI solution再繼續。

Prerequisites

Windows 10 版本 26100 或更新版本（建議使用 Windows 11 24H2 或更新版本）
.NET 9.0 SDK 或更新版本
支援 DirectX 12 的 GPU（整合式或獨立式）。此 WinML 套件使用硬體加速，且需要真實的 GPU 硬體——不支援沒有 GPU 直通的虛擬機。

安裝 Foundry 局部指令列介面 (CLI)

使用 winget 安裝 CLI：

winget install Microsoft.FoundryLocal

然後關閉並重新開啟終端機，讓 foundry 指令在你的 PATH 上。請驗證：

foundry --version

建立專案

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

NuGet 套件包含原生 Windows 二進位檔，因此專案需要 Windows 目標框架與執行時識別碼。打開FoundryLocalDemo.csproj並用以下方式替換該區塊：<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>

接著還原以產生新目標的資產檔案：

dotnet restore

安裝 NuGet 封裝

安裝 WinML 套件，該套件會自動使用最佳可用硬體（Qualcomm NPU、NVIDIA GPU 或 CPU），透過 ONNX 執行時：

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

Betalgo.Ranul.OpenAI 套件提供 ChatMessage 和 Foundry 本地聊天 API 使用的相關類型。

Note

如果你需要鎖定非Windows平台，建議改用 Microsoft.AI.Foundry.Local。 API 完全相同;該套件省略了 Windows 專屬的硬體加速。

快速入門：運行模型

將的內容 Program.cs 替換為以下，然後執行 dotnet run。程式會初始化 Foundry Local，當需要時下載模型，執行聊天過程的完成，並進行清理。

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

串流回應

為了提升使用者在應用程式界面中的體驗，可以逐個分詞串流回應。以下片段從上面的快速入門延續而來——chatClient源自第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();

調音產生參數

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

模型別名

傳遞 一個型號別名 （非完整型號 ID）到 Foundry Local，自動選擇最佳硬體變體，例如，Snapdragon 上的 QNN NPU 變體、NVIDIA 的 CUDA 變體，或其他地方的 CPU 備援選項。

執行 CLI 以查看可用的別名：

foundry model list

常見別名： phi-3.5-mini、 phi-4、 qwen2.5-0.5b （最小——適合快速測試）、 qwen2.5-7b、 deepseek-r1-7b。完整目錄請見 foundrylocal.ai/models。

Python 快速入門

Foundry Local 也支援 Python、JavaScript（Node.js）和 Rust。這裡有一個最小Python範例來確認這個模式有效——四種語言的完整攻略都在 Azure AI Foundry docs。

安裝以下 其中一個 ——不要同時安裝，因為它們有相互衝突 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

Important

foundry-local PyPI 上的套件（不含 -sdk）是無關的第三方套件。安裝 foundry-local-sdk 或 foundry-local-sdk-winml 即可取得 Microsoft Foundry 本地 SDK。

創建 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()

執行它：

python app.py

完整Python快速入門指南——包括執行提供者設定、錯誤處理及模型列表——請參見Azure AI Foundry文件中的 Get Start with Foundry Local。

使用 WinUI 3 或 WPF 應用程式

請在App.xaml.cs或App.cs中初始化一次。

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

然後在應用程式裡的任何地方解析 FoundryLocalManager.Instance 。在應用程式的退出處理程序中呼叫Dispose()。

回歸雲端

結合 Foundry Local 與 Windows AI API 並Azure OpenAI，打造具韌性的多層次模式。完整可彙編範例請參見 Choose your Windows AI solution。

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
這些警告會在程式結束後出現，且為良性。它們來自底層的 ONNX 運行時生成人工智慧（OGA）函式庫的原生資源追蹤。你的輸出是正確的;警告並不代表你的程式碼有問題。

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
ONNX 執行時的這個警告表示函式庫無法辨識你的 ARM SoC 來偵測 CPU 功能。它會回復到安全預設，推理也能正常執行。不需採取動作。

Model '...' not found in catalog
SDK 從網路上取得模型目錄。檢查你的網路連線。如果找不到特定的型號別名，請前往 foundry model list 查看可用的別名，或在 foundrylocal.ai/models 瀏覽完整目錄。

模型回傳空白內容
WinML 後端需要支援 DirectX 12 的 GPU。沒有 GPU 直通的虛擬機會回應成功，但內容是空的。在實體硬體上運行，搭配獨立或整合式 GPU。

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
這種 pip 依賴衝突意味著 foundry-local-sdk-winml 和 foundry-local-sdk 都被安裝——它們指定了不同版本的 onnxruntime-core，因此無法共存。卸載一個應用程序：

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

然後重新安裝你想要的那個。使用虛擬環境完全避免了這個問題。

完整 Foundry 本地文件 — CLI、REST API、Python SDK、模型管理
Foundry Local C# SDK 參考 — 完整 API 參考
Windows ML — 帶上你自己的 ONNX 模型，並具備完整的 EP 控制
選擇你的Windows AI解決方案 — 比較所有Windows AI選項

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-11