Foundry 本地 SDK 遷移指南

本指南提供將程式碼從舊版 Foundry Local SDK 遷移到目前版本的指引。 新 SDK 移除了對 Foundry 本地 CLI 的依賴，因此讓您能在不需使用者安裝 CLI 或設定本地 Foundry 環境的情況下，直接發佈應用程式。 新 SDK 也對 API 進行了改進，以提升可用性與效能。

C# SDK 遷移指南

為了提升你使用裝置 AI 發佈應用程式的能力，C# SDK 的架構在版本 0.8.0 及之後版本中進行了重大變更。 在本節中，我們將概述主要變更，幫助您將應用程式遷移到最新版本的 SDK。

備註

在 SDK 版本 0.8.0 及之後，API 與先前版本<=0.3.0有破壞性的變更（）。

下圖展示了先前架構—在更早 0.8.0 版本中 —如何大量依賴使用 REST 網頁伺服器來管理模型與推論，例如聊天完成：

SDK 會使用遠端程序呼叫（RPC）在機器上尋找 Foundry Local CLI 執行檔，啟動網頁伺服器，然後透過 HTTP 與它通訊。 此架構存在多項限制，包括：

• 管理網頁伺服器生命週期的複雜性。
• 部署困難：終端使用者必須在他們的機器和應用程式上安裝 Foundry Local CLI。
• CLI 與 SDK 的版本管理可能導致相容性問題。

為了解決這些問題，重新設計的 0.8.0 架構版本及後續版本採用了更精簡的方法。 新架構如下：

在這個新架構中：

• 你的應用程式是自給自足的。 它不需要將 Foundry 本地 CLI 單獨安裝在終端使用者的機器上，讓你更容易部署應用程式。
• REST 網頁伺服器是 可選的。 如果你想和其他透過 HTTP 通訊的工具整合，仍然可以使用網頁伺服器。 請閱讀「透過 REST 伺服器使用 Foundry Local 進行聊天補全」的詳細資訊，了解如何使用此功能。
• SDK 原生 支援聊天完成與音訊轉錄，讓您能以較少依賴建立對話式 AI 應用程式。 請參閱 Use Foundry Local 本地聊天完成 API 以了解如何使用此功能。
• 在 Windows 裝置上，你可以使用 Windows 的機器學習版本，透過引入正確的執行時和驅動程式來處理裝置上模型的硬體加速。

API 變更

版本 0.8.0 及以後的版本提供更物件導式且可組合的 API。 主要入口仍然是類別FoundryLocalManager，但現在不再是一組以靜態方式呼叫無狀態 HTTP API 的方法。SDK 現在會在FoundryLocalManager實例上，暴露用於維護服務與模型狀態的方法。

原始	版本 < 0.8.0	版本 >等於 0.8.0
Configuration	不適用	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 在網頁伺服器、日誌記錄、快取位置及型號變體選擇上更具可配置性。 例如，這個 Configuration 類別允許你設定應用程式名稱、日誌層級、網頁伺服器網址，以及應用程式資料、模型快取和日誌的目錄：

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 REFERENCE。

JavaScript SDK 遷移指南

為了提升您使用裝置 AI 發佈應用程式的能力，JavaScript SDK 的架構有重大變更。 在本節中，我們將概述主要變更，幫助您將應用程式遷移到最新版本的 SDK。

備註

在 JavaScript SDK 版本 0.9.0 及之後，API 與先前版本 <=0.5.0 有重大變更。

下圖顯示先前的架構如何大量依賴使用 REST 網路伺服器來管理推論模型與推論過程，例如聊天補全：

SDK 會使用遠端程序呼叫（RPC）在機器上尋找 Foundry Local CLI 執行檔，啟動網頁伺服器，然後透過 HTTP 與它通訊。 此架構存在多項限制，包括：

• 管理網頁伺服器生命週期的複雜性。
• 部署困難：終端使用者必須在他們的機器和應用程式上安裝 Foundry Local CLI。
• CLI 與 SDK 的版本管理可能導致相容性問題。

