共用方式為

Foundry 本地 SDK 參考

這很重要

  • Foundry Local 提供預覽版。 公開預覽版提供對正在部署的功能的早期存取。
  • 正式發行前的功能、方法和程序可能會變更或有功能上的限制。

Foundry Local SDK 讓您能在應用程式中搭載能利用本地 AI 模型的 AI 功能，透過簡單且直覺的 API。 SDK 抽象化了管理 AI 模型的複雜性，並提供無縫的體驗，將本地 AI 能力整合進您的應用程式。 本參考文獻文件說明了 JavaScript 與 C# 的 SDK 實作。 未來還會新增更多語言。

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

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

JavaScript SDK 參考

項目設定

Foundry Local SDK 的高階架構如下：

Foundry Local 新架構示意圖。

SDK 是一個輕量級包裝器，包覆於 Foundry Local Core C API.dll/.so/.dylib（），為 JavaScript 開發者提供更友善的介面。 SDK 負責載入原生函式庫、管理記憶體，以及在 JavaScript 與 C 之間的資料型態轉換。Foundry Local Core C API 有兩種版本，但 API 表面 相同 ：

  • WindowsML（WinML） -專為 Windows 設計，利用 WindowsML 取得所需驅動程式與執行工具，適用於可用硬體。 這是 Windows 用戶的推薦選項，因為它提供更佳的效能與多種硬體相容性。
  • 跨平台 支援 - 可在 Windows、macOS 及 Linux 上使用。 值得注意的是，在搭載 Apple Silicon 的 macOS 裝置上，跨平台 SDK 將透過 ONNX 執行時的 WebGPU 執行提供者，使用 Apple 的 Metal 框架進行硬體加速。

當你將 Foundry Local SDK 套件安裝到專案中時，可以選擇安裝 WinML 或跨平台版本。

在你的 JavaScript 專案中使用 Foundry Local，請遵循以下 Windows 專用或跨平台（macOS/Linux/Windows）指示：

  1. 建立一個新的 JavaScript 專案： 
    mkdir app-name
cd app-name
npm init -y
npm pkg set type=module
  2. 安裝 Foundry 本地 SDK 套件： 
    npm install --winml foundry-local-sdk
npm install 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 參考資料

參考資料

C# SDK 參考

專案設定指南

Foundry Local SDK 有兩個 NuGet 套件——一個是 WinML，一個是跨平台套件，兩者擁有相同的 API 表面，但針對不同平台進行優化：

  • Windows：使用專屬於 Windows 應用程式的 Microsoft.AI.Foundry.Local.WinML 套件，該套件使用 Windows Machine Learning（WinML）框架。
  • 跨平台：使用 Microsoft.AI.Foundry.Local 可用於跨平台應用程式（Windows、Linux、macOS）的套件。

根據你的目標平台，請依照以下指示建立新的 C# 應用程式並加入必要的相依性：

在你的 C# 專案中使用 Foundry Local，請遵循以下 Windows 專用或跨平台（macOS/Linux/Windows）指示：

  1. 建立一個新的 C# 專案並進入該專案：
    dotnet new console -n app-name
cd app-name
  2. 打開並編輯 app-name.csproj 檔案為： 
    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0-windows10.0.26100</TargetFramework>
    <RootNamespace>app-name</RootNamespace>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

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

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local.WinML" Version="0.9.0" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.10" />
    <PackageReference Include="OpenAI" Version="2.5.0" />
  </ItemGroup>

</Project>
  3. 在project根建立一個 nuget.config 檔案，內容如下，以確保套件能正確還原：
    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="ORT" value="https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="ORT">
      <package pattern="*Foundry*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

備註

Microsoft.AI.Foundry.Local NuGet 套件的目標是 net8.0。 其中 。NET具備前向相容性，能無縫支援針對.NET 9、.NET 10及更新版本的專案——無需其他設定。 SDK 僅使用 .NET 8 API，且不含特定框架的程式碼路徑，因此無論你的應用程式目標執行時如何，行為都是相同的。 我們的目標是 .NET 8，因為它是目前長期支援（LTS）版本，擁有最廣泛的安裝基礎。

快速入門

使用此片段驗證 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 參考資料

  • Last updated on