Foundry 本地 SDK 迁移指南

本指南提供有关将代码从旧版 Foundry Local SDK 迁移到当前版本的说明。 新 SDK 会删除 Foundry 本地 CLI 上的依赖项，因此，无需用户安装 CLI 或设置本地 Foundry 环境即可交付应用程序。 新 SDK 还包括对 API 的改进，以提高可用性和性能。

C# SDK 迁移指南

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

注释

在 SDK 版本 0.8.0 及更高版本中，与之前版本（<=0.3.0）相比，API 存在重大变更。

下图显示了以前的架构（对于低于 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 实例公开方法，这些实例能够保持关于服务和模型的状态。

原始	版本 < 0.8.0	版本 >= 0.8.0
配置	不适用	config = Configuration(...)
获取管理器	mgr = FoundryLocalManager();	await FoundryLocalManager.CreateAsync(config, logger); var mgr = FoundryLocalManager.Instance;
获取目录	不适用	catalog = await mgr.GetCatalogAsync();
列出模型	mgr.ListCatalogModelsAsync();	catalog.ListModelsAsync();
获取模型	mgr.GetModelInfoAsync("aliasOrModelId");	catalog.GetModelAsync(alias: "alias");
获取变体	不适用	model.SelectedVariant;
设置变体	不适用	model.SelectVariant();
下载模型	mgr.DownloadModelAsync("aliasOrModelId");	model.DownloadAsync()
加载模型	mgr.LoadModelAsync("aliasOrModelId");	model.LoadAsync()
卸载模型	mgr.UnloadModelAsync("aliasOrModelId");	model.UnloadAsync()
列出加载的模型	mgr.ListLoadedModelsAsync();	catalog.GetLoadedModelsAsync();
获取模型路径	不适用	model.GetPathAsync()
启动服务	mgr.StartServiceAsync();	mgr.StartWebServerAsync();
停止服务	mgr.StopServiceAsync();	mgr.StopWebServerAsync();
缓存位置	mgr.GetCacheLocationAsync();	config.ModelCacheDir
列出缓存的模型	mgr.ListCachedModelsAsync();	catalog.GetCachedModelsAsync();

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"
};

API 参考

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

JavaScript SDK 迁移指南

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

注释

在 JavaScript SDK 0.9.0 及更高版本中，API 相对于先前版本（<=0.5.0）发生了重大变更。

下图显示了先前的体系结构如何严重依赖使用 REST Web 服务器来管理模型和推理，例如聊天完成。

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

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

为了解决这些问题，重新设计的体系结构使用更简化的方法。 新体系结构如下所示：

在此新体系结构中：

• 应用程序是独立的。 它不需要在最终用户的计算机上安装 Foundry Local CLI，因此可以更轻松地部署应用程序。
• REST Web 服务器是 可选的。 如果想要与其他通过 HTTP 通信的工具集成，仍可使用 Web 服务器。
• SDK 原生 支持聊天完成和音频听录，使你可以生成依赖项较少的聊天 AI 应用程序。

API 更改

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

原始	以前的版本	当前版本
配置	不适用	config = { appName: "app-name", ... }
获取管理器	mgr = new FoundryLocalManager();	mgr = FoundryLocalManager.create(config);
获取目录	不适用	catalog = mgr.catalog;
列出模型	mgr.listCatalogModels();	catalog.getModels();
获取模型	mgr.getModelInfo("aliasOrModelId");	catalog.getModel(alias);
获取变体	不适用	model.id;
设置变体	不适用	model.selectVariant(modelId);
下载模型	mgr.downloadModel("aliasOrModelId");	model.download();
加载模型	mgr.loadModel("aliasOrModelId");	model.load();
卸载模型	mgr.unloadModel("aliasOrModelId");	model.unload();
列出加载的模型	mgr.listLoadedModels();	catalog.getLoadedModels();
获取模型路径	不适用	model.path;
启动服务	mgr.startService();	mgr.startWebService();
停止服务	不适用	mgr.stopWebService();
缓存位置	mgr.getCacheLocation();	config.modelCacheDir
列出缓存的模型	mgr.listCachedModels();	catalog.getCachedModels();

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

const config = {
  appName: "app-name",
  logLevel: "info",
  webServiceUrls: "http://127.0.0.1:55588",
  appDataDir: "./foundry_local_data",
  modelCacheDir: "{appDataDir}/model_cache",
  logsDir: "{appDataDir}/logs",
};

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

参考

• 与推理 SDK 集成
• 使用 Foundry Local 原生聊天完成 API

Python SDK 迁移指南

为了提高使用设备 AI 交付应用程序的能力，Python SDK 的体系结构发生了重大更改。 在本部分中，我们将概述关键更改，以帮助你将应用程序迁移到最新版本的 SDK。

注释

在最新的 Python SDK 版本（1.0.0）中，与之前版本（<=0.5.1）相比，API 存在重大变更。

下图显示了先前的体系结构如何严重依赖使用 REST Web 服务器来管理模型和推理，例如聊天完成。

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

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

