Foundry 本地 SDK 參考

Foundry Local SDK 讓你能透過簡單直覺的 API 在應用程式中提供使用本地 AI 模型的 AI 功能。 SDK 抽象化了管理 AI 模型的複雜性,並提供無縫的體驗,將本地 AI 能力整合進您的應用程式。 本參考資料說明了 C#、C++、JavaScript、Python 及 Rust 的 SDK 實作。

SDK 不需要在終端使用者機器上安裝 Foundry 本地 CLI,讓你能直接發佈應用程式,無需額外設定步驟——你的應用程式是自成一體的。 Foundry Local SDK 的額外好處包括:

  • 硬體偵測與優化:自動評估 GPU、NPU 與 CPU 的能力。
  • 執行提供者管理(Windows):根據裝置能力自動下載並註冊適當的 ONNX 執行時執行提供者(CUDA、Vitis、QNN、OpenVINO、TensorRT)。
  • 透過 WebGpu 的 Metal 支援 (macOS):原生支援在 Apple Silicon 上執行模型,並提供最佳化效能。
  • 模型擷取:從 Foundry 模型目錄無縫下載,具備版本控制、更新,以及具備後援支援的自動硬體最佳化模型選取功能。
  • 高效執行時:應用程式容量增加約 20 MB,可於手機到桌機等裝置上運行。
  • OpenAI API 相容性:與 OpenAI 模型及工具輕鬆整合。
  • 可選的 REST 伺服器:將 Foundry Local 作為本地服務執行,供其他應用程式存取。

C# SDK 參考

安裝套件

dotnet add package Microsoft.AI.Foundry.Local
dotnet add package OpenAI

GitHub 倉庫裡的 C# 範例都是預先設定好的專案。 如果你是從零開始建立,建議閱讀 Foundry Local SDK 參考資料 ,了解更多如何用 Foundry Local 設定 C# 專案的細節。

專案配置

範例儲存庫包含一個 .csproj 自動處理平台偵測的檔案。 如果你是從零開始建構專案,請參考以下設定:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- Windows: target Windows SDK for WinML hardware acceleration -->
  <PropertyGroup Condition="$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0-windows10.0.19041.0</TargetFramework>
    <Platforms>ARM64;x64</Platforms>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

  <!-- Non-Windows: standard .NET -->
  <PropertyGroup Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(RuntimeIdentifier)'==''">
    <RuntimeIdentifier>$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local" />
  </ItemGroup>

  <!-- Linux GPU support -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <PackageReference Include="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Include="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
  </ItemGroup>

  <!-- Shared utilities -->
  <ItemGroup>
    <Compile Include="../Shared/*.cs" />
  </ItemGroup>

</Project>

下表說明了主要專案設定:

Setting 說明
TargetFramework 針對範例所需的 .NET 版本。
RuntimeIdentifier 預設為目前 SDK 的執行階段識別碼,確保選取正確的平台二進位檔。
Microsoft.AI.Foundry.Local Foundry 本地 SDK 套件適用於 Windows、macOS 和 Linux。

快速入門

使用此片段驗證 SDK 是否能初始化並存取本地模型目錄。

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging;
using System.Linq;

var config = new Configuration
{
  AppName = "app-name",
  LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
};