為了解決這些問題，重新設計的架構採用了更精簡的方法。 新架構如下：

在這個新架構中：

• 你的應用程式是自給自足的。 它不需要將 Foundry 本地 CLI 單獨安裝在終端使用者的機器上，讓你更容易部署應用程式。
• REST 網頁伺服器是 可選的。 如果你想和其他透過 HTTP 通訊的工具整合，仍然可以使用網頁伺服器。
• SDK 原生 支援聊天完成與音訊轉錄，讓您能以較少依賴建立對話式 AI 應用程式。

API 變更

最新版本提供了更物件導向且可組合的 API。 主要入口仍然是類別FoundryLocalManager，但現在不再是一組以靜態方式呼叫無狀態 HTTP API 的方法。SDK 現在會在FoundryLocalManager實例上，暴露用於維護服務與模型狀態的方法。

原始	先前版本	目前的版本
Configuration	不適用	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 在網頁伺服器、日誌記錄、快取位置及型號變體選擇上更具可配置性。 例如，允許 config 你設定應用程式名稱、日誌層級、網頁伺服器網址，以及應用程式資料、模型快取和日誌的目錄：

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）中，API 與先前版本（<=0.5.1）有破壞性變更。

下圖顯示先前的架構如何大量依賴使用 REST 網路伺服器來管理推論模型與推論過程，例如聊天補全：

SDK 會使用遠端程序呼叫（RPC）在機器上尋找 Foundry Local CLI 執行檔，啟動網頁伺服器，然後透過 HTTP 與它通訊。 此架構存在多項限制，包括：

• 管理網頁伺服器生命週期的複雜性。
• 部署困難：終端使用者必須在他們的機器和應用程式上安裝 Foundry Local CLI。
• CLI 與 SDK 的版本管理可能導致相容性問題。

為了解決這些問題，重新設計的架構採用了更精簡的方法。 新架構如下：

在這個新架構中：

• 你的應用程式是自給自足的。 它不需要將 Foundry 本地 CLI 單獨安裝在終端使用者的機器上，讓你更容易部署應用程式。
• REST 網頁伺服器是 可選的。 如果你想和其他透過 HTTP 通訊的工具整合，仍然可以使用網頁伺服器。
• 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
Configuration	不適用	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 在網頁伺服器、日誌記錄、快取位置及型號變體選擇上更具可配置性。 例如，這個 Configuration 類別允許你設定應用程式名稱、日誌層級、網頁伺服器網址，以及應用程式資料、模型快取和日誌的目錄：

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 網路伺服器來管理推論模型與推論過程，例如聊天補全：

SDK 會使用遠端程序呼叫（RPC）來尋找機器上的 Foundry 本地 CLI 執行檔，啟動網頁伺服器，然後透過 HTTP 與之通訊。 此架構存在多項限制，包括：

• 管理網頁伺服器生命週期的複雜性。
• 部署困難：終端使用者必須在他們的機器和應用程式上安裝 Foundry Local CLI。
• CLI 與 SDK 的版本管理可能導致相容性問題。

為了解決這些問題，重新設計的架構採用了更精簡的方法。 新架構如下：

在這個新架構中：

• 你的應用程式是自給自足的。 它不需要將 Foundry 本地 CLI 單獨安裝在終端使用者的機器上，讓你更容易部署應用程式。
• REST 網頁伺服器是 可選的。 如果你想和其他透過 HTTP 通訊的工具整合，仍然可以使用網頁伺服器。
• SDK 原生 支援聊天完成與音訊轉錄，讓您能以較少依賴建立對話式 AI 應用程式。

API 變更

最新版本提供了更物件導向且可組合的 API。 建構模式已被基於配置的方式取代，模型管理現在使用專用 Model 物件。

原始	先前版本（foundry-local）	現行版本（foundry-local-sdk）
籠子	foundry-local	foundry-local-sdk
Configuration	不適用	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 （手動休止）	原生 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 完成聊天功能