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

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

快速验证

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

1. 显示 CLI 帮助信息：

    foundry --help
   

   此命令输出使用情况信息和可用命令组的列表。

   参考： 概述

2. 检查服务器状态：

foundry 服务器状态“'”

此命令打印 Foundry Local 守护程序是否正在运行并包括其本地终结点。

参考： 服务器命令

概述

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

CLI 将命令组织成以下组：

• 模型： modelcache
• 运行：run、、chat、 completetranscribe
• 服务器： server
• 设置： config
• 帮助： statusreport

下表汇总了顶级命令：

模型命令

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

模型列表排序

当多个模型 ID 变体可用于别名时，模型列表按优先级顺序显示模型。 在指定模型 alias 时运行的模型是列表中的第一个模型。

模型列表筛选

使用显式选项缩小 foundry model list 或展开结果。

示例

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?

服务器命令

下表总结了与管理和运行 Foundry Local 服务相关的命令：

固定端口本地服务器

若要在固定端口上启动本地服务并保持守护程序运行，请使用--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 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 会在首次运行时自动下载这些执行提供程序。 当新版本可用时，插件执行提供程序会自动更新。

将 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 本地：

   1. 转到“设置>管理员设置连接”>并启用直接连接。
   2. 转到 “设置>连接>管理直接连接 ” +并选择。
   3. 将 URLhttp://localhost:PORT/v1 设置为（替换为 PORT 步骤 2 中的端口），将 身份验证 设置为 “无”。
   4. 选择“保存”。

3. 从下拉列表中选择一个模型并开始聊天。

升级 Foundry Local

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

• Windows:

  winget upgrade --id Microsoft.FoundryLocal
  

• macOS：

  brew upgrade foundrylocal
  

卸载 Foundry 本地

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

• Windows:

  winget uninstall Microsoft.FoundryLocal
  

• macOS：

  brew rm foundrylocal
  brew untap microsoft/foundrylocal
  brew cleanup --scrub
  

故障排除

服务连接问题

如果在运行如下 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

此命令修复了服务器因端口绑定问题而无法访问的情况。

有关更多故障排除指南，请参阅 最佳做法和故障排除。