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

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

Логотипы технологий, связанных с Foundry Local

Note

Полная документация по Foundry Local ( включая ИНТЕРФЕЙС командной строки, управление моделями, необязательный сервер REST, пакет SDK Python и многое другое) поддерживается в документации по Microsoft Foundry. Ссылки на этой странице перенаправляют вас туда, где это необходимо. Используйте кнопку "Назад" в браузере или навигационную цепочку, чтобы в любое время вернуться в документацию Windows по ИИ.

Если вы не уверены, подойдет ли решение Foundry Local для вашего сценария, см. статью Выбор вашего решения ИИ для Windows прежде чем продолжить.

Prerequisites

  • Windows 11 версии 24H2 (сборка 26100) или более поздняя
  • пакет SDK .NET 9.0 или более поздней версии
  • Устройство x64 или Arm64 с достаточной памятью и дисковым пространством для выбранной модели
  • Доступ к Интернету для начального пакета, модели и загрузки компонентов среды выполнения

Пакет SDK Windows может использовать совместимые варианты модели ЦП, GPU и NPU. Выделенный GPU, NPU или Copilot+ PC не требуется, если выбранная модель имеет совместимый вариант ЦП. Доступное ускорение и производительность зависят от вашего устройства, модели и поставщика выполнения.

Note

В этом кратком руководстве используется Phi-4 Mini — на данный момент это новейшая модель Microsoft Phi, доступная через локальный псевдоним Foundry Local phi-4-mini. Алиасы локального каталога Foundry и рекомендуемые модели могут изменяться по мере развития каталога.

Phi-4 Mini отделен от Phi Silica, модель API Windows ИИ, которая поставляется с Windows. Phi Silica остается функцией с ограниченным доступом и требует токен разблокировки. Его планируется заменить на Aion Instruct, для которого не потребуется токен функции ограниченного доступа. Дополнительные сведения о доступе и временной шкале перехода см. в статье "Начало работы с Phi Silica ".

Необязательно. Установка локального интерфейса командной строки Foundry

Рабочий процесс пакета SDK в этом кратком руководстве не требует интерфейса командной строки. Установите его только в том случае, если вы также хотите проверить модели и управлять ими из терминала:

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

Установите текущий стабильный пакет Windows:

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

Пакет включает ChatMessage и связанные типы, используемые собственным API локального чата Foundry Local. Он выбирает совместимый вариант модели для текущего устройства и может использовать поставщики Windows выполнения машинного обучения для аппаратного ускорения.

Note

Если вам нужно использовать платформы, отличные от Windows, используйте вместо этого Microsoft.AI.Foundry.Local. Он обеспечивает тот же интерфейс Foundry Local 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;

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

Передайте псевдоним модели (а не полный идентификатор модели) в GetModelAsync, чтобы Foundry Local мог выбрать совместимый вариант аппаратного обеспечения. В зависимости от модели и устройства, это может быть вариант QNN NPU на Snapdragon, вариант CUDA на NVIDIA или вариант для ЦП.

Если вы установили необязательный интерфейс командной строки, запустите его, чтобы просмотреть доступные псевдонимы:

foundry model list

Например, используйте phi-4-mini для модели Microsoft Phi-4 Mini. Каталог изменяется со временем, поэтому проверьте каталог локальных моделей Foundry для текущих псевдонимов и доступных вариантов.

краткое руководство по 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, чтобы получить локальный пакет SDK Microsoft Foundry.

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

Чтобы ознакомиться с полным пошаговым руководством по созданию приложения, перейдите к руководству по WinUI. Она охватывает явное подтверждение загрузки модели, отслеживание хода выполнения, отмену, специальные возможности и проверку выходных данных.

Добавление локального ИИ в приложение WinUI

Переход на резервный вариант в облаке

Объединяйте 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.

Модель возвращает пустое содержимое
Повторите запрос и убедитесь, что выбранная модель имеет совместимый вариант для устройства. Если проблема продолжается, выберите меньшую модель или вариант ЦП и убедитесь, что устройство имеет достаточно доступной памяти.

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

Затем переустановите нужный объект. Использование виртуальной среды полностью избегает этой проблемы.

  • Last updated on