Foundry ローカル「CLI」リファレンス

Important

  • Foundry Local CLI はプレビューで利用できます。 パブリック プレビュー リリースでは、アクティブなデプロイ中の機能に早期accessが提供されます。
  • 一般提供 (GA) の前は、機能、アプローチ、プロセスが変更されたり、機能が制限されたりする場合があります。

この記事では、Foundry Local コマンド ライン インターフェイス (CLI) の包括的なリファレンスを提供します。 CLI は、モデルの管理、ローカル サーバーの制御、ローカル キャッシュの維持に役立つコマンドを論理カテゴリに編成します。

前提条件

  • Foundry Local をインストールします。
  • foundry CLI が使用可能なローカル ターミナル。
  • 初回ダウンロード（実行プロバイダーとモデル）のためにインターネットアクセスがあることを確認します。
  • Azure RBAC: 適用できません (ローカルで実行されます)。
  • Windowsに Intel NPU がある場合は、最適な NPU アクセラレーションのために Intel NPU ドライバーをインストールします。

Foundry Local のインストール

オペレーティング システムのパッケージ マネージャーを使用して Foundry Local をインストールします。

  • Windows: ターミナルを開き、次のコマンドを実行します。
    winget install Microsoft.FoundryLocal
  • macOS: ターミナルを開き、次のコマンドを実行します。 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    または、foundry-samples GitHub リポジトリからインストーラーをダウンロードします。

インストールを確認します。

foundry --version

ソフトウェアをインストールするための管理者権限があることを確認します。

ヒント

インストール後にサービス接続エラー ( Request to local service failed など) が表示された場合は、 foundry server restart実行します。

クイック検証

これらのコマンドを実行して、CLI がインストールされ、サービスに到達可能であることを確認します。

  1. CLI のヘルプを表示する:

     foundry --help

    このコマンドは、使用状況情報と使用可能なコマンド グループの一覧を出力します。

    リファレンス: 概要

  2. サーバーの状態を確認します。

foundry サーバーの状態 '''

このコマンドは、Foundry Local デーモンが実行されていて、そのローカル エンドポイントが含まれているかどうかを出力します。

リファレンス: サーバー コマンド

概要

組み込みのヘルプを使用して、コマンドとオプションを調べる。

CLI は、コマンドを次のグループに編成します。

  • モデル: model、 cache
  • 実行: run、 chat、 complete、 transcribe
  • サーバー: server
  • セットアップ: config
  • ヘルプ: status、 report

次の表は、最上位レベルのコマンドをまとめたものです。

命令 説明
foundry model ローカル モデルを検出、検査、ダウンロード、読み込み、アンロードします。
foundry chat <model> 対話型のローカル チャット セッションを開始します。
foundry complete <model> <prompt> ステートレス テキスト入力候補を 1 つ生成します。
foundry run <model> チャットまたは文字起こしへの自動ルーティングを使用してモデルを実行します。
foundry server ローカル Foundry デーモンの起動、停止、再起動、検査、トラブルシューティングを行います。
foundry cache ダウンロードしたモデル キャッシュ エントリを検査および管理します。
foundry config 永続的な Foundry CLI 設定を表示および編集します。
foundry status システム、サービス、モデル、接続の診断を表示します。
foundry report 診断に関する事前入力済みのGitHubの問題を開きます。
foundry transcribe 対話型のローカル音声文字起こしセッションを開始するか、ファイルを文字起こしします。

モデル コマンド

次の表は、モデルの管理と実行に関連するコマンドをまとめたものです。

注

model引数は、そのエイリアスまたはモデル ID で指定できます。 エイリアスの使用:

  • 使用可能なハードウェアに最適なモデルを自動的に選択します。 たとえば、Nvidia GPU を使用できる場合、Foundry Local は最適な GPU モデルを選択します。 サポートされている NPU を使用できる場合は、Foundry Local によって NPU モデルが選択されます。
  • モデル ID を覚えておく必要なく、短い名前を使用できます。

特定のモデルを実行する場合は、モデル ID を使用します。 たとえば、使用可能なハードウェアに関係なく、CPU で qwen2.5-0.5b を実行するには、 foundry model run qwen2.5-0.5b-instruct-generic-cpuを使用します。

命令 説明
foundry model --help 使用可能なすべてのモデル関連コマンドとその使用方法を表示します。
foundry model run <model> 指定したモデルを実行し、キャッシュされていない場合はダウンロードして、対話を開始します。
foundry model list ローカルで使用できるすべてのモデルを一覧表示します。 初回実行時には、ハードウェアの実行プロバイダー (EP) がダウンロードされます。
foundry model list --filter <key>=<value> 指定した条件 (デバイス、タスク、エイリアス、プロバイダー) でフィルター処理されたモデルを一覧表示します。
foundry model info <model> 特定のモデルに関する詳細情報を表示します。
foundry model info <model> --license 特定のモデルのライセンス情報を表示します。
foundry model download <model> モデルを実行せずにローカル キャッシュにダウンロードします。
foundry model load <model> サービスにモデルを読み込みます。
foundry model unload <model> サービスからモデルをアンロードします。

モデル リストの順序付け

エイリアスに対して複数のモデル ID バリアントを使用できる場合、モデルの一覧にモデルが優先順位で表示されます。 一覧の最初のモデルは、 aliasでモデルを指定したときに実行されるモデルです。

モデルリストのフィルタリング

foundry model list コマンドでは、--filter オプションを使用したモデルのフィルター処理がサポートされています。 キーと値のペアを使用して、1 つの属性に基づいてモデルをフィルター処理できます。

foundry model list --filter <key>=<value>

このコマンドは、フィルター キーと値に一致するモデルを出力します。

リファレンス: モデル リストのフィルター処理

注

インストール後に foundry model list を初めて実行すると、Foundry Local によって、コンピューターのハードウェア構成に関連する実行プロバイダー (IP) が自動的にダウンロードされます。 モデルの一覧が表示される前に、ダウンロードの完了を示す進行状況バーが表示されます。

サポートされているフィルター キー:

デバイス - ハードウェア デバイスの種類

実行されているハードウェア デバイスによってモデルをフィルター処理します。

使用可能な値:

  • CPU - 中央処理装置モデル
  • GPU - グラフィックス処理装置モデル
  • NPU - ニューラル処理ユニット モデル

プロバイダー - 実行プロバイダー

実行プロバイダーまたはランタイムによってモデルをフィルター処理します。

使用可能な値:

  • CPUExecutionProvider - CPU ベースの実行
  • CUDAExecutionProvider - NVIDIA CUDA GPU の実行
  • WebGpuExecutionProvider - WebGPU の実行
  • QNNExecutionProvider - Qualcomm ニューラルネットワーク処理 (NPU)
  • OpenVINOExecutionProvider - Intel OpenVINO の実行
  • NvTensorRTRTXExecutionProvider - NVIDIA TensorRT の実行
  • VitisAIExecutionProvider - AMD Vitis AI の実行

task - モデル タスクの種類

モデルを目的のユース ケースまたはタスクでフィルター処理します。

一般的な値:

  • chat-completion: 会話型 AI モデル
  • text-generation: テキスト生成モデル

alias - モデルエイリアス

エイリアス識別子でモデルをフィルター処理します。 * サフィックスを使用したワイルドカード 照合をサポートします。

サンプル値:

  • phi4-cpu
  • qwen2.5-coder-0.5b-instruct-generic-cpu
  • deepseek-r1-distill-qwen-1.5b-generic-cpu
  • phi-4-mini-instruct-generic-cpu

特殊なフィルター機能

否定のサポート: 一致するモデルを除外するには、 ! を使用して値のプレフィックスを付けます。

foundry model list --filter device=!GPU

このコマンドは、結果から GPU モデルを除外します。

リファレンス: 特殊なフィルター機能

ワイルドカード一致 (エイリアスのみ): エイリアスでフィルター処理するときにプレフィックスに一致する * を追加します。

foundry model list --filter alias=qwen*

このコマンドは、エイリアスが qwen で始まるモデルを返します。

リファレンス: 特殊なフィルター機能

例示

foundry model list --filter device=GPU
foundry model list --filter task=chat-completion
foundry model list --filter provider=CUDAExecutionProvider

次の例では、デバイス、タスク、実行プロバイダーによってモデルの一覧をフィルター処理します。

リファレンス: モデル リストのフィルター処理

注

  • すべての比較において大文字と小文字を区別しません。
  • コマンドごとに使用できるフィルターは 1 つだけです。
  • 認識できないフィルター キーを使用すると、エラーが発生します。

モデルを対話形式で実行する

モデルを実行し、ターミナルで直接操作します。

foundry model run qwen2.5-0.5b

Foundry Local は、最初の実行時にモデルをダウンロードし、対話型セッションを開始します。 応答を取得するためのプロンプトを入力します。

Why is the sky blue?

Foundry Local run コマンドからの出力のスクリーンショット。

ヒント

qwen2.5-0.5bをカタログの任意のモデル エイリアスに置き換えます。 foundry model listを実行して、使用可能なモデルを表示します。 Foundry Local は、ハードウェアに最適なバリアント (NVIDIA GPU の CUDA バリアントや、Qualcomm NPU の NPU バリアントなど) をダウンロードします。

サーバーのコマンド。

次の表は、Foundry Local サービスの管理と実行に関連するコマンドをまとめたものです。

命令 説明
foundry server --help 使用可能なすべてのサーバー関連コマンドとその使用方法を表示します。
foundry server start Foundry Local デーモンと OpenAI 互換のローカル サービスを開始します。
foundry server start --port <port> 指定した TCP ポートでローカル サービスを開始します。 OS 割り当てポートに 0 を使用します。
foundry server start --idle-timeout <minutes> 指定した非アクティブ分数の後にデーモンを停止します。 デーモンを実行したままにするには、 0 を使用します。
foundry server stop Foundry Local デーモンを停止します。
foundry server restart Foundry Local デーモンとローカル サービスを再起動します。
foundry server restart --port <port> --idle-timeout 0 指定した TCP ポートでローカル サービスを再起動し、デーモンを実行したままにします。
foundry server status デーモンの状態、ローカル サービスの URL、プロセス ID、アップタイム、ログの場所を表示します。
foundry server logs Foundry Local デーモンと SDK ログを表示します。

固定ポート ローカル サーバー

固定ポートでローカル サービスを開始し、デーモンを実行したままにするには、--idle-timeout 0で--portを使用します。

foundry server start --port 39839 --idle-timeout 0

デーモンが既に実行されていて、新しいポートを適用する必要がある場合は、同じオプションで再起動します。

foundry server restart --port 39839 --idle-timeout 0

ローカル エンドポイント URL を確認するには、次を実行します。

foundry server status

キャッシュ コマンド

次の表は、モデルが格納されているローカル キャッシュを管理するためのコマンドをまとめたものです。

命令 説明
foundry cache --help 使用可能なすべてのキャッシュ関連コマンドとその使用状況が表示されます。
foundry cache location 現在のキャッシュ ディレクトリを表示します。
foundry cache list ローカル キャッシュに格納されているすべてのモデルを一覧表示します。
foundry cache cd <path> キャッシュ ディレクトリを指定したパスに変更します。
foundry cache remove <model> ローカル キャッシュからモデルを削除します。

実行プロバイダー

実行プロバイダーは、デバイスで可能な限り効率的にモデルを実行するハードウェア固有のアクセラレーション ライブラリです。

組み込みの実行プロバイダー

Foundry Local には、CPU 実行プロバイダー、WebGPU 実行プロバイダー、および CUDA 実行プロバイダーが含まれます。

CPU 実行プロバイダーは、Microsoft線形代数サブルーチン (MLAS) を使用して任意の CPU で実行され、Foundry Local の CPU フォールバックです。

WebGPU 実行プロバイダーは、web ベースの API のネイティブ実装である Dawn を任意の GPU での高速化に使用し、Foundry Local の GPU フォールバックです。

CUDA 実行プロバイダーは、NVIDIA GPU の高速化に NVIDIA CUDA を使用します。 最小推奨ドライバー バージョン 32.0.15.5585 および CUDA バージョン 12.5 を備えた NVIDIA GeForce RTX 30 シリーズ以降が必要です。 NVIDIA ソフトウェア開発キットの使用許諾契約書 (EULA) のライセンス条項が適用されます。

プラグイン実行プロバイダー

次の表に示す実行プロバイダーは、デバイスとドライバーの互換性に応じて、Windowsでの動的なダウンロードと登録に使用できます。 指定されたライセンス条項に従います。

Foundry Local では、最初の実行時にこれらの実行プロバイダーが自動的にダウンロードされます。 プラグイン実行プロバイダーは、新しいバージョンが利用可能になると自動的に更新されます。

名前 (ベンダー) 必要条件 ライセンス条項
NvTensorRTRTXExecutionProvider (NVIDIA) 最小推奨ドライバー バージョン 32.0.15.5585 および CUDA バージョン 12.5 の NVIDIA GeForce RTX 30XX 以降のバージョン NVIDIA ソフトウェア開発キットの使用許諾契約書 - EULA
OpenVINOExecutionProvider （インテル） CPU: Intel TigerLake (第 11 世代) 以降のバージョン (最小推奨ドライバー 32.0.100.9565)
GPU: Intel AlderLake (第 12 世代) 以降のバージョン (最小推奨ドライバー 32.0.101.1029)
NPU: Intel ArrowLake (第 15 世代) 以降のバージョン (最小推奨ドライバー 32.0.100.4239)		 Intel OBLディストリビューション商用使用ライセンス契約 v2025.02.12
QNNExecutionProvider (クアルコム) Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU (最小ドライバー バージョン 30.0.140.0 以降)
Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU (最小ドライバー バージョン 30.0.140.0 以降)		 QNN ライセンスを表示するには、Qualcomm® Neural Processing SDK をダウンロードし、ZIP を抽出して、LICENSE.pdf ファイルを開きます。
VitisAIExecutionProvider (AMD) 最小要件: Adrenalin Edition 25.6.3 (NPU ドライバー 32.00.0203.280)
Max: アドレナリン エディション 25.9.1 と NPU ドライバー 32.00.0203.297		 追加のライセンスは必要ありません

ローカル サーバーで Open WebUI を使用する

Open WebUI を Foundry Local に接続して、デバイス上で完全に実行されるブラウザー ベースのチャット インターフェイスを作成します。

  1. モデルを開始し、ターミナルを開いたままにします。

    foundry model run qwen2.5-0.5b

  2. ローカル エンドポイントの URL を取得します。

foundry サーバーの状態


Copy the endpoint URL. Foundry Local assigns a dynamic port each time the service starts.

1. Install and launch [Open WebUI](https://github.com/open-webui/open-webui), then open `http://localhost:8080` in your browser.

1. Connect Open WebUI to Foundry Local:

1. Go to **Settings** > **Admin Settings** > **Connections** and enable **Direct Connections**.
1. Go to **Settings** > **Connections** > **Manage Direct Connections** and select **+**.
1. Set **URL** to `http://localhost:PORT/v1` (replace `PORT` with the port from step 2) and **Auth** to **None**.
1. Select **Save**.

1. Select a model from the dropdown and start chatting.

> [!TIP]
> If no models appear, run `foundry model run <model>` in a terminal and reload Open WebUI. If the connection fails, confirm the port with `foundry server status`.

## Upgrade Foundry Local

Run the command for your operating system to upgrade Foundry Local.

- **Windows**:
```bash
winget upgrade --id Microsoft.FoundryLocal
  • macOS: 
    brew upgrade foundrylocal

Foundry Local のアンインストール

オペレーティング システムのコマンドを実行して Foundry Local をアンインストールします。

  • Windows: 
    winget uninstall Microsoft.FoundryLocal
  • macOS: 
    brew rm foundrylocal
brew untap microsoft/foundrylocal
brew cleanup --scrub

Troubleshooting

サービス接続の問題

foundry model listのようなコマンドを実行するときにこのエラーが表示される場合:

Exception: Request to local service failed.
Uri: http://127.0.0.1:0/foundry/list

The requested address is not valid in its context. (127.0.0.1:0)

Please check service status with 'foundry server status'.

サービス を再起動します。

foundry server restart

このコマンドは、サーバーが実行されていても、ポート バインドの問題のためにアクセスできない場合を修正します。

トラブルシューティングのガイダンスについては、「 ベスト プラクティスとトラブルシューティング」を参照してください。

  • Last updated on