开始使用 Foundry Local

作为 Microsoft Foundry on Windows 的一部分,Foundry Local 直接在 Windows 设备上实现大型语言模型(LLM)的本地执行。 当你需要比 Windows AI API 更深入的了解,或者需要支持 AI+ PC 以外的其他硬件时,这是一个很好的替代方案。 无需特殊权限或解锁令牌。 原生 SDK 在应用进程中运行,不需要 Foundry Local CLI 或单独部署的本地 REST 服务器。 相同的模式适用于控制台应用、WinUI 3 应用、WPF应用或任何其他.NET主机。

与 Foundry Local 关联的技术的徽标

注释

Foundry Local 的完整文档(包括 CLI、模型管理、可选的 REST 服务器、Python SDK 等)保留在 Microsoft Foundry 文档中。 如果需要,此页面中的链接会带你到那里。 使用浏览器的后退按钮或痕迹导航随时返回到 Windows AI 文档。

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

Prerequisites

  • Windows 11 版本 24H2(内部版本 26100)或更高版本
  • .NET 9.0 SDK 或更高版本
  • 具有足够内存和磁盘空间以运行所选模型的 x64 或 Arm64 设备
  • 首次下载包、模型和运行时组件时所需的互联网访问权限

Windows SDK 可以使用兼容的 CPU、GPU 和 NPU 模型变体。 当所选模型具有兼容的 CPU 变体时,不需要专用 GPU、NPU 或AI+ PC。 可用的加速和性能取决于设备、模型和执行提供程序。

注释

本快速入门使用 Phi-4 Mini,这是目前可通过 Foundry Local 别名使用的最新 Microsoft Phi 模型phi-4-mini。 随着目录的发展,Foundry Local 目录别名和建议的模型可能会更改。

Phi-4 Mini 与 Phi Silica 是不同的,后者是随 Windows 一起提供的 Windows AI API 模型。 Phi 硅仍然是受限访问功能,需要解锁令牌。 预计它将由 Aion Instruct 取代,后者将无需有限访问功能令牌。 有关访问详细信息和过渡时间线,请参阅 Phi 硅入门 。

可选:安装 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 执行提供程序进行硬件加速。

注释

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

流式响应

为了在 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

例如,对 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

重要

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 教程。 它涵盖显式模型下载同意、进度、取消、辅助功能和输出评审。

切换到云端

将 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 浏览完整目录。

模型返回空内容
再次尝试该请求,并确认所选模型具有适用于设备的兼容变体。 如果问题仍然存在,请选择较小的模型或 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

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