Начало работы с Foundry Local

Foundry Local обеспечивает локальное выполнение больших языковых моделей (LLMs) непосредственно на устройстве Windows, как часть Microsoft Foundry на Windows. Это хорошая альтернатива, если вам нужно углубиться больше, чем API искусственного интеллекта Windows, или необходимо поддерживать оборудование, отличное от Copilot+ ПК. Никаких специальных разрешений или маркеров разблокировки не требуется — он полностью выполняется на вашем собственном оборудовании. Тот же шаблон работает в консольном приложении, приложении WinUI 3, приложении WPF или любом другом узле .NET.

Prerequisites

• Windows 10 сборки 26100 или более поздней версии (рекомендуется Windows 11 24H2 или более поздней версии)
• пакет SDK .NET 9.0 или более поздней версии
• Gpu с поддержкой DirectX 12 (интегрированный или дискретный). Пакет WinML использует аппаратное ускорение и требует наличия реального GPU — виртуальные машины без проброса GPU не поддерживаются.

Установка локального интерфейса командной строки Foundry

Установите CLI с помощью winget:

winget install Microsoft.FoundryLocal

Затем закройте и снова откройте терминал, чтобы foundry команда была включена в PATH. Проверить.

foundry --version

Создание проекта

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Пакет NuGet включает собственные двоичные файлы Windows, поэтому для проекта требуются целевые платформы 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 или ЦП) через среду выполнения 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 и связанные типы, используемые API Foundry Local Chat.

Быстрый старт: запуск модели

Замените содержимое 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;

Псевдонимы модели

Передайте псевдоним модели (не полный идентификатор модели), GetModelAsync чтобы Foundry Local автоматически выбрал лучший вариант — например, вариант NPU QNN на Snapdragon, вариант CUDA на NVIDIA или резервный вариант процессора везде.

Запустите интерфейс командной строки, чтобы просмотреть доступные псевдонимы:

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.

Установите один из следующих вариантов: не устанавливайте оба, так как они имеют конфликтующие 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

Создайте 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, включая настройку поставщика выполнения, обработку ошибок и список моделей, см. в статье Начало работы с Foundry Local в документации Azure AI Foundry.

Использование из приложения 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.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Эти предупреждения появляются после выхода программы и являются доброкачественными. Они поступают из встроенной системы отслеживания ресурсов в базовой библиотеке ONNX Runtime GenAI (OGA). Результат правильный; Предупреждения не указывают на проблему с кодом.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Это предупреждение от ONNX Runtime означает, что библиотека не распознает ваш ARM SoC для определения возможностей ЦП. Он возвращается к безопасным значениям по умолчанию и вывод выполняется нормально. Никаких действий не требуется.

Model '...' not found in catalog
Пакет SDK извлекает каталог моделей из Интернета. Проверьте сетевое подключение. Если псевдоним конкретной модели не найден, выполните команду foundry model list , чтобы просмотреть доступные псевдонимы, или просмотрите полный каталог в foundrylocal.ai/models.

Модель возвращает пустое содержимое
Для серверной части WinML требуется gpu с поддержкой DirectX 12. Виртуальные машины без передачи 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 Local — CLI, REST API, пакет SDK Python, управление моделями
• Справочник по пакету SDK для Local C# Foundry — полный справочник по API
• Windows ML — используйте собственную модель ONNX с полным контролем исполнения EP
• Выберите решение Windows для ИИ — сравните все решения ИИ для Windows.