開始使用 Foundry Local

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

與 Foundry Local 相關聯的技術標誌

Note

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

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

Prerequisites

Windows 11，版本 24H2（版本 26100）或更新版本
.NET 9.0 SDK 或更新版本
一台 x64 或 Arm64 裝置，具備足夠的記憶體與磁碟空間，以容納你所選的模型
初始套件、模型及執行時元件下載的網際網路存取

Windows SDK 可使用相容的 CPU、GPU 與 NPU 型號變體。當所選型號有相容的 CPU 變體時，則不需要專用的 GPU、NPU 或 Copilot+ PC。可用的加速與效能取決於您的裝置、型號及執行提供者。

Note

本快速入門使用 Phi-4 Mini，這是目前可透過 Foundry Local 別名 phi-4-mini 取得的最新 Microsoft Phi 模型。 Foundry Local 目錄別名及推薦型號會隨著目錄演進而變動。

Phi-4 Mini 與 Windows 內建的 Windows AI API 模型 Phi Silica 是分開的。 Phi Silica 仍屬有限存取功能，且需解鎖代幣。它預計會被 Aion Ininstruction 取代，後者不需要有限存取功能（Limited Access Feature）代幣。請參閱「與 Phi Silica 開始」一節，了解存取詳情及過渡時間表。

可選：安裝 Foundry 本地 CLI

這個快速入門的 SDK 工作流程不需要 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 封裝

安裝目前穩定的 Windows 套件：

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

該套件包含供 Foundry Local 原生聊天 API 使用的 ChatMessage 及相關類型。它會為目前裝置選擇相容的型號變體，並可使用 Windows ML 執行工具進行硬體加速。

Note

如果你需要鎖定非Windows平台，建議改用 Microsoft.AI.Foundry.Local。它提供相同的 Foundry 本地 API 表面，但沒有 Windows ML 整合。

上述指令是安裝目前穩定套件。 WinUI 教學使用 .NET 10，並釘選套件版本，讓你能重現完整的攻略。

快速入門：運行模型

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

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

串流回應

為了提升使用者在應用程式界面中的體驗，可以逐個分詞串流回應。以下片段從上面的快速入門延續而來——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）到， GetModelAsync 讓 Foundry Local 能選擇相容的硬體變體。根據型號與裝置不同，這可能是 Snapdragon 的 QNN NPU 變體、NVIDIA 的 CUDA 變體，或是 CPU 變體。

如果你安裝了可選的 CLI，請執行它以查看可用的別名：

foundry model list

例如，Microsoft Phi-4 Mini 模型使用 phi-4-mini。目錄會隨時間變動，請參考 Foundry Local 型號目錄，了解目前的別名和可用變體。

Python 快速入門

Foundry Local 也支援 Python、JavaScript（Node.js）和 Rust。這裡有一個簡短的 Python 範例來確認這個模式可行——完整的四種語言攻略都在 Microsoft Foundry 文件中。

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

執行它：

python app.py

完整的 Python 快速入門指南——包括執行提供者設定、錯誤處理及模型列表——請參閱 Microsoft Foundry 文件中的「從 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()。

想完整了解應用程式攻略，請繼續閱讀 WinUI 教學。它涵蓋明確的模型下載同意、進度、取消、無障礙及輸出審查。

在 WinUI 應用程式中加入本地 AI

回歸雲端

結合 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 瀏覽完整目錄。

模型回傳空白內容
請再試一次請求，確認所選型號是否有相容的裝置版本。如果問題持續，請選擇較小的型號或 CPU 變體，並檢查裝置是否有足夠的可用記憶體。

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 SDK 參考 — SDK 設定與 API 指引
Windows ML — 帶上你自己的 ONNX 模型，並具備完整的 EP 控制
選擇你的Windows AI解決方案 — 比較所有Windows AI選項

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-22

開始使用 Foundry Local

Prerequisites

可選：安裝 Foundry 本地 CLI

建立專案

安裝 NuGet 封裝

快速入門：運行模型

串流回應

調音產生參數

模型別名

Python 快速入門

使用 WinUI 3 或 WPF 應用程式

回歸雲端

Troubleshooting

意見反應

其他資源