Foundry Local SDK 参考

Python SDK 参考

安装

安装 Python 包：

pip install foundry-local-sdk

FoundryLocalManager 类

该 FoundryLocalManager 类提供用于管理模型、缓存和 Foundry Local 服务的方法。

初始化

from foundry_local import FoundryLocalManager

# Initialize and optionally bootstrap with a model
manager = FoundryLocalManager(alias_or_model_id=None, bootstrap=True)

• alias_or_model_id：（可选）在启动时下载和加载的别名或模型 ID。
• bootstrap：（默认值 True） 如果为 True，则启动服务（如果未运行），并在提供时加载模型。

有关别名的注释

此引用中概述的许多方法在签名中都有一个 alias_or_model_id 参数。 可以将 别名 或 模型 ID 作为值传入方法。 使用别名将：

• 选择适合可用硬件的最佳模型。 例如，如果 Nvidia CUDA GPU 可用，Foundry Local 将选择 CUDA 模型。 如果支持的 NPU 可用，Foundry Local 将选择 NPU 模型。
• 允许使用较短的名称，而无需记住模型 ID。

服务管理

目录管理

缓存管理

模型管理

FoundryModelInfo

方法list_catalog_models()list_cached_models()，并list_loaded_models()返回对象列表FoundryModelInfo。 可以使用此对象中包含的信息进一步优化列表。 或者通过调用 get_model_info(alias_or_model_id) 方法直接获取模型的信息。

这些对象包含以下字段：

执行提供者

下列其中一项：

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

示例用法

以下代码演示如何使用 FoundryManager 类管理模型并与 Foundry Local 服务交互。

from foundry_local import FoundryLocalManager

# By using an alias, the most suitable model will be selected
# to your end-user's device.
alias = "qwen2.5-0.5b"

# Create a FoundryLocalManager instance. This will start the Foundry.
manager = FoundryLocalManager()

# List available models in the catalog
catalog = manager.list_catalog_models()
print(f"Available models in the catalog: {catalog}")

# Download and load a model
model_info = manager.download_model(alias)
model_info = manager.load_model(alias)
print(f"Model info: {model_info}")

# List models in cache
local_models = manager.list_cached_models()
print(f"Models in cache: {local_models}")

# List loaded models
loaded = manager.list_loaded_models()
print(f"Models running in the service: {loaded}")

# Unload a model
manager.unload_model(alias)

与 OpenAI SDK 集成

安装 OpenAI 包：

pip install openai

以下代码演示如何使用 OpenAI SDK 集成 FoundryLocalManager 以与本地模型交互。

import openai
from foundry_local import FoundryLocalManager

# By using an alias, the most suitable model will be downloaded
# to your end-user's device.
alias = "qwen2.5-0.5b"

# Create a FoundryLocalManager instance. This will start the Foundry
# Local service if it is not already running and load the specified model.
manager = FoundryLocalManager(alias)

# The remaining code us es the OpenAI Python SDK to interact with the local model.

# Configure the client to use the local Foundry service
client = openai.OpenAI(
    base_url=manager.endpoint,
    api_key=manager.api_key  # API key is not required for local usage
)

# Set the model to use and generate a streaming response
stream = client.chat.completions.create(
    model=manager.get_model_info(alias).id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True
)

# Print the streaming response
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript SDK 参考文档

安装

请从 npm 安装该软件包：

npm install foundry-local-sdk

FoundryLocalManager 类

该 FoundryLocalManager 类允许你在浏览器和 Node.js 环境中管理模型、控制缓存以及与 Foundry Local 服务交互。

初始化

import { FoundryLocalManager } from "foundry-local-sdk";

const foundryLocalManager = new FoundryLocalManager();

可用选项：

• serviceUrl：Foundry Local 服务的基 URL
• fetch：（可选） 适用于 Node.js 等环境的自定义提取实现

有关别名的注释

此引用中概述的许多方法在签名中都有一个 aliasOrModelId 参数。 可以将 别名 或 模型 ID 作为值传入方法。 使用别名将：

• 选择适合可用硬件的最佳模型。 例如，如果 Nvidia CUDA GPU 可用，Foundry Local 将选择 CUDA 模型。 如果支持的 NPU 可用，Foundry Local 将选择 NPU 模型。
• 允许使用较短的名称，而无需记住模型 ID。

服务管理

目录管理

