Foundry Local を始める

Foundry Local を使用すると、Microsoft Foundry on Windowsの一部として、Windows デバイスで大規模な言語モデル (LLM) を直接ローカルで実行できます。 これは、Windows AI API よりも深く進む必要がある場合や、Copilot+ PCではないハードウェアをサポートする必要がある場合に適した代替手段です。 特別なアクセス許可やロック解除トークンは必要ありません。完全に独自のハードウェアで実行されます。 コンソール アプリ、WinUI 3 アプリ、WPF アプリ、またはその他の.NET ホストでも、同じパターンが機能します。

Prerequisites

• ビルド 26100 以降Windows 10 (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 パッケージのインストール

ONNX ランタイムを介して最適なハードウェア (Qualcomm NPU、NVIDIA GPU、または CPU) を自動的に使用する WinML パッケージをインストールします。

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 Local チャット API で使用されるChatMessageと関連する種類が用意されています。

クイック スタート: モデルを実行する

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-4、 qwen2.5-7b、 deepseek-r1-7b。 完全なカタログは foundrylocal.ai/models にあります。

WinUI 3 または WPF アプリから使用する

App.xaml.csまたはApp.csで 1 回初期化します。

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 Runtime GenAI (OGA) ライブラリのネイティブ リソース追跡から取得されます。 出力は正しいです。警告はコードに問題があることを示していません。

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
ONNX ランタイムからのこの警告は、ライブラリが CPU 機能検出のために ARM SoC を認識しないことを意味します。 これは安全な既定値にフォールバックし、推論は通常どおり実行されます。 アクションは必要ありません。

Model '...' not found in catalog
SDK は、インターネットからモデル カタログを取得します。 ネットワーク接続を確認します。 特定のモデル エイリアスが見つからない場合は、 foundry model list 実行して使用可能なエイリアスを表示するか、 foundrylocal.ai/models で完全なカタログを参照します。

モデルから空のコンテンツが返される
WinML バックエンドには、DirectX 12 対応 GPU が必要です。 GPU パススルーのない仮想マシンは、空のコンテンツを含む正常な応答を返します。 ディスクリート GPU または統合 GPU を使用して物理ハードウェア上で実行します。

• Full Foundry Local のドキュメント — CLI、REST API、Python SDK、モデル管理
• Foundry Local C# SDK リファレンス — 完全な API リファレンス
• Windows ML - 完全な EP コントロールを備えた独自の ONNX モデルを使用します
• Windows AI ソリューションの選択 — すべてのWindows AI オプションを比較します