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 run qwen2.5-0.5b-instruct-generic-cpuを使用します。

命令 説明
foundry model --help 使用可能なすべてのモデル関連コマンドとその使用方法を表示します。
foundry model list ローカルで使用できるすべてのモデルを一覧表示します。 初回実行時には、ハードウェアの実行プロバイダー (EP) がダウンロードされます。
foundry model info <model> 特定のモデルに関する詳細情報を表示します。
foundry model download <model> モデルを実行せずにローカル キャッシュにダウンロードします。
foundry model load <model> サービスにモデルを読み込みます。
foundry model unload <model> サービスからモデルをアンロードします。

モデル リストの順序付け

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

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

結果を絞り込んだり拡張したりするには、 foundry model list の明示的なオプションを使用します。

注

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

オプション 説明
--device <device> デバイスでモデルをフィルター処理します。
--type <type> モデルを種類別にフィルター処理します。
--search <query> 検索クエリでモデルをフィルター処理します。
--cached キャッシュされたモデルに一覧をフィルター処理します。
--loaded 読み込まれたモデルに一覧をフィルター処理します。
--variants 一覧にモデルバリアントが含まれます。

例示

foundry model list --device gpu
foundry model list --type chat
foundry model list --search qwen
foundry model list --cached
foundry model list --loaded
foundry model list --variants

次の例では、サポートされているオプションを使用して、モデルの一覧をフィルター処理または展開します。

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

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

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

foundry chat qwen2.5-0.5b

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

Why is the sky blue?

ヒント

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 ログを表示します。

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

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

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 run qwen2.5-0.5b


1. Get your local endpoint URL:

```bash
foundry server status

エンドポイント URL をコピーします。 Foundry Local では、サービスが開始されるたびに動的ポートが割り当てられます。

  1. Open WebUI をインストールして起動し、ブラウザーでhttp://localhost:8080を開きます。

  2. Open WebUI を Foundry Local に接続する:

    1. 設定>Admin 設定>Connections に移動し、直接接続を有効にします。
    2. 設定>Connections>Manage Direct Connections に移動し、+を選択します。
    3. URL を http://localhost:PORT/v1 に設定し (PORTを手順 2 のポートに置き換えます)、認証を [なし] に設定します。
    4. 保存を選びます。

  3. ドロップダウンからモデルを選択し、チャットを開始します。

ヒント

モデルが表示されない場合は、ターミナルで foundry run <model> を実行し、Open WebUI を再読み込みします。 接続に失敗した場合は、 foundry server statusでポートを確認します。

Foundry Local のアップグレード

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

  • Windows: 
    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