缓存管理

模型管理

示例用法

以下代码演示如何使用 FoundryLocalManager 类管理模型并与 Foundry Local 服务交互。

import { FoundryLocalManager } from "foundry-local-sdk";

// By using an alias, the most suitable model will be downloaded
// to your end-user's device.
// TIP: You can find a list of available models by running the
// following command in your terminal: `foundry model list`.
const alias = "qwen2.5-0.5b";

const manager = new FoundryLocalManager();

// Initialize the SDK and optionally load a model
const modelInfo = await manager.init(alias);
console.log("Model Info:", modelInfo);

// Check if the service is running
const isRunning = await manager.isServiceRunning();
console.log(`Service running: ${isRunning}`);

// List available models in the catalog
const catalog = await manager.listCatalogModels();

// Download and load a model
await manager.downloadModel(alias);
await manager.loadModel(alias);

// List models in cache
const localModels = await manager.listCachedModels();

// List loaded models
const loaded = await manager.listLoadedModels();

// Unload a model
await manager.unloadModel(alias);

与 OpenAI 客户端集成

安装 OpenAI 包：

npm install openai

以下代码演示如何将 FoundryLocalManager 与 OpenAI 客户端集成，以便与本地模型进行交互。

import { OpenAI } from "openai";
import { FoundryLocalManager } from "foundry-local-sdk";

// By using an alias, the most suitable model will be downloaded
// to your end-user's device.
// TIP: You can find a list of available models by running the
// following command in your terminal: `foundry model list`.
const alias = "qwen2.5-0.5b";

// Create a FoundryLocalManager instance. This will start the Foundry
// Local service if it is not already running.
const foundryLocalManager = new FoundryLocalManager();

// Initialize the manager with a model. This will download the model
// if it is not already present on the user's device.
const modelInfo = await foundryLocalManager.init(alias);
console.log("Model Info:", modelInfo);

const openai = new OpenAI({
  baseURL: foundryLocalManager.endpoint,
  apiKey: foundryLocalManager.apiKey,
});

async function streamCompletion() {
  const stream = await openai.chat.completions.create({
    model: modelInfo.id,
    messages: [{ role: "user", content: "What is the golden ratio?" }],
    stream: true,
  });

  for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write(chunk.choices[0].delta.content);
    }
  }
}

streamCompletion();

浏览器使用情况

SDK 包含与浏览器兼容的版本，必须在其中手动指定服务 URL：

import { FoundryLocalManager } from "foundry-local-sdk/browser";

// Specify the service URL
// Run the Foundry Local service using the CLI: `foundry service start`
// and use the URL from the CLI output
const endpoint = "ENDPOINT";

const manager = new FoundryLocalManager({ serviceUrl: endpoint });

// Note: The `init`, `isServiceRunning`, and `startService` methods
// are not available in the browser version

示例用法

import { FoundryLocalManager } from "foundry-local-sdk/browser";

// Specify the service URL
// Run the Foundry Local service using the CLI: `foundry service start`
// and use the URL from the CLI output
const endpoint = "ENDPOINT";

const manager = new FoundryLocalManager({ serviceUrl: endpoint });

const alias = "qwen2.5-0.5b";

// Get all available models
const catalog = await manager.listCatalogModels();
console.log("Available models in catalog:", catalog);

// Download and load a specific model
await manager.downloadModel(alias);
await manager.loadModel(alias);

// View models in your local cache
const localModels = await manager.listLocalModels();
console.log("Cached models:", catalog);

// Check which models are currently loaded
const loaded = await manager.listLoadedModels();
console.log("Loaded models in inference service:", loaded);

// Unload a model when finished
await manager.unloadModel(alias);

C# SDK 参考

重新设计

为了提高使用设备 AI 发布应用程序的能力，从版本 0.8.0 及更高版本开始，C# SDK 的体系结构发生了重大变化。 在本部分中，我们将概述关键更改，以帮助你将应用程序迁移到最新版本的 SDK。

体系结构更改

下图显示了以前的架构（对于低于 0.8.0 的版本）如何非常依赖使用 REST Web服务器来管理模型和推理，比如聊天补全。

SDK 将使用远程过程调用（RPC）在计算机上查找 Foundry Local CLI 可执行文件，启动 Web 服务器，然后通过 HTTP 与其通信。 此体系结构有几个限制，包括：

• 管理 Web 服务器生命周期的复杂性。
• 具有挑战性的部署：最终用户需要在其计算机 和 应用程序中安装 Foundry Local CLI。
• CLI 和 SDK 的版本管理可能会导致兼容性问题。

在版本 0.8.0 及之后的版本中，为了解决这些问题，体系结构进行了重新设计，采用了更简化的方法。 新体系结构如下所示：

在此新体系结构中：

• 应用程序是独立的。 它不需要在最终用户的计算机上安装 Foundry Local CLI，因此可以更轻松地部署应用程序。
• REST Web 服务器是 可选的。 如果想要与其他通过 HTTP 通信的工具集成，仍可使用 Web 服务器。 可以查阅通过 REST 服务器与 Foundry Local 使用聊天补全以了解此功能的使用详情。
• SDK 原生 支持聊天完成和音频听录，使你可以生成依赖项较少的聊天 AI 应用程序。 有关如何使用此功能的详细信息，请阅读 Use Foundry Local native chat completions API 。
• 在 Windows 设备上，通过安装正确的运行时和驱动程序，可以使用 Windows ML 版本来处理设备上模型的硬件加速。

API 更改

从版本 0.8.0 开始及更高版本提供了更加面向对象且可组合的 API。 主要入口点仍然是 FoundryLocalManager 类，但 SDK 现在不再以一组通过静态调用无状态 HTTP API 的简单方法来实现，而是通过 FoundryLocalManager 实例公开方法，这些实例能够保持关于服务和模型的状态。

API 允许 Foundry Local 通过 Web 服务器、日志记录、缓存位置和模型变体选择进行更可配置。 例如，类 Configuration 允许为应用程序数据、模型缓存和日志设置应用程序名称、日志记录级别、Web 服务器 URL 和目录：

var config = new Configuration
{
    AppName = "app-name",
    LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
    Web = new Configuration.WebService
    {
        Urls = "http://127.0.0.1:55588"
    },
    AppDataDir = "./foundry_local_data",
    ModelCacheDir = "{AppDataDir}/model_cache",
    LogsDir = "{AppDataDir}/logs"
};

在以前版本的 Foundry Local C# SDK 中，无法直接通过 SDK 配置这些设置，这限制了自定义服务行为的能力。

项目设置指南

Foundry Local SDK 有两个 NuGet 包（WinML 和跨平台包）具有相同 的 API 图面 ，但针对不同的平台进行优化：

• Windows：使用 Microsoft.AI.Foundry.Local.WinML 特定于 Windows 应用程序的包，该包使用 Windows 机器学习 （WinML） 框架在 Windows 设备上提供最佳性能和用户体验。
• 跨平台：使用 Microsoft.AI.Foundry.Local 可用于跨平台应用程序的包（Windows、Linux、macOS）。

根据目标平台，按照以下说明创建新的 C# 应用程序并添加必要的依赖项：

按照以下特定于 Windows 或跨平台（macOS/Linux/Windows）的说明，在 C# 项目中使用 Foundry Local：

减小应用程序包大小

Foundry Local SDK 将 Microsoft.ML.OnnxRuntime.Foundry NuGet 包作为依赖项引入。 该 Microsoft.ML.OnnxRuntime.Foundry 包提供 推理运行时捆绑包，这是在特定供应商硬件设备上高效运行推理所需的库集。 推理运行时捆绑包包含以下组件：

• ONNX 运行时库：核心推理引擎 （onnxruntime.dll）。
• ONNX 运行时执行提供程序 （EP） 库。 ONNX Runtime 中的特定硬件后端，可利用硬件加速器优化并执行机器学习模型的部分内容。 例如：
  • CUDA EP： onnxruntime_providers_cuda.dll
  • QNN EP： onnxruntime_providers_qnn.dll
• 独立硬件供应商 （IHV） 库。 例如：
  • WebGPU：DirectX 依赖项 （dxcompiler.dll， dxil.dll）
  • QNN：高通 QNN 依赖项（QnnSystem.dll等等）

下表总结了哪些 EP 和 IHV 库与应用程序捆绑在一起，以及 WinML 将在运行时下载/安装的内容：

