Foundry 本地 CLI 參考指南

Important

  • Foundry Local CLI 已提供預覽版。 公開預覽版提供對正在部署的功能的早期存取。
  • 正式發行前的功能、方法和程序可能會變更或有功能上的限制。

本文提供 Foundry Local 命令行介面 （CLI） 的完整參考。 CLI 將指令組織成邏輯類別，幫助您管理模型、控制本地伺服器及維護本地快取。

先決條件

  • 安裝 Foundry Local。
  • 一個本地終端機，CLI foundry 可用。
  • 請確保首次下載時具備網際網路存取權 (執行提供者與模型)。
  • Azure RBAC：不適用（本地運行）。
  • 如果你Windows有 Intel NPU 的設定，請安裝 Intel NPU 驅動程式以達到最佳 NPU 加速。

安裝 Foundry Local

使用作業系統的套件管理器安裝 Foundry Local。

  • Windows：開啟終端機並執行：
    winget install Microsoft.FoundryLocal
  • macOS：開啟終端機並執行： 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    或者，也可以從 Foundry-samples 的 GitHub 倉庫下載安裝程式。

確認安裝：

foundry --version

請確定您擁有安裝軟體的管理員權限。

Tip

如果安裝後看到服務連線錯誤（例如）， Request to local service failed請執行 foundry server restart。

快速驗證

執行這些指令確認 CLI 已安裝且服務可達。

  1. 顯示 CLI 幫助：

     foundry --help

    此指令會列印使用資訊及可用指令群組清單。

    參考資料： 概述

  2. 查看伺服器狀態：

Foundry 伺服器狀態

此指令會列印 Foundry 本地守護進程是否正在執行，並包含其本地端點。

參考資料： 伺服器指令

概觀

利用內建的說明功能來探索指令和選項。

CLI 將指令組織成以下群組：

  • 模型： modelcache
  • 跑： run， chat， complete， transcribe
  • 伺服器： server
  • 設定：config
  • 求助： statusreport

下表總結了頂層指令：

Command Description
foundry model 發現、檢查、下載、載入及卸載本地模型。
foundry chat <model> 啟動互動式本地聊天會話。
foundry complete <model> <prompt> 產生一個無狀態的文字補全。
foundry run <model> 運行一個自動路由到聊天或轉錄的模型。
foundry server 啟動、停止、重啟、檢查並排除本地 Foundry 惡魔。
foundry cache 檢查並管理已下載的模型快取條目。
foundry config 檢視與編輯持久化的 Foundry CLI 設定。
foundry status 顯示系統、服務、型號及連接性診斷。
foundry report 開啟一個預先填好且帶有診斷功能的 GitHub 問題。
foundry transcribe 啟動互動式本地語音轉錄會談或轉錄檔案。

模型命令

下表摘要說明與管理和執行模型相關的命令：

Note

您可以依其model或模型標識碼來指定自變數。 使用別名：

  • 自動為你現有硬體選擇最佳型號。 舉例來說，如果你有 Nvidia GPU，Foundry Local 會選擇最佳的 GPU 型號。 如果您有支援的 NPU 可用，Foundry Local 會選取 NPU 模型。
  • 可讓您使用較短的名稱，而不需要記住模型 ID。

如果您想要執行特定模型，請使用模型識別碼。 例如，不論你可用的硬體如何，都要在 qwen2.5-0.5bCPU 上執行。foundry run qwen2.5-0.5b-instruct-generic-cpu

Command Description
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 來縮小或擴展結果範圍。

Note

當您在安裝後首次執行 foundry model list 時，Foundry Local 會自動下載機器硬體組態的相關執行提供者 （EP）。 在模型清單出現之前，您會看到一個進度列，指出下載完成。

選項 Description
--device <device> 依裝置篩選模型。
--type <type> 依類型篩選模型。
--search <query> 以搜尋查詢篩選模型。
--cached 會篩選清單到快取模型。
--loaded 篩選出已載入的模型。
--variants 列表中包含車型變體。

Examples

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?

Tip

替換 qwen2.5-0.5b 成目錄中的任何型號別名。 跑去 foundry model list 查看可用模型。 Foundry Local 會下載最適合你硬體的版本——例如，NVIDIA GPU 的 CUDA 版本或 Qualcomm NPU 的 NPU 版本。

伺服器命令

下表摘要說明與管理和執行 Foundry Local Service 相關的命令：

Command Description
foundry server --help 顯示所有可用的伺服器相關指令及其使用情況。
foundry server start 啟動 Foundry 本地守護程序及相容 OpenAI 的本地服務。
foundry server start --port <port> 在指定的 TCP 埠開始本地服務。 用於 0 作業系統指定的埠口。
foundry server start --idle-timeout <minutes> 在指定非啟用分鐘數後停止守護程序。 用來 0 維持惡魔運作。
foundry server stop 阻止鑄造廠本地惡魔。
foundry server restart 重新啟動鑄造廠本地守護程序和本地服務。
foundry server restart --port <port> --idle-timeout 0 在指定的 TCP 埠上重新啟動本地服務，並讓守護程序繼續運作。
foundry server status 顯示守護程序狀態、本地服務網址、程序 ID、運作時間及日誌位置。
foundry server logs 顯示 Foundry 本地守護程序與 SDK 日誌。

固定埠本地伺服器

要在固定埠啟動本地服務並保持守護程序運作，請使用 --port ：--idle-timeout 0

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

如果守護程序已經在執行，需要套用新埠，請用相同的選項重新啟動它：

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

要驗證本地端點的網址，請執行：

foundry server status

快取命令

下表摘要說明管理儲存模型之本機快取的命令：

Command Description
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 執行提供者使用 Dawn，這是網頁 API 的原生實作，用於任何 GPU 上的加速，並且是 Foundry Local 的 GPU 備援。

CUDA 執行供應商使用 NVIDIA CUDA 進行 NVIDIA GPU 的加速。 它需要 NVIDIA GeForce RTX 30 系列及以上版本，並至少推薦驅動程式版本為 32.0.15.5585，CUDA 版本為 12.5。 它受以下授權條款約束：NVIDIA 軟體開發套件授權協議（EULA）。

插件執行提供者

下表中列出的執行提供者可依裝置與驅動程式相容性，在 Windows 上提供動態下載與註冊。 它們受限於上述授權條款。

Foundry Local 會在首次執行時自動下載這些執行提供者。 當有新版本可用時，外掛執行提供者會自動更新。

名稱（供應商） 要求 授權條款
NvTensorRTRTXExecutionProvider （NVIDIA） NVIDIA GeForce RTX 30XX 及之後版本，使用最低推薦驅動程式版本 32.0.15.5585 及 CUDA 版本 12.5 NVIDIA 軟體開發套件授權協議—EULA
OpenVINOExecutionProvider （Intel） CPU：Intel TigerLake（第 11 代）及以後版本，最低推薦驅動程式為 32.0.100.9565
顯示卡：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® 神經處理 SDK，解壓 ZIP 檔，然後開啟 LICENSE.pdf 檔案。
VitisAIExecutionProvider （AMD） 最小值：Adrenalin 版 25.6.3，附 NPU 驅動程式 32.00.0203.280
Max：Adrenalin 版本 25.9.1，搭配 NPU 驅動程式 32.00.0203.297		 無需額外許可證

在本地伺服器上使用 Open WebUI

將 Open WebUI 連接到 Foundry Local，打造一個完全在你裝置上運行的瀏覽器聊天介面。

  1. 啟動模型並保持終端機開啟：

Foundry 運行 QWEN2.5-0.5b


1. Get your local endpoint URL:

```bash
foundry server status

複製端點網址。 Foundry Local 在每次服務啟動時都會指派一個動態埠。

  1. 安裝並啟動 Open WebUI，然後在瀏覽器中開啟 http://localhost:8080 。

  2. 將 Open WebUI 連接到 Foundry 本地：

    1. 到設定>中的管理員設定>連線，並啟用直接連線。
    2. 到 設定>中的連線>管理直接連線 ，然後選擇 +。
    3. 將 URL 設為 http://localhost:PORT/v1 （替換 PORT 成步驟 2 的埠口），並將 Auth 設為 None。
    4. 選取 [儲存]。

  3. 從下拉選單選擇一位模特兒，開始聊天。

Tip

如果沒有模型出現，請在終端機執行 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