Foundry Local 的最佳做法和故障排除指南

重要

• Foundry Local 以预览版形式提供。 通过公共预览版，可以提前访问正处于开发状态的功能。
• 正式发布 (GA) 之前，功能、方法和流程可能会发生更改或功能受限。

本文列出了 Foundry Local 的最佳做法和故障排除提示。

先决条件

• 安装 Foundry Local。
• 拥有 Internet 访问权限以下载模型（建议）。
• 如果使用本文中的计算机范围安装解决方法，请以管理员身份运行 PowerShell。

验证 CLI

运行以下命令，确认已安装 Foundry Local CLI 并在 PATH 中可用：

foundry --help

此命令列出了可用的命令和选项。

参考： Foundry 本地命令行接口（CLI）参考

安全最佳做法

• 仅在符合组织安全策略的环境中运行 Foundry Local。
• 处理敏感数据时，确保你的设备满足组织的安全要求。
• 对缓存包含敏感微调数据的模型的设备进行磁盘加密。

许可注意事项

查看在 Foundry Local 中运行的模型的许可含义。 若要查看目录中每个模型的完整模型许可条款，请运行以下命令。 在以下命令中，将占位符 <model> 替换为模型名称：

foundry model info <model> --license

参考： Foundry 本地命令行接口（CLI）参考

性能最佳做法

如果推理速度缓慢，请考虑以下策略：

• 运行 Foundry Local 之前，请停止任何用于 VS Code 推理的 AI 工具包会话。
• 可用时使用 GPU 加速。
• 通过监视推理期间的内存使用情况识别瓶颈。
• 尝试更多量化模型变体（例如 INT8 而不是 FP16）。
• 为非交互式工作负荷调整批处理大小。

生产部署范围

Foundry Local 适用于本地设备推理，不适用于分布式、容器化或多机器生产部署。

故障排除

常见问题和解决方案

問题	可能的原因	解决方案
推理缓慢	仅使用 CPU 的模型，具有大量参数。	如果可用，请使用 GPU 优化的模型变体。
模型下载失败	网络连接问题。	检查网络连接，并运行 foundry cache list 验证缓存状态。
服务连接错误 (Request to local service failed. Uri:http://127.0.0.1:0/foundry/list)	端口绑定问题或服务不可访问。	运行 foundry service restart 重启服务，解决端口绑定问题。
服务启动失败。	端口冲突或权限问题。	运行 foundry service restart，或使用 附带日志foundry zip-logs。
未检测到 Intel NPU 或其无法工作	缺少或过时的 Intel NPU 驱动程序。	安装适用于 Windows 的 Intel NPU 驱动程序以启用 NPU 加速。
高通 NPU 错误 (Qnn error code 5005: "Failed to load from EpContext model. qnn_backend_manager.")	过时的高通 NPU 驱动程序或 NPU 资源冲突。	安装高通 NPU 驱动程序。 如果问题仍然存在，请重启以清除 NPU 资源冲突，尤其是在使用 Windows Copilot+ 功能后。
winget install Microsoft.FoundryLocal --scope machine 失败并显示“当前系统配置不支持安装此包”。	Winget 阻止 MSIX 计算机范围安装。	使用 安装问题中的解决方法。

安装问题

如果 winget install Microsoft.FoundryLocal --scope machine 失败并显示“当前系统配置不支持安装此包”。请改用 Add-AppxProvisionedPackage 。

1. 下载.msix及其依赖项包。
2. 以管理员身份运行 PowerShell。
3. 运行以下命令，为所有用户安装 Foundry Local：

Add-AppxProvisionedPackage -Online -PackagePath .\FoundryLocal.msix `
  -DependencyPackagePath .\VcLibs.appx -SkipLicense

相关参考

• Foundry Local CLI 参考
• Foundry 本地 SDK 参考
• Foundry 本地 REST API 参考