在所有平台/体系结构中，都需要 CPU EPU。 WebGPU EP 和 IHV 库大小较小（例如，WebGPU 仅向应用程序包添加约 7MB），在 Windows 和 macOS 中是必需的。 但是，CUDA 和 QNN IP 的大小很大（例如，CUDA 将 ~1GB 添加到应用程序包），因此我们建议从应用程序包 中排除 这些 IP。 如果最终用户具有兼容的硬件，WinML 将在运行时下载/安装 CUDA 和 QNN。

若要减小应用程序包的大小，可以在项目目录中创建包含以下 ExcludeExtraLibs.props 内容的文件，这在发布应用程序时不包括 CUDA 和 QNN EP 和 IHV 库：

<Project>
  <!-- we want to ensure we're using the onnxruntime libraries from Foundry Local Core so 
  we delete the WindowsAppSdk versions once they're unzipped. -->
  <Target Name="ExcludeOnnxRuntimeLibs" AfterTargets="ExtractMicrosoftWindowsAppSDKMsixFiles">
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime.dll"/>
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime_providers_shared.dll"/>
    <Message Importance="Normal" Text="Deleted onnxruntime libraries from $(MicrosoftWindowsAppSDKMsixContent)." />
  </Target>

  <!-- Remove CUDA EP and IHV libraries on Windows x64 -->
  <Target Name="ExcludeCudaLibs" Condition="'$(RuntimeIdentifier)'=='win-x64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <!-- match onnxruntime*cuda.* (we're matching %(Filename) which excludes the extension) -->
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^onnxruntime.*cuda.*', RegexOptions.IgnoreCase))" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime CUDA libraries from package." />
  </Target>

  <!-- Remove QNN EP and IHV libraries on Windows arm64 -->
  <Target Name="ExcludeQnnLibs" Condition="'$(RuntimeIdentifier)'=='win-arm64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)%(Extension)', 
                                      '^QNN.*\.dll', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^libQNNhtp.*', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="'%(FileName)%(Extension)' == 'onnxruntime_providers_qnn.dll'" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime QNN libraries from package." />
  </Target>

  <!-- need to manually copy on linux-x64 due to the nuget packages not having the correct props file setup -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <!-- 'Update' as the Core package will add these dependencies, but we want to be explicit about the version -->
    <PackageReference Update="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Update="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
    <OrtNativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntime.gpu.linux/$(OnnxRuntimeVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
    <OrtGenAINativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntimegenai.cuda/$(OnnxRuntimeGenAIVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
  </ItemGroup>

  <Target Name="CopyOrtNativeLibs" AfterTargets="Build" Condition=" '$(RuntimeIdentifier)' == 'linux-x64'">
    <Copy SourceFiles="@(OrtNativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
    <Copy SourceFiles="@(OrtGenAINativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
  </Target>
</Project>

在项目文件中（.csproj）添加以下行以导入 ExcludeExtraLibs.props 该文件：

<!-- other project file content -->
  
<Import Project="ExcludeExtraLibs.props" />

Linux：CUDA 依赖项

CUDA EP 通过 Microsoft.ML.OnnxRuntime.Foundry 引入你的 Linux 应用程序，但我们不包含 IHV 库。 如果要允许启用了 CUDA 的设备的最终用户从更高的性能中受益，需要将以下 CUDA IHV 库 添加到 应用程序：

• CUBLAS v12.8.4 （从 NVIDIA 开发人员下载）
  • cublas64_12.dll
  • cublasLt64_12.dll
• CUDA RT v12.8.90 （从 NVIDIA 开发人员下载）
  • cudart64_12.dll
• CUDNN v9.8.0 （从 NVIDIA 开发人员下载）
  • cudnn_graph64_9.dll
  • cudnn_ops64_9.dll
  • cudnn64_9.dll
• CUDA FFT v11.3.3.83 （可从 NVIDIA 开发者中心下载）
  • cufft64_11.dll

Samples

• 有关演示如何使用 Foundry 本地 C# SDK 的示例应用程序，请参阅 Foundry Local C# SDK 示例 GitHub 存储库。

API 参考

• 有关 Foundry Local C# SDK 的更多详细信息，请参阅 Foundry Local C# SDK API 参考。

Rust SDK 参考

Rust SDK for Foundry Local 提供了一种管理模型、控制缓存以及与 Foundry Local 服务交互的方法。

安装

若要使用 Foundry Local Rust SDK，请将以下内容添加到你的 Cargo.toml位置：

[dependencies]
foundry-local-sdk = "0.1"

或者，可以使用 cargo 添加 Foundry Local Crate：

cargo add foundry-local

FoundryLocalManager

面向 Foundry Local SDK 操作的管理器。

领域

• service_uri: Option<String> — Foundry 服务的 URI。
• client: Option<HttpClient> — API 请求的 HTTP 客户端。
• catalog_list: Option<Vec<FoundryModelInfo>> — 目录模型的缓存列表。
• catalog_dict: Option<HashMap<String, FoundryModelInfo>> - 目录模型的缓存字典。
• timeout: Option<u64> - 可选的 HTTP 客户端超时。

方法

• pub fn builder() -> FoundryLocalManagerBuilder
  为 FoundryLocalManager 创建新的生成器。

• pub fn service_uri(&self) -> Result<&str>
  获取服务 URI 地址。
  返回：Foundry 服务的 URI。

• fn client(&self) -> Result<&HttpClient>
  获取 HTTP 客户端实例。
  返回：HTTP 客户端。

• pub fn endpoint(&self) -> Result<String>
  获取服务的终结点。
  返回：终结点 URL。

• pub fn api_key(&self) -> String
  获取用于身份验证的 API 密钥。
  返回： API 密钥。

• pub fn is_service_running(&mut self) -> bool
  检查服务是否正在运行，并设置服务 URI（如果找到）。
  返回：true（如果运行），否则返回 false。

• pub fn start_service(&mut self) -> Result<()>
  启动 Foundry 本地服务。

• pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
  获取目录中可用模型的列表。

• pub fn refresh_catalog(&mut self)
  刷新目录缓存。

• pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
  按别名或 ID 获取模型信息。
  参数：

  • alias_or_model_id：别名或模型 ID。
  • raise_on_not_found：如果为 true，则为错误（如果找不到）。

• pub async fn get_cache_location(&self) -> Result<String>
  以字符串的形式获取缓存位置。

• pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
  列出缓存的模型。

• pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
  下载模型。
  参数：

  • alias_or_model_id：别名或模型 ID。
  • token：可选身份验证令牌。
  • force：如果缓存了，则强制重新下载。

• pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
  加载用于推理的模型。
  参数：

  • alias_or_model_id：别名或模型 ID。
  • ttl：可选的生存时间（以秒为单位）。

• pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
  卸载模型。
  参数：

  • alias_or_model_id：别名或模型 ID。
  • force：强制卸载（即使正在使用）。

• pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
  列出加载的模型。

FoundryLocalManagerBuilder

用于创建实例的 FoundryLocalManager 生成器。

领域

• alias_or_model_id: Option<String> - 要下载和加载的别名或模型 ID。
• bootstrap: bool — 是否在未运行的情况下启动服务。
• timeout_secs: Option<u64> — HTTP 客户端超时（以秒为单位）。

方法

• pub fn new() -> Self
  创建新的生成器实例。

• pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
  设置要下载和加载的别名或模型 ID。

• pub fn bootstrap(mut self, bootstrap: bool) -> Self
  设置是否在未运行时启动服务。

• pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
  设置 HTTP 客户端超时（以秒为单位）。

• pub async fn build(self) -> Result<FoundryLocalManager>
  生成 FoundryLocalManager 实例。

FoundryModelInfo

表示有关模型的信息。

领域

• alias: String — 模型别名。
• id: String — 模型 ID。
• version: String — 模型版本。
• runtime: ExecutionProvider — 执行提供程序（CPU、CUDA 等）。
• uri: String — 模型 URI。
• file_size_mb: i32 — 模型文件大小（以 MB 为单位）。
• prompt_template: serde_json::Value —— 模型的提示模板。
• provider: String - 提供程序名称。
• publisher: String — 发布者名称。
• license: String — 许可证类型。
• task: String — 模型任务（例如文本生成）。

方法

• from_list_response(response: &FoundryListResponseModel) -> Self
  根据目录响应创建 FoundryModelInfo。

• to_download_body(&self) -> serde_json::Value
  将模型信息转换为用于下载请求的 JSON 正文。

ExecutionProvider

支持的执行提供程序的枚举。

• CPU
• WebGPU
• CUDA
• QNN

方法

• get_alias(&self) -> String
  返回执行提供程序的字符串别名。

ModelRuntime

描述模型的运行时环境。

• device_type: DeviceType
• execution_provider: ExecutionProvider