Foundry Localの使い方｜CLI 0.12の新コマンド・SDK v2のChatSession・対応モデル一覧【2026年11月】

Foundry Localは、モデルの取得から推論までを利用者の端末内で完結させるMicrosoftのローカルAI実行基盤です。2026年4月9日のGA後も更新が速く、6月にCLIが作り直され、9月にはSDKがv2へ上がりました。そのため、GA直後の手順どおりにfoundry model runと打っても、現行のCLI 0.12.1ではエラーになります。この記事では、2026年11月1日時点の最新版であるCLI 0.12.1と、Python SDK 2.3.0・2.2.1、C# SDK 2.2.1をLinux x64環境で実際に動かしました。その結果をもとに、インストール、新しいコマンド、対応モデル、PythonとC#の実装、OpenAI互換APIの使い方をまとめます。

まとめ：Foundry Localの要点（2026年11月時点）

• 最新版：GitHub Releasesの最新はv2.2.1とCLI 0.12.1 Preview（ともに2026年10月23日）。各言語のSDKパッケージは10月31日に2.3.0が公開された。対応OSはWindows・macOS（Appleシリコン）・Linux（x64／ARM64）。
• コマンドの変更：foundry model runはfoundry runに、foundry serviceはfoundry serverに置き換わった。--filterも廃止され、--device・--type・--searchで絞り込む。
• SDKの変更：v2ではChatSessionが標準になった。旧来のget_chat_client()は2026年末に削除される予定で、Windows ML版の別パッケージも標準パッケージに統合された。
• モデル：Linux x64のCPU環境では56モデルが表示され、Gemma 4（gemma-4-e2b-it）、Qwen3、gpt-oss-20b、Whisper、埋め込みモデルが使える。
• 向き不向き：アプリに同梱して1人の利用者の端末で動かす用途向け。多人数が同時に使うサーバー推論や、GGUF形式のモデルを使いたい場合は別のツールを選ぶ。

Foundry Localとは：アプリに同梱するローカルAI実行基盤

ランタイム・SDK・モデルカタログの3点構成

Foundry Localは、推論ランタイム、各言語のSDK、厳選されたモデルカタログの3つで構成されています。推論にはONNX Runtimeを使い、Microsoft Learnの製品概要によると、アプリのパッケージに加わるのは約20MBです。SDKはPython・JavaScript・C#・Rust・C・C++の6言語です。v2では各言語のSDKが共通のネイティブライブラリ（Linuxではlibfoundry_local.so、Windowsではfoundry_local.dll）をアプリのプロセス内に読み込んで推論する形に統一されました。

Azureのサブスクリプションは不要で、トークン単位の課金もありません。推論そのものは端末内で完結し、プロンプトと応答は外部に送られません。一方で通信がゼロになるわけではなく、モデルや実行プロバイダー（EP）のダウンロードと更新のほか、公式リポジトリのREADMEによると利用状況のデータをMicrosoftに送ることがあります。LICENSEではSDKにMITライセンスが、CLIには別のMicrosoftのライセンス条項が適用されるとされ、モデルにはそれぞれのライセンスが付きます。foundry model info qwen3-0.6bを実行するとLicense欄にapache-2.0と表示されるので、商用で使う前にモデルごとに確認してください。

Microsoft FoundryやFoundry Local on Azure Localとの違い

名前が似た製品が2つあります。クラウドでモデルやエージェントを運用するMicrosoft Foundryは、Azure上のサービスで、Foundry Localとは別物です。もう1つのFoundry Local on Azure Localは、Azure Arcに対応したKubernetesクラスターに拡張機能として入れる製品で、2026年11月時点でもプレビューです。利用者のPCにAIを同梱して配るならFoundry Local、自社のサーバー基盤で推論を動かすならAzure Local版、と覚えておけば取り違えません。

GA後の変更点：GA直後の手順が今は動かない理由

GA（v1.0.0）から半年で、CLIとSDKの両方に互換性のない変更が入りました。2026年5月ごろまでのブログ記事や書籍の手順がそのままでは動かないのはこのためです。主な変更をGitHub Releasesから日付順に並べます。

旧コマンドと新コマンドの対応表

CLI 0.10.0のリリースノートは、旧来のサービス型CLIを置き換えたと明記しています。CLI 0.12.1で旧コマンドを打つと、● error: Unrecognized command or argument 'run'.のようにエラーで止まります。--filterも同様にUnrecognized command or argument '--filter'.と返されました。

