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。

服务管理

目录管理

缓存管理

模型管理

示例用法

以下代码演示如何使用 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 参考

安装

若要使用 Foundry 本地 C# SDK，需要安装 NuGet 包：

dotnet add package Microsoft.AI.Foundry.Local

有关别名的注释

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

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

枚举

DeviceType

表示用于模型执行的设备的类型。

ExecutionProvider

表示模型推理的执行提供程序。

FoundryLocalManager 类

管理模型、缓存和 Foundry 本地服务的主要入口点。

建筑

var manager = new FoundryLocalManager();

属性

服务管理

启动服务

await manager.StartServiceAsync(CancellationToken.None);

启动 Foundry Local 服务（如果尚未运行）。

停止服务

await manager.StopServiceAsync(CancellationToken.None);

停止 Foundry Local 服务。

启动和加载模型（静态帮助程序）

var manager = await FoundryLocalManager.StartModelAsync("aliasOrModelId");

启动服务并加载指定的模型。

目录管理

列出所有目录模型

List<ModelInfo> models = await manager.ListCatalogModelsAsync();

返回目录中的所有可用模型。

刷新目录

manager.RefreshCatalog();

清除缓存的目录，以便在下次访问时重新加载它。

按别名或 ID 获取模型信息

ModelInfo? info = await manager.GetModelInfoAsync("aliasOrModelId");

返回模型信息或 null (如果找不到)。

缓存管理

获取缓存位置

string cachePath = await manager.GetCacheLocationAsync();

返回缓存模型的目录路径。

列出缓存的模型

List<ModelInfo> cached = await manager.ListCachedModelsAsync();

返回下载到本地缓存的模型。

模型管理

下载模型

ModelInfo? model = await manager.DownloadModelAsync("aliasOrModelId");

将模型下载到本地缓存。

下载带有进度指示的模型

await foreach (var progress in manager.DownloadModelWithProgressAsync("aliasOrModelId"))
{
    // progress.Percentage, progress.Status, etc.
}

流式传输下载进度更新。

加载模型

ModelInfo loaded = await manager.LoadModelAsync("aliasOrModelId");

将模型加载到推理服务器。

列出加载的模型

List<ModelInfo> loaded = await manager.ListLoadedModelsAsync();

列出服务中当前加载的所有模型。

卸载模型

await manager.UnloadModelAsync("aliasOrModelId");

从推理服务器中卸载模型。

处理

同时实现 IDisposable 和 IAsyncDisposable 以正确进行清理。

manager.Dispose();
// or
await manager.DisposeAsync();

模型类型

本页记录 Foundry Local C# SDK 用于描述模型、下载和运行时信息的关键数据类型。

PromptTemplate

表示模型的提示模板。

Runtime

描述模型的运行时环境。

ModelSettings

表示特定于模型的参数。

ModelInfo

介绍 Foundry Local 目录或缓存中的模型。

ModelDownloadProgress

表示模型下载作业的进度。

静态方法：

• Progress(double percentage)：创建进度更新。
• Completed(ModelInfo modelInfo)：生成已完成的进度结果。
• Error(string errorMessage)：创建错误结果。

示例用法

using Microsoft.AI.Foundry.Local;

var manager = new FoundryLocalManager();
await manager.StartServiceAsync();

var models = await manager.ListCatalogModelsAsync();
var alias = "qwen2.5-0.5b";

await manager.DownloadModelAsync(alias);
await manager.LoadModelAsync(alias);

var loaded = await manager.ListLoadedModelsAsync();

await manager.UnloadModelAsync(alias);

manager.Dispose();

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