为了解决这些问题，重新设计的体系结构使用更简化的方法。 新体系结构如下所示：

在此新体系结构中：

• 应用程序是独立的。 它不需要在最终用户的计算机上安装 Foundry Local CLI，因此可以更轻松地部署应用程序。
• REST Web 服务器是 可选的。 如果想要与其他通过 HTTP 通信的工具集成，仍可使用 Web 服务器。
• SDK 原生 支持聊天完成和音频听录，使你可以生成依赖项较少的聊天 AI 应用程序。

API 更改

最新版本提供更面向对象的可组合 API。 主要入口点仍然是 FoundryLocalManager 类，但初始化模式、模型管理和推理都发生了重大变化。

原始	以前的版本 （foundry-local）	当前版本 （foundry-local-sdk）
包	pip install foundry-local	pip install foundry-local-sdk
进口	from foundry_local import FoundryLocalManager	from foundry_local_sdk import Configuration, FoundryLocalManager
配置	不适用	config = Configuration(app_name="app-name")
获取管理器	manager = FoundryLocalManager(alias)	FoundryLocalManager.initialize(config) manager = FoundryLocalManager.instance
获取目录	不适用	catalog = manager.catalog
列出模型	manager.list_catalog_models()	catalog.list_models()
获取模型	manager.get_model_info(alias)	catalog.get_model(alias)
下载模型	manager.download_model(alias)	model.download(progress_callback)
加载模型	manager.load_model(alias)	model.load()
卸载模型	manager.unload_model(alias)	model.unload()
列出加载的模型	manager.list_loaded_models()	catalog.get_loaded_models()
列出缓存的模型	manager.list_cached_models()	catalog.get_cached_models()
缓存位置	manager.get_cache_location()	config.model_cache_dir
启动服务	manager.start_service()	manager.start_web_service()
服务终结点	manager.endpoint	manager.urls

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

from foundry_local_sdk import Configuration

config = Configuration(
    app_name="app-name",
    log_level="info",
    web={"urls": "http://127.0.0.1:55588"},
    model_cache_dir="./foundry_local_data/model_cache",
)

参考

• 使用 REST 服务器生成聊天回复
• 使用 Foundry Local 原生聊天完成 API

Rust SDK 迁移指南

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

注释

在最新的 Rust SDK 版本（1.0.0）中，API 与以前版本相比有重大变更。 箱名称已从foundry-local更改为foundry-local-sdk。

下图显示了先前的体系结构如何严重依赖使用 REST Web 服务器来管理模型和推理，例如聊天完成。

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

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

为了解决这些问题，重新设计的体系结构使用更简化的方法。 新体系结构如下所示：

在此新体系结构中：

• 应用程序是独立的。 它不需要在最终用户的计算机上安装 Foundry Local CLI，因此可以更轻松地部署应用程序。
• REST Web 服务器是 可选的。 如果想要与其他通过 HTTP 通信的工具集成，仍可使用 Web 服务器。
• SDK 原生 支持聊天完成和音频听录，使你可以生成依赖项较少的聊天 AI 应用程序。

API 更改

最新版本提供更面向对象的可组合 API。 生成器模式已替换为基于配置的方法，模型管理现在使用专用 Model 对象。

原始	以前的版本 （foundry-local）	当前版本 （foundry-local-sdk）
箱子	foundry-local	foundry-local-sdk
配置	不适用	FoundryLocalConfig::new("app-name")
获取管理器	FoundryLocalManager::builder().build().await?	FoundryLocalManager::create(config)?
获取目录	不适用	manager.catalog()
列出模型	manager.list_catalog_models().await?	manager.catalog().get_models().await?
获取模型	manager.get_model_info(alias).await?	manager.catalog().get_model(alias).await?
下载模型	manager.download_model(alias).await?	model.download(callback).await?
加载模型	manager.load_model(alias).await?	model.load().await?
卸载模型	manager.unload_model(alias).await?	model.unload().await?
列出加载的模型	manager.list_loaded_models().await?	manager.catalog().get_loaded_models().await?
列出缓存的模型	manager.list_cached_models().await?	manager.catalog().get_cached_models().await?
启动服务	manager.start_service()?	manager.start_web_service().await?
终结点	manager.endpoint()?	manager.urls()
HTTP 调用	reqwest::Client （手动 REST）	本机 SDK： model.create_chat_client()

新 SDK 提供本机聊天和音频客户端，在大多数情况下无需手动 HTTP 请求：

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

let config = FoundryLocalConfig::new("app-name");
let manager = FoundryLocalManager::create(config)?;

let model = manager.catalog().get_model("qwen2.5-0.5b").await?;
model.download(None).await?;
model.load().await?;

// Native chat client - no HTTP server needed
let client = model.create_chat_client().temperature(0.7).max_tokens(256);

参考

• 使用 REST 服务器生成聊天回复
• 使用 Foundry Local 原生聊天完成 API