インストールと最初のモデル実行（Windows・macOS・Linux）

winget・Homebrew・tar.gzでの導入

Windowsはwinget、macOSはHomebrewで入れます。どちらも配布元のマニフェストは2026年11月1日時点でCLI 0.12.1を指しています。macOSのHomebrew版はAppleシリコンとmacOS Sequoia以降が条件で、Intel Macには対応していません。

# Windows
winget install Microsoft.FoundryLocal

# macOS（Appleシリコン）
brew tap microsoft/foundrylocal
brew install foundrylocal

Linuxは、CLI 0.12.1のリリースページからtar.gzを取得します。同梱のinstall.shを実行すると/usr/local/bin/foundryにリンクが作られます。リリースノートには展開した./lib/foundryを直接実行する手順も載っています。しかし、0.12.1のtar.gzに入っているlib/foundryには実行権限が付いておらず（tar tvzfで-rw-r--r--）、そのまま実行するとPermission deniedになりました。install.shは実行権限を付けてから配置するので、こちらを使うのが確実です。

tar xzf foundry-0.12.1-linux-x64.tar.gz
sudo bash foundry-0.12.1-linux-x64/install.sh
foundry --version   # 0.12.1

Linuxの条件は、Python SDKのREADMEによるとx64でglibc 2.28以上、ARM64でglibc 2.34以上です。ただし公式資料にない落とし穴もあります。Debian 13ベースのpython:3.12-slimイメージでは、SDKを初期化した時点でOSError: libatomic.so.1: cannot open shared object fileが出て止まりました。apt-get install libatomic1で解消します。軽量なコンテナイメージに組み込む場合は、最初にこのパッケージを入れておいてください。

foundry run・foundry chatでのモデル実行

現行CLIでは、foundry runがモデルの種類を見て、チャットか文字起こしかを自動で振り分けます。初回はモデルのダウンロードから始まります。

foundry status                 # OS・CPU・GPU・SDK版・接続状態を一覧
foundry run qwen3-0.6b         # チャットモデルを対話で実行
foundry chat qwen3-0.6b -s "日本語で簡潔に答える" -t 0.2 -m 512
foundry transcribe -m whisper-tiny -f audio.wav

foundry chatでは、-sでシステムプロンプト、-tで温度（0.0〜1.0）、-mで1回の応答の最大トークン数を指定できます。画像を読めるモデルなら--imageで画像も渡せます。foundry statusの表には、SDKとランタイムの版（2.2.1）、ONNX Runtime 1.31.0、ONNX Runtime GenAI 0.18.0、ローカルサービスのURLが表示されます。不具合を報告するときはこの表を添えると話が早く進みます。ほとんどのコマンドに--output jsonを付けられるので、スクリプトから状態を調べるときはそちらを使います。

foundry model listの絞り込みとキャッシュ管理

foundry model list --type chat --device cpu --search qwen3 --limit 6
foundry model list --type embedding
foundry model list --cached
foundry model info gemma-4-e2b-it   # バリアント・サイズ・ライセンス・ツール対応
foundry cache list
foundry cache location
foundry cache remove qwen3-0.6b

--typeにはchat・speech・embeddingを指定します。--variantsを付けると、デバイスごとのバリアントが1行ずつ表示されます。一覧のTools列は、そのモデルがツール呼び出し（function calling）に対応しているかを示します。キャッシュの保存先はfoundry cache cd <path>で変更できます。

対応モデル一覧（catalog v2・2026年11月時点）

CLIとSDKがモデルを取得するカタログは、v2.2.1から「catalog v2」に変わりました。下の表は、Linux x64・GPUなしの環境でSDKのcatalog.list_models()が返した56モデルをファミリー別にまとめたものです。GPUやNPUを積んだWindows機では、表示されるバリアントの構成が変わります。

Gemma 4 E2Bの対応状況とサイズの制限

「foundry local gemma」で検索する人は多いものの、GA直後のカタログにGemmaはありませんでした。2026年11月時点のカタログにはgemma-4-e2b-itが入っています。foundry model list --search gemmaで調べると、種別はMultimodal、CPU版は5.9GB、ツール呼び出しにも対応と表示されました。ただし用意されているのはE2Bの1サイズだけです。Gemma 4の他のサイズを使いたい場合は、LM StudioなどGGUF形式のモデルを扱えるツールを選ぶことになります。

エイリアス・モデルID・バリアントの関係

qwen3-0.6bはエイリアスで、端末に合わせてバリアントが自動で選ばれます。GPUのないLinux環境ではqwen3-0.6b-generic-cpu:4が選ばれました。末尾の:4はカタログ上の版番号です。CLIとSDKはエイリアスで指定できます。一方、OpenAI互換のREST APIではエイリアスを受け付けません。model="qwen3-0.6b"で呼ぶと404 - Model not found: No model matching 'qwen3-0.6b'が返り、モデルIDで指定すると応答が返りました。IDは/v1/modelsで確認できます。

実行プロバイダー（EP）とGPU・NPUの動作条件

自動選択の仕組みと内蔵EP

v2.0.1のリリースノートによると、v2のパッケージは端末のハードウェアを調べて、WinML・WebGPU・CPU・CUDAの中から自動でEPを選びます。CPUとWebGPUはWindows・Linux・macOSのすべてで、CUDAはWindowsとLinuxで使えます。GPUのないLinuxコンテナではdiscover_eps()が空のリストを返し、推論はCPUで実行されました。

Windowsのプラグイン EPと対応チップ

Windowsでは、端末に合うベンダー別のEPが初回の実行時にダウンロードされます。CLIリファレンスに載っている条件は次のとおりです。

「No registered plugin EP device found for CUDAExecutionProvider」の対処

このメッセージはONNX Runtimeが出す警告で、指定されたEPに対応するデバイスが登録されていないことを示します。v2.2.1以降でまず確認したいのは、CUDAの実行環境が入っているかどうかです。v2.2.1からCUDAの実行環境が同梱されなくなりました。v2.2.1のリリースノートは、CUDAとcuDNNを別に入れるよう求めています。x64ではCUDA 12とcuDNN 9、ARM64ではCUDA 13とcuDNN 9です。導入後、WindowsではDLLのフォルダをPATHに、LinuxではLD_LIBRARY_PATHなどの検索パスに加えます。そのうえで新しいターミナルからfoundry server restartを実行してください。自作のWindows x64アプリではPATHの設定だけでは足りず、EPを登録する前にAddDllDirectoryでCUDAのフォルダを追加する必要があります。

SDK v2でのアプリ組み込み（Python・C#）

パッケージと対応バージョン

表の最新版は2026年11月1日に各レジストリで確認した値です。2.3.0はパッケージだけが先に公開され、GitHub Releasesのリリースノートはまだありません（C／C++向けのRuntimeパッケージは2.2.1のまま）。Windows ML版のfoundry-local-sdk-winmlとMicrosoft.AI.Foundry.Local.WinMLは1.2.4で更新が止まっています。v2ではWindows ML対応が標準パッケージに含まれるため、移行するときは-winml付きのパッケージを外します。Pythonのimport名はfoundry_local_sdkです。No module named 'foundry_local_sdk'が出たら、pip install foundry-local-sdkを実行したPython環境と、スクリプトを実行しているPython環境が同じかを確認してください。

PythonのChatSessionでのストリーミング応答

v2の推論は、モデル、セッション、リクエスト、応答の順に組み立てます。次のコードは、python:3.12-slimにfoundry-local-sdk 2.2.1と2.3.0をそれぞれ入れた環境で動作を確認したものです。ChatSessionは会話の履歴を内部に保持するため、2回目のリクエストに追加の発言を1つ渡すだけで前の会話を踏まえた応答が返り、turn_countは2になりました。

from foundry_local_sdk import (
    ChatSession, Configuration, FoundryLocalManager,
    MessageItem, Request, RequestOptions, SearchOptions,
    TextItem, TextItemType,
)

FoundryLocalManager.initialize(Configuration(app_name="issoh_sample"))
manager = FoundryLocalManager.instance

model = manager.catalog.get_model("qwen2.5-0.5b")
model.download()
model.load()

def ask(session, text):
    with Request().add_item(MessageItem.user(text)) as req:
        for item in session.process_streaming_request(req):
            # 推論過程（reasoning）を除き、本文のテキストだけ表示する
            if isinstance(item, TextItem) and item.type == TextItemType.DEFAULT:
                print(item.text, end="", flush=True)
    print()

try:
    with ChatSession(model) as session:
        session.set_options(RequestOptions(
            search=SearchOptions(temperature=0, max_output_tokens=128)))
        session.set_streaming(True)
        ask(session, "黄金比とは何ですか？一文で。")
        ask(session, "その値は？")   # 前の質問を覚えている
        print("turn_count =", session.turn_count)
finally:
    model.unload()

Windowsで、ベンダー別のEPを使ってGPUやNPUで推論したい場合は、モデルを取得する前にmanager.download_and_register_eps()を呼びます。今回の検証では、qwen2.5-0.5bが黄金比の値を「2.372051」と答えるなど、0.5Bのモデルは事実を誤りました。業務で日本語の応答品質が必要なら、qwen3-4bやphi-4-mini以上を試してください。

C#の実装とセッションを破棄する順序

C#もPythonと同じ流れで書きます。dotnet new consoleで作ったプロジェクト（暗黙的なusingが有効な既定の設定）にdotnet add package Microsoft.AI.Foundry.Localでパッケージを追加して使います。.NET 8のLinuxコンテナで検証したときは、ビルドがNETSDK1047（復元したアセットにnet8.0/linux-x64向けの対象がない）で止まりました。csprojに<RuntimeIdentifier>linux-x64</RuntimeIdentifier>を書くか、dotnet run -r linux-x64のように実行環境を指定して復元し直すと解消します。

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging.Abstractions;

await FoundryLocalManager.CreateAsync(
    new Configuration { AppName = "issoh_sample" }, NullLogger.Instance);
using var manager = FoundryLocalManager.Instance;

var catalog = await manager.GetCatalogAsync();
var model = await catalog.GetModelAsync("qwen2.5-0.5b")
            ?? throw new Exception("Model not found");
await model.DownloadAsync();
await model.LoadAsync();

// セッションはUnloadAsyncより前に破棄する
using (var session = new ChatSession(model))
using (var request = new Request())
{
    request.AddItem(MessageItem.User("日本の首都は？一言で。"));
    using var response = await session.ProcessRequestAsync(request);
    var text = string.Concat(response
        .OfType<MessageItem>()
        .SelectMany(m => m.Parts)
        .OfType<TextItem>()
        .Where(t => t.Type == TextItemType.Default)
        .Select(t => t.Text));
    Console.WriteLine(text);
}

await model.UnloadAsync();

注意したいのが破棄の順序です。using var sessionで宣言したまま同じスコープでUnloadAsync()を呼ぶと、cannot unload model 'qwen2.5-0.5b-instruct-generic-cpu:4': 1 session(s) still using itというFoundryLocalExceptionが出て、プロセスが異常終了しました。上のコードのように、セッションをブロックで囲んで先に閉じてからアンロードしてください。

旧ChatClient（get_chat_client）からの移行

v1系の書き方であるmodel.get_chat_client()とcomplete_streaming_chat()はv2でも動きます。ただし、実行するとDeprecationWarning: The OpenAI direct client is deprecated and will be removed at the end of 2026; use ChatSession.という警告が出ます。2027年以降もSDKを更新し続けるアプリは、今のうちに書き換えておくべきです。

OpenAI互換APIでの接続（既存アプリ・Open WebUI・LangChain）

既にOpenAI SDKで書いたアプリを動かしたい場合や、LangChainと組み合わせたい場合は、ローカルのWebサービスを起動してOpenAI互換のエンドポイントを使います。ポートを指定しないとOSが空いている番号を割り当てるため、URLはfoundry server statusで確認します。接続先を固定したい場合はfoundry server start --port 5273のように番号を指定します（起動済みならfoundry server restart --port 5273）。

foundry server start
foundry server status        # Web URLs http://127.0.0.1:38195 など
curl http://127.0.0.1:38195/v1/models

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:38195/v1", api_key="notneeded")
r = client.chat.completions.create(
    model="qwen3-0.6b-generic-cpu:4",   # エイリアスでは404になる
    messages=[{"role": "user", "content": "日本の首都は？一言で。"}],
    max_tokens=300,
)
print(r.choices[0].message.content)
print(r.usage.completion_tokens_details.reasoning_tokens)

Qwen3のような推論型のモデルでは、考える過程のトークンが応答とは別に数えられます。実測では、completion_tokens106のうち75がreasoning_tokensでした。max_tokensを小さくしすぎると、本文を出す前に上限に達するので注意してください。SDKからWebサービスを起動する場合は、manager.start_web_service()を呼び、manager.urls[0]に/v1を付けたURLをbase_urlにします（公式のPythonサンプルと同じ方法です）。HTTP側では/v1/chat/completionsのほかに/v1/responses・/v1/embeddings・/v1/audio/transcriptionsも使えます。ただしHTTP側は会話の状態を持たないため、会話の履歴は毎回送ります。ブラウザでチャット画面を使いたい場合は、このURLをOpen WebUIに接続先として登録します。

OllamaやLM Studioとの使い分け

使い分けは「アプリに入れて配るか、手元で試すか」で決まります。Foundry Localはモデルを厳選し、端末に合うバリアントの選択とEPの更新を自動で行うので、利用者のPCの違いをアプリ側で吸収できます。一方、Ollamaは幅広いモデルを手早く試すのに向いています。

v2.1.0で追加されたBYOMを使えば、カタログにないモデルも登録できます。ただし対象はONNX Runtime GenAI形式のフォルダに限られ、CLIではfoundry model register <path> <model-id>で登録します。手元のGGUFファイルをそのまま使いたいならOllamaやLM Studioを選びましょう。コーディングエージェントをローカルのモデルで動かす構成は、OllamaでCodexを動かす手順で解説しています。

採用を避けるべき場面と代わりの選択肢

次の条件に当てはまる場合は、Foundry Localを選ばないほうが無難です。

• 複数の利用者が同時に使うサーバー推論：公式FAQは、同時リクエストのキューイングや連続バッチングを提供しないと明言しています。この用途ではvLLMやTriton Inference Serverを使います。
• Intel Macで動かしたい：macOS版はAppleシリコン専用です。Intel MacならLinuxのVMかコンテナで動かすことになり、GPUは使えません。Appleシリコン向けに作られた別の実行環境としてMLXも比較候補になります。
• CLIの出力に依存する運用スクリプト：CLIは0.12.1でもPreviewで、0.10から0.12の間だけでもコマンドと引数が変わりました。本番ではSDKの版を固定し、CLIは試験用にとどめます。
• 端末のメモリに載らないモデルを使いたい：カタログで最大級はgpt-oss-20b（CPU版12.5GB）です。BYOMで登録できるのもONNX Runtime GenAI形式のモデルに限られ、利用者の端末のメモリに収まる必要があります。それを超える規模のモデルは、vLLMなどのサーバー推論かクラウドのAPIを使います。

社内のPCや現場の端末に生成AIを組み込みたい場合、どのモデルでどこまで任せられるかは業務データで検証しないと決まりません。モデル選定から組み込みまで相談したい場合は、生成AI導入支援で検証の段取りからお手伝いしています。

よくある質問

Foundry Localは無料で使えますか？

無料です。Azureのサブスクリプションは不要で、トークン単位の課金もありません。SDKはMITライセンスです。ただし、CLIにはMicrosoftの別のライセンス条項が、各モデルにはそれぞれのライセンスが適用されます。商用で使う前にfoundry model info <alias>でライセンスを確認してください。

foundry model runやfoundry service statusが動かないのはなぜですか？

CLI 0.10.0（2026年6月4日）以降、これらのコマンドが廃止されたためです。foundry runとfoundry server statusを使ってください。一覧の--filterも廃止され、--device・--type・--searchに置き換わりました。

Gemmaは使えますか？

使えます。2026年11月時点のカタログにはgemma-4-e2b-it（画像とテキストを扱うE2Bサイズ・CPU版5.9GB）が入っており、foundry run gemma-4-e2b-itで実行できます。ほかのサイズのGemma 4はカタログにありません。

GUIで使う方法はありますか？

Foundry Local本体には専用のGUIがありません。Foundry Toolkit for VS Codeを使うと、Windows（x64／ARM64）とmacOS（Appleシリコン）で、Foundry Localのモデルをダウンロードし、Playgroundで試せます。ブラウザで使いたい場合は、ローカルのWebサービスにOpen WebUIを接続します。

LinuxやIntel Macでも使えますか？

Linuxは、x64（glibc 2.28以上）とARM64（glibc 2.34以上）に対応しています。macOSはAppleシリコン専用で、Intel Macには対応していません。軽量なDebian系イメージで使う場合は、libatomic1を先に入れておかないとSDKの初期化で止まります。

関連記事

• ONNXとは？読み方・.onnxファイルの中身・変換とONNX Runtimeでの推論【onnx 1.23／ORT 1.31対応】
• Microsoft Foundryとは？できること・料金の仕組み・始め方【2026年10月】
• Open WebUIとは｜使い方・インストール・APIキー発行をv0.12.0で実測解説
• LM StudioのMCP設定とGemma 4のMTP設定｜mcp.json・Web検索・動かない時の対処【2026年10月】
• MLXとは？mlx-lmの使い方｜生成・量子化・サーバ・LoRAの手順とApple Siliconでの採用判断【2026年10月】