using var loggerFactory = LoggerFactory.Create(builder =>
{
  builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();

await FoundryLocalManager.CreateAsync(config, logger);
var manager = FoundryLocalManager.Instance;

var catalog = await manager.GetCatalogAsync();
var models = await catalog.ListModelsAsync();

Console.WriteLine($"Models available: {models.Count()}");

這個範例列印出你硬體可用的模型數量。

範例

API 參考資料

原生音訊轉錄 API

C# SDK 內建音訊用戶端,可使用 Whisper 模型在裝置上轉錄音訊檔案。 這會在過程中執行推論,無需 REST 網頁伺服器。

買一個音訊客戶端

載入 Whisper 模型後,取得音訊用戶端:

var audioClient = await model.GetAudioClientAsync();

音訊轉錄方法

方法 Signature 說明
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> 轉錄結果以串流方式逐段提供。 每個區塊都有一個 Text 屬性。

AudioClient 設定

房產 類型 說明
Language string ISO 639-1 語言代碼(例如, "en")。 提升準確度。
Temperature float 取樣溫度(0.0–1.0)。 較低的數值則更具確定性。

範例

var audioClient = await model.GetAudioClientAsync();
audioClient.Settings.Language = "en";
audioClient.Settings.Temperature = 0.0f;

await foreach (var chunk in audioClient.TranscribeAudioStreamingAsync(
    "recording.mp3", CancellationToken.None))
{
    Console.Write(chunk.Text);
}

參考:

JavaScript SDK 參考

安裝套件

npm install foundry-local-sdk openai

快速入門

使用此片段驗證 SDK 是否能初始化並存取本地模型目錄。

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

console.log('Initializing Foundry Local SDK...');

const manager = FoundryLocalManager.create({
    appName: 'foundry_local_samples',
    logLevel: 'info'
});
console.log('✓ SDK initialized successfully');

// Explore available models
console.log('\nFetching available models...');
const catalog = manager.catalog;
const models = await catalog.getModels();

console.log(`Found ${models.length} models:`);
for (const model of models) {
    console.log(`  - ${model.alias}`);
}

這個範例會輸出你硬體可用型號的清單。

範例

API 參考資料

參考資料

Python SDK 指南

安裝套件

pip install foundry-local-sdk openai

快速入門

使用此片段驗證 SDK 是否能初始化並存取本地模型目錄。

import asyncio
from foundry_local_sdk import Configuration, FoundryLocalManager


async def main():
    config = Configuration(app_name="app-name")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    models = manager.catalog.list_models()
    print(f"Models available: {len(models)}")


if __name__ == "__main__":
    asyncio.run(main())

這個範例列印出你硬體可用的模型數量。

範例

Configuration

這個 Configuration 類別允許你自訂 SDK 的行為:

from foundry_local_sdk import Configuration

config = Configuration(
    app_name="app-name",
    log_level="info",
    model_cache_dir="./foundry_local_data/model_cache",
    web={"urls": "http://127.0.0.1:55588"},
)
參數 類型 說明
app_name str 你的申請名稱。
log_level str 記錄層級 (例如:例如 "info"、"debug")。
model_cache_dir str 快取模型目錄。
web dict 使用urls鍵值進行網路服務配置。

核心 API

方法 說明
FoundryLocalManager.initialize(config) 用Configuration初始化單例管理器。
FoundryLocalManager.instance 存取已初始化的管理者實例。
manager.catalog.list_models() 列出目錄中所有可購買的車型。
manager.catalog.get_model(alias) 使用別名取得模型。
manager.catalog.get_cached_models() 列出本地快取中的模型。
manager.catalog.get_loaded_models() 目前已載入的模型清單。
model.download(progress_callback) 下載模型 (若有快取則跳過)。
model.load() 載入模型進行推論。
model.unload() 卸下模型。
model.is_cached 檢查模型是否已於本機快取。
model.is_loaded 檢查模型是否已載入。

原生聊天完成 API

載入模型後,開啟聊天客戶端:

client = model.get_chat_client()
方法 說明
client.complete_chat(messages) 產生完整的聊天回覆。
client.complete_streaming_chat(messages) 串流聊天回應片段。

原生音訊轉錄 API

載入 Whisper 模型後,取得音訊用戶端:

audio_client = model.get_audio_client()
方法 說明
audio_client.transcribe(file_path) 轉錄一段音訊檔案。 回傳一個帶有屬性 text 的物件。

參考:

Rust SDK 參考

安裝套件

cargo add foundry-local-sdk
cargo add tokio --features full
cargo add tokio-stream anyhow

快速入門

使用此片段驗證 SDK 是否能初始化並存取本地模型目錄。

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manager = FoundryLocalManager::create(FoundryLocalConfig::new("app-name"))?;

    let models = manager.catalog().get_models().await?;
    println!("Models available: {}", models.len());

    Ok(())
}

這個範例列印出你硬體可用的模型數量。

範例

Configuration

這個 FoundryLocalConfig 結構體允許你自訂 SDK 的行為:

use foundry_local_sdk::FoundryLocalConfig;

let config = FoundryLocalConfig::new("app-name")
    .with_log_level("info")
    .with_model_cache_dir("./foundry_local_data/model_cache")
    .with_web_urls("http://127.0.0.1:55588");

核心 API

方法 說明
FoundryLocalManager::create(config) 用 FoundryLocalConfig建立一個新的管理器。
manager.catalog().get_models().await 列出所有可用型號。
manager.catalog().get_model(alias).await 使用別名取得模型。
manager.catalog().get_cached_models().await 列出本地快取中的模型。
manager.catalog().get_loaded_models().await 目前已載入的模型清單。
model.download(callback).await 下載模型 (若有快取則跳過)。
model.load().await 載入模型進行推論。
model.unload().await 卸下模型。

原生聊天完成 API

載入模型後,建立一個帶有可選設定的聊天客戶端:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
方法 說明
client.complete_chat(&messages, tools).await 產生完整的聊天回覆。
client.complete_streaming_chat(&messages, tools).await 串流聊天回應片段。

訊息類型: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage。

原生音訊轉錄 API

載入 Whisper 模型後,建立音訊客戶端:

let audio_client = model.create_audio_client();
方法 說明
audio_client.transcribe(file_path).await 轉錄一段音訊檔案。 回傳一個帶有 text 欄位的物件。

參考:

C++ SDK 參考

Prerequisites

C++ SDK 為原生 Foundry Local 執行階段提供純標頭包裝器。 你已部署的應用程式不需要 Foundry 本地 CLI 或 .NET 執行時。

複製原生聊天範例,以開始使用已設定好的 CMake 專案:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/native-chat-completions

C++ 範例需要:

  • CMake 3.20 或更新版本。
  • 一個 C++20 編譯器。
  • PATH 上的 NuGet CLI。

配置並建立樣本:

cmake -S . -B build
cmake --build build --config Release

在組態期間,範本會將 2.2.1 版的 Microsoft.AI.Foundry.Local.RuntimeNuGet 套件還原到 build/_packages。 該套件包含 Windows、Linux 和 macOS 的 C++ 標頭及原生函式庫。 你不需要另外的 WinML 套件。

CMake 設定會選擇適用於您的作業系統與架構的執行階段資產,並將所需的原生函式庫複製到執行檔旁。 在 macOS 和 Linux 上,從 build 執行該可執行檔。 在 Windows 上,從 build 執行 .exe 檔案。

選擇與你的應用程式的作業系統和架構相符的原生資產:

作業系統 Architecture 執行階段識別碼(RID)
Windows x64 或 ARM64 win-x64 或 win-arm64
Linux x64 或 ARM64 linux-x64 或 linux-arm64
macOS 蘋果矽(ARM64) osx-arm64

新增 build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include 至您編譯器的包含路徑。 連結來自套件的原生程式庫 build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native 目錄:

  • foundry_local.lib在 Windows 上。
  • libfoundry_local.so 在 Linux 上。
  • libfoundry_local.dylib 在 macOS 上。

將相應的原生執行時與相依函式庫部署在可執行檔旁或平台函式庫搜尋路徑中。 把還原後的套件版本放在一起。 不要混用來自不同發行版本的標頭和原生函式庫。

快速入門

請將範例 main.cpp 替換為以下程式碼,以初始化 SDK 並計算目錄中的模型數量:

#include <foundry_local/foundry_local_cpp.h>

#include <iostream>

using namespace foundry_local;

int main() {
    try {
        Manager manager{Configuration("app-name")};
        auto models = manager.GetCatalog().GetModels();
        std::cout << "Models available: " << models.size() << "\n";
    } catch (const Error& error) {
        std::cerr << "Foundry Local error [" << error.Code()
                  << "]: " << error.what() << "\n";
        return 1;
    }
    return 0;
}

範例會先輸出 Models available:,接著是型錄的型號數量。 它不會下載或載入模型。 在使用從管理器中取得的目錄、模型或中繼資料物件時,讓管理器保持存活。

參考資料:C++ 對 Configuration、Manager 和 Catalog 的包裝器宣告。

核心 API

包裝器使用資源擷取初始化(RAII)來在物件離開作用範圍時釋放原生句柄。

API 說明
Manager{Configuration("app-name")} 用應用程式名稱初始化一個管理器。
manager.GetCatalog() 取得型號目錄。
catalog.GetModels() 在型錄中列出型號。
catalog.GetModel(alias) 用別名查詢模型。 使用前先檢查傳回的指標。
model->Download() 把模型下載到本地快取。
model->Load() 載入模型以進行推斷。
model->Unload() 從記憶體中卸載模型。
ChatSession::ProcessRequest(request) 發送聊天請求並傳回回應。

API 參考與範例

使用公開標頭及持續維護的範例,以取得完整的 API 與推論工作流程: