你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Foundry Local CLI 参考

重要

Foundry Local CLI 以预览版提供。公共预览版为正在部署的功能提供早期访问。
正式发布 (GA) 之前，功能、方法和流程可能会发生更改或功能受限。

本文提供了 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 Local GitHub 存储库下载安装程序。

验证安装：

foundry --version

请确保你具有安装软件的管理员权限。

小窍门

如果在安装后看到服务连接错误（例如）， Request to local service failed请运行 foundry service restart。

快速验证

运行这些命令以确认 CLI 已安装且可访问该服务。

显示 CLI 帮助信息：
```
 foundry --help
```
此命令输出使用情况信息和可用命令组的列表。

参考：概述
检查服务状态：
```
 foundry service status
```
此命令显示 Foundry Local 服务是否正在运行，并提供其本地终结点。

参考：服务命令

概述

使用内置帮助浏览命令和选项。

CLI 将命令组织为三个主要类别：

模型：用于管理和运行 AI 模型的命令
服务：用于控制 Foundry 本地服务的命令
Cache：用于管理本地模型storage的命令

模型命令

下表总结了与管理和运行模型相关的命令：

注释

可以通过参数model或模型 ID 来指定参数。使用别名：

自动为可用硬件选择最佳模型。例如，如果有可用的 Nvidia GPU，Foundry Local 会选择最佳 GPU 模型。如果有受支持的 NPU 可用，Foundry Local 会选择 NPU 模型。
允许使用较短的名称，而无需记住模型 ID。

如果要运行特定模型，请使用模型 ID。例如，若要在 qwen2.5-0.5b CPU 上运行（无论可用的硬件如何），请使用： 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 选项筛选模型。可以使用键值对基于单个属性筛选模型。

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

此命令输出与筛选器键和值匹配的模型。

参考：模型列表筛选

注释

安装完成后首次运行foundry model list时，Foundry Local会根据您计算机的硬件配置自动下载相关的执行提供程序（EP）。此时会看到一个进度栏，指示模型列表出现之前下载完成。

支持的筛选器键：

设备 - 硬件设备类型

按其运行的硬件设备筛选模型。

可能的值：

CPU - 中央处理单元模型
GPU - 图形处理单元模型
NPU - 神经处理单元模型

提供者 - 执行提供者

按其执行提供程序或运行时筛选模型。

可能的值：

CPUExecutionProvider - 基于 CPU 的执行
CUDAExecutionProvider - NVIDIA CUDA GPU 执行
WebGpuExecutionProvider - WebGPU 的执行
QNNExecutionProvider - 高通神经网络运算（NPU）
OpenVINOExecutionProvider - Intel OpenVINO 执行
NvTensorRTRTXExecutionProvider - NVIDIA TensorRT 执行过程
VitisAIExecutionProvider - AMD Vitis AI 执行

任务 - 模型任务类型

按其预期用例或任务筛选模型。

常见值：

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

这些示例按设备、任务和执行提供程序筛选模型列表。

参考：模型列表筛选

注释

所有比较不区分大小写。
每个命令只能使用一个筛选器。
无法识别的筛选器键会导致错误。

以交互方式运行模型

运行模型，并在终端中直接与它交互：

foundry model run 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 service --help`	显示所有可用的服务相关命令及其用法。
`foundry service start`	启动 Foundry Local 服务。
`foundry service stop`	停止 Foundry Local 服务。
`foundry service restart`	重启 Foundry 本地服务。
`foundry service status`	显示 Foundry 本地服务的当前状态。
`foundry service ps`	列出 Foundry Local 服务中当前加载的所有模型。
`foundry service diag`	显示 Foundry 本地服务的日志。
`foundry service set <options>`	设置 Foundry 本地服务的配置。

缓存命令

下表汇总了用于管理存储模型的本地缓存的命令：

命令	说明
`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，这是一个基于 Web 的 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 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® 神经处理 SDK，提取 ZIP，然后打开 LICENSE.pdf 文件。
`VitisAIExecutionProvider` （AMD）	最低配置：Adrenalin Edition 25.6.3 与 NPU 驱动 32.00.0203.280 最高版本：Adrenalin Edition 25.9.1，使用的 NPU 驱动程序版本为 32.00.0203.297	无需其他许可证

将 Open WebUI 与本地服务器配合使用

将 Open WebUI 连接到 Foundry Local，以获取完全在设备上运行的基于浏览器的聊天界面。

启动模型并将终端保持打开状态：
```
foundry model run qwen2.5-0.5b
```
获取本地终结点 URL：
```
foundry service status
```
复制终结点 URL。 Foundry Local 每次启动服务时都会分配动态端口。
安装并启动 Open WebUI，然后在浏览器中打开 http://localhost:8080 。
将 Open WebUI 连接到 Foundry 本地：
1. 转到“设置>管理员设置连接”>并启用直接连接。
2. 转到 “设置>连接>管理直接连接 ” +并选择。
3. 将 URLhttp://localhost:PORT/v1 设置为（替换为 PORT 步骤 2 中的端口），将 身份验证 设置为 “无”。
4. 选择“保存”。
从下拉列表中选择一个模型并开始聊天。

小窍门

如果未显示模型，请在终端中运行 foundry model run <model> 并重新加载 Open WebUI。如果连接失败，请使用 .. 确认端口 foundry service status。

升级 Foundry Local

运行操作系统的命令以升级 Foundry Local。

Windows：

winget upgrade --id Microsoft.FoundryLocal

macOS：
```
brew upgrade foundrylocal
```

卸载 Foundry 本地

运行操作系统的命令以卸载 Foundry Local。