你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Important
- Foundry Local 以预览版形式提供。 通过公共预览版，可以提前访问正处于开发状态的功能。
- 正式发布 (GA) 之前，功能、方法和流程可能会发生更改或功能受限。
本指南将指导你设置 Foundry Local 以在设备上运行 AI 模型。
Prerequisites
系统必须满足以下要求才能运行 Foundry Local：
- 作系统：Windows 10（x64）、Windows 11（x64/ARM）、Windows Server 2025、macOS。
- 硬件：最小 8 GB RAM 和 3 GB 可用磁盘空间。 建议使用 16 GB RAM 和 15 GB 可用磁盘空间。
- 网络：用于下载初始模型的 Internet 连接（可选）供脱机使用。
- 加速（可选）：NVIDIA GPU（2,000 系列或更高版本）、AMD GPU（6,000 系列或更新）、AMD NPU、Intel iGPU、Intel NPU（32GB 或更多内存）、高通 Snapdragon X Elite（8GB 或更多内存）、高通 NPU 或 Apple 硅。
注释
仅在运行 Windows 24H2 或更高版本的系统上支持新的 NPU。 如果在 Windows 上使用 Intel NPU，请安装 Intel NPU 驱动程序 以在 Foundry Local 中启用 NPU 加速。
请确保你具有安装软件的管理员权限。
Tip
如果在安装后看到服务连接错误（例如“请求本地服务失败”），请运行 foundry service restart。
快速入门
快速开始使用 Foundry Local：
选项 1：快速 CLI 设置
安装 Foundry Local。
-
Windows：打开终端并运行以下命令：
winget install Microsoft.FoundryLocal -
macOS：打开终端并运行以下命令：
或者，可以从 Foundry 本地 GitHub 存储库下载安装程序。brew tap microsoft/foundrylocal brew install foundrylocal
-
Windows：打开终端并运行以下命令：
运行第一个模型。 打开终端并运行以下命令：
foundry model run qwen2.5-0.5bFoundry Local 下载模型，可能需要几分钟时间，具体取决于你的 Internet 速度，然后运行它。 模型启动后，使用命令行接口（CLI）与之交互。 例如，可以询问：
Why is the sky blue?终端中显示了来自模型的响应：
选项 2：下载入门项目
为了进行实际操作和动手学习，请下载我们提供的其中一个入门项目，该项目展示了实际应用场景：
每个项目包括：
- 分步设置说明
- 完整源代码
- 配置示例
- 最佳做法
Tip
这些初学者项目与 作指南 中的方案保持一致，并提供即时的实际价值。
Tip
将qwen2.5-0.5b替换为目录中的任意模型名称（运行foundry model list以查看可用的模型）。 Foundry Local 下载最适合系统硬件和软件配置的变体。 例如，如果有 NVIDIA GPU，Foundry Local 会下载 CUDA 版本。 如果你有 Qualcomm NPU，Foundry Local 将下载 NPU 变体。 如果没有 GPU 或 NPU，Foundry Local 将下载 CPU 版本。
如果是首次运行 foundry model list，在 Foundry Local 为你的硬件下载执行提供程序，会显示一个下载进度条。
运行最新的 OpenAI 开源模型
使用以下命令运行最新的 OpenAI 开源模型 GPT-OSS-20B：
foundry model run gpt-oss-20b
Important
运行 GPT-OSS-20B 的要求：
- 具有 16 GB VRAM 或更高版本的 NVIDIA GPU。
- Foundry Local 版本 0.6.87 或更高版本。 早期版本不支持模型。 通过以下命令检查您的版本：
foundry --version
探索命令
Foundry CLI 将命令组织成以下主要类别：
- 模型：用于管理和运行模型的命令。
- 服务：用于管理 Foundry 本地服务的命令。
- 缓存：用于管理本地模型缓存的命令（本地磁盘上下载的模型）。
查看所有命令：
foundry --help
查看 模型 命令：
foundry model --help
查看 服务 命令：
foundry service --help
查看 缓存 命令：
foundry cache --help
Tip
有关所有 CLI 命令的详细信息，请参阅 Foundry Local CLI 参考。
升级 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
Troubleshooting
服务连接问题
如果在运行 foundry model list 或类似命令时看到此错误：
>foundry model list
🟢 Service is Started on http://127.0.0.1:0/, PID 11192!
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 service status'.
运行以下命令以重启服务：
foundry service restart
此命令修复了服务因端口绑定问题而无法访问的情况。