开始使用 Foundry Local

作为 Microsoft Foundry on Windows 的一部分，Foundry Local 直接在 Windows 设备上实现大型语言模型（LLM）的本地执行。当你需要深入了解 Windows AI API，或需要支持不属于 AI+ PC 硬件时，这是一个很好的替代方案。不需要特殊权限或解锁令牌 - 它完全在自己的硬件上运行。相同的模式适用于控制台应用、WinUI 3 应用、WPF应用或任何其他.NET主机。

与 Foundry Local 关联的技术的徽标

注释

Foundry Local 的完整文档（包括 CLI、模型管理、REST API、Python SDK 等）在 Azure AI Foundry 文档中维护。如果需要，此页面中的链接会带你到那里。使用浏览器的后退按钮或痕迹导航随时返回到 Windows AI 文档。

如果不确定 Foundry Local 是否适合你的方案，请参阅选择你的 Windows AI 解决方案，然后再继续。

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 包，该包通过 ONNX 运行时自动使用最佳可用硬件（Qualcomm NPU、NVIDIA GPU 或 CPU）：

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 包提供由 Foundry 本地聊天 API 使用的 ChatMessage 及相关类型。

注释

如果需要面向非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();
}

流式处理响应

为了在 UI 应用中提供更好的用户体验，请以令牌为单位流式传输响应。此代码片段接续上文的快速入门，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

常见别名：phi-3.5-mini、、 phi-4qwen2.5-0.5b （最小-适用于快速测试）、qwen2.5-7b、 deepseek-r1-7b 完整目录位于 foundrylocal.ai/models。

Python快速入门

Foundry Local 还支持 Python、JavaScript （Node.js）和 Rust。下面是确认模式工作的最小Python示例 - 所有四种语言的完整演练都位于 Azure AI 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

重要

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 started 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 相结合，实现可复原的多层模式。有关完整的可编译示例，请参阅选择您的 Windows AI 解决方案。

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
这些警告在程序退出后显示，是无害的。它们来自底层 ONNX 运行时 GenAI（OGA）库的原生资源跟踪。输出是正确的，警告并不表示你的代码有问题。

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
ONNX 运行时的此警告意味着库无法识别 ARM SoC 进行 CPU 功能检测。它回退到安全默认值，推理正常运行。无需采取任何行动。

Model '...' not found in catalog
SDK 从 Internet 提取模型目录。检查网络连接。如果未找到特定模型别名，请运行 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

然后重新安装你需要的项目。使用虚拟环境可以完全避免此问题。

Full 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