Foundry Localを実機で試してみた！インストールからCLI・Python SDK実行まで、エラー対処も全部まとめ

こんにちは！横浜情報機器株式会社のShahinです！
今回はMicrosoftの Foundry Local をWindows（Snapdragon X搭載PC）で実際に動かしてみた検証記事をご紹介します。
クラウド不要・Azureサブスクリプション不要でAIモデルがローカルで動くという点に注目し、実機で検証しました。
途中でサービス未起動やカタログエラーなど詰まりポイントもありましたが、トラブルシューティングも含めてすべてまとめています。ぜひ最後まで読んでみてください。

Foundry Localって何？

Foundry Local は、AIモデルをユーザーのデバイス上で完全に動かすための、MicrosoftのエンドツーエンドなローカルAIソリューションです。

SDKはC#・JavaScript・Python・Rustに対応しており、モデルの取得からハードウェアアクセラレーション、推論まで一括で処理できます。ランタイム本体のサイズが約20MBと軽量なため、アプリへの組み込みも現実的です。

ポイント：Azureサブスクリプション不要です。プロンプトもレスポンスもデバイス外に出ません。オフラインでも動作します。

クラウドAIとの違い

Foundry Local とクラウドAIの主な違いを以下の表で確認します。

項目	クラウドAI	Foundry Local（オンデバイス）
データの場所	クラウドサーバーに送信	デバイス外に出ない
オフライン動作	❌ 不可	✅ 可能
レイテンシ	ネットワーク遅延あり	ゼロ（ローカル処理）
コスト	トークン従量課金	無料（ハードウェアのみ）
Azureサブスクリプション	必要	不要

個人情報や機密データを扱うアプリ、ネット環境が不安定な現場で使うツール、リアルタイムに近い応答が必要なケースで特に有効です。

インストール手順（Windows / winget）

今回の検証環境はWindows + Snapdragon X（QNN/NPU搭載）のCopilot+ PCを使用します。

ステップ1：コマンドプロンプトを起動する

スタートメニューを開き、検索バーに「Terminal」または「コマンドプロンプト」と入力して起動します。

ステップ2：wingetでインストールする

以下のコマンドを実行してFoundry Localをインストールします。

winget install Microsoft.FoundryLocal

インストールが開始されます。完了まで数分かかる場合があります。

ステップ3：インストールを確認する

インストール完了後、以下のコマンドでバージョンを確認します。

foundry --version

バージョン 0.8.119 が表示されればインストール成功です。

ステップ4：サービス状態を確認する

次のコマンドでFoundryのバックグラウンドサービスが起動しているか確認します。

foundry service status

インストール直後のトラブルシューティング

インストール直後にいくつかエラーが発生しました。同じ状況になった場合の参考にしていただければ幸いです。

エラー①：サービスが起動していない場合

サービスが停止している場合は、以下のコマンドで再起動します。

原因と対処：インストール直後はFoundryのバックグラウンドサービスが自動起動していない場合があります。foundry service restart を実行して解決します。

foundry service restart

🟢 が表示されれば、サービスが http://127.0.0.1:62322/ で起動しています。次にモデル一覧を確認します。

エラー②：model list でカタログ取得に失敗する場合

初回に foundry model list を実行したところ、QNNExecutionProviderのダウンロード・登録は成功したものの、モデル一覧の取得でエラーが発生しました。

対処法：カタログが取得できない場合でも、モデル名がわかれば foundry model download <alias> で直接ダウンロードできます。この現象はサーバー側の一時的な問題であることが多いため、時間をおいて再試行することも有効です。

CLIでモデルをダウンロード＆実行する

モデルをダウンロードする

以下のコマンドでモデルをダウンロードします。エイリアス名を指定するだけで実行できます。

foundry model download qwen2.5-0.5b

ダウンロードが完了します。Snapdragon X搭載PCの場合、Foundry LocalがQNNExecutionProvider（Qualcomm NPU向け）最適化モデル qwen2.5-0.5b-instruct-qnn-npu:1 を自動で選択します。ハードウェアの自動検出により、手動での設定は不要です。

モデルを実行する

以下のコマンドでモデルを起動し、対話モードに入ります。

foundry model run qwen2.5-0.5b

対話してみる

対話モードに入ったら、プロンプトに質問を入力します。

Why is the sky blue?

クラウドに接続していない状態で、英語の質問に対して詳細な回答が返ってきます。これでオフライン動作を確認できました。

CLIで使用できる主なコマンドは以下のとおりです。

コマンド	内容
foundry model list	利用可能なモデル一覧を表示する
foundry model run <alias>	モデルをダウンロード＆対話実行する
foundry model download <alias>	モデルをキャッシュにダウンロードする（実行なし）
foundry service status	ローカルサービスの状態を確認する
foundry service restart	サービスを再起動する
foundry cache list	ローカルキャッシュ内のモデル一覧を表示する

Python SDKで試してみる

CLIでの動作確認ができましたので、次はPython SDKから呼び出してみます。

SDKをインストールする

OSに合わせて以下のコマンドを実行します。

# Windows（WindowsML統合版・NPU/GPU アクセラレーション対応）
pip install foundry-local-sdk-winml openai

# macOS / Linux（クロスプラットフォーム版）
pip install foundry-local-sdk openai

プロジェクト構成を確認する

以下のファイル構成でプロジェクトを用意します。

サンプルコード（app.py）を作成する

以下のコードを app.py として保存します。

from foundry_local_sdk import Configuration, FoundryLocalManager

def main():
    # SDK を初期化
    config = Configuration(app_name="foundry_local_samples")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    # 実行プロバイダーのダウンロードと登録
    print("実行プロバイダーを確認中...")
    manager.download_and_register_eps()

    # モデルをカタログから取得してダウンロード
    model = manager.catalog.get_model("qwen2.5-0.5b")
    model.download(lambda p: print(f"\rダウンロード中: {p:.2f}%", end="", flush=True))
    print()
    model.load()
    print("モデルの準備完了！")

    # ストリーミング推論
    client = model.get_chat_client()
    messages = [{"role": "user", "content": "黄金比とは何ですか？簡単に教えてください。"}]

    print("アシスタント: ", end="", flush=True)
    for chunk in client.complete_streaming_chat(messages):
        if not chunk.choices:   # 最終チャンクのガード
            continue
        content = chunk.choices[0].delta.content
        if content:
            print(content, end="", flush=True)
    print()

    model.unload()
    print("モデルをアンロードしました。")

if __name__ == "__main__":
    main()

実行する

python app.py

以下のコマンドでスクリプトを実行します。

日本語の質問に対して、ストリーミング形式で回答が返ってきます。モデルのダウンロードから推論・アンロードまで、コード通りに動作することを確認できました。

よくあるエラーと対処

エラー	対処
ModuleNotFoundError: No module named 'foundry_local_sdk'	pip install foundry-local-sdk を再実行します
IndexError: list index out of range	ストリーミング最終チャンクで choices が空になります。if not chunk.choices: continue でガードします
Request to local service failed	foundry service restart を実行します
No models were returned from the Azure Foundry catalog.	foundry model download <alias> で直接ダウンロードします

まとめ

今回は Foundry Local を実機で動かした全手順をまとめました。

実施内容	結果
winget でインストール	コマンド1行で完了。バージョン 0.8.119
サービス起動	foundry service restart で解決
モデルダウンロード	NPU向け qwen2.5-0.5b-instruct-qnn-npu:1 が自動選択
CLI対話	「Why is the sky blue?」に英語で詳細回答
Python SDK	app.py で日本語ストリーミング推論が動作

サービス未起動やカタログエラーなどのトラブルが発生しましたが、すべて解決して実際に動作することを確認できました。
「Azureサブスクリプション不要」「データがデバイス外に出ない」「オフライン動作対応」の3点が揃っているため、セキュリティ要件の厳しいプロジェクトや現場ツールの開発において大きなメリットになります。
ご興味のある方はぜひ試してみてください。また新しい検証結果があれば記事にしていきます。