Foundry Local SDK リファレンス

Von Bedeutung

Foundry Local はプレビューで利用できます。パブリックプレビューリリースでは、デプロイ中の機能に早期にアクセスできます。
一般提供 (GA) の前は、機能、アプローチ、プロセスが変更されたり、機能が制限されたりする場合があります。

Foundry Local SDK は、データプレーン推論コードとは別のコントロールプレーン操作を提供することで、ローカル環境での AI モデル管理を簡素化します。このリファレンスでは、Python、JavaScript、C#、Rust の 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 を覚えておく必要なく、短い名前を使用できます。

ヒント

アプリケーションをデプロイすると、Foundry Local は実行時にエンドユーザーのマシンに最適なモデルを取得するため、 alias_or_model_id パラメーターに エイリアス を渡すことをお勧めします。

注

Windows 上に Intel NPU がある場合は、最適な NPU アクセラレーションのために Intel NPU ドライバーがインストールされていることを確認します。

サービス管理

メソッド	署名	説明
`is_service_running()`	`() -> bool`	Foundry Local サービスが実行されているかどうかを確認します。
`start_service()`	`() -> None`	Foundry Local サービスを開始します。
`service_uri`	`@property -> str`	サービス URI を返します。
`endpoint`	`@property -> str`	サービスエンドポイントを返します。
`api_key`	`@property -> str`	API キーを返します (env または既定値から)。

カタログ管理

メソッド	署名	説明
`list_catalog_models()`	`() -> list[` FoundryModelInfo`]`	カタログ内で使用可能なすべてのモデルを一覧表示します。
`refresh_catalog()`	`() -> None`	モデルカタログを更新します。
`get_model_info()`	`(alias_or_model_id: str, raise_on_not_found=False) ->` FoundryModelInfo `or None`	エイリアスまたは ID でモデル情報を取得します。

キャッシュ管理

メソッド	署名	説明
`get_cache_location()`	`() -> str`	モデルキャッシュディレクトリパスを返します。
`list_cached_models()`	`() -> list[` FoundryModelInfo`]`	ローカルキャッシュにダウンロードされたモデルを一覧表示します。

モデル管理

メソッド	署名	説明
`download_model()`	`(alias_or_model_id: str, token: str = None, force: bool = False) ->` FoundryModelInfo`]`	モデルをローカルキャッシュにダウンロードします。
`load_model()`	`(alias_or_model_id: str, ttl: int = 600) ->` FoundryModelInfo`]`	推論サーバーにモデルを読み込みます。
`unload_model()`	`(alias_or_model_id: str, force: bool = False) -> None`	推論サーバーからモデルをアンロードします。
`list_loaded_models()`	`() -> list[` FoundryModelInfo`]`	サービスに現在読み込まれているすべてのモデルを一覧表示します。

FoundryModelInfo

メソッドlist_catalog_models()、 list_cached_models()、および list_loaded_models() は、 FoundryModelInfo オブジェクトの一覧を返します。このオブジェクトに含まれる情報を使用して、リストをさらに絞り込むことができます。または、 get_model_info(alias_or_model_id) メソッドを呼び出して、モデルの情報を直接取得します。

これらのオブジェクトには、次のフィールドが含まれています。

フィールド	タイプ	説明
`alias`	`str`	モデルのエイリアス
`id`	`str`	モデルの一意識別子
`version`	`str`	モデルのバージョン
`execution_provider`	`str`	モデルの実行に使用されるアクセラレータ (実行プロバイダー)。
`device_type`	`DeviceType`	モデルのデバイスの種類: CPU、GPU、NPU
`uri`	`str`	モデルの URI
`file_size_mb`	`int`	ディスク上のモデルのサイズ (MB)
`supports_tool_calling`	`bool`	モデルがツール呼び出しをサポートしているかどうか
`prompt_template`	`dict \\| None`	モデルのプロンプトテンプレート
`provider`	`str`	モデルのプロバイダー (モデルが公開されている場所)
`publisher`	`str`	モデルの発行元、つまりモデルを公開したユーザー
`license`	`str`	モデルのライセンスの名前
`task`	`str`	モデルのタスク。チャット補完の 1 つ、自動音声認識
`ep_override`	`str \\| None`	モデルの既定値と異なる場合は、実行プロバイダーをオーバーライドします。

実行プロバイダー

つぎのいずれかです。

CPUExecutionProvider - CPU ベースの実行
CUDAExecutionProvider - NVIDIA CUDA GPU の実行
WebGpuExecutionProvider - WebGPU の実行
QNNExecutionProvider - Qualcomm ニューラルネットワーク処理 (NPU)
OpenVINOExecutionProvider - Intel OpenVINO の実行
NvTensorRTRTXExecutionProvider - NVIDIA TensorRT の実行
VitisAIExecutionProvider - AMD Vitis AI の実行

使用例

次のコードは、 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

次のコードは、 FoundryLocalManager を OpenAI SDK と統合してローカルモデルと対話する方法を示しています。

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 を覚えておく必要なく、短い名前を使用できます。

ヒント

アプリケーションをデプロイすると、Foundry Local は実行時にエンドユーザーのマシンに最適なモデルを取得するため、 aliasOrModelId パラメーターに エイリアス を渡すことをお勧めします。

注

Windows 上に Intel NPU がある場合は、最適な NPU アクセラレーションのために Intel NPU ドライバーがインストールされていることを確認します。

サービス管理

メソッド	署名	説明
`init()`	`(aliasOrModelId?: string) => Promise<void>`	SDK を初期化し、必要に応じてモデルを読み込みます。
`isServiceRunning()`	`() => Promise<boolean>`	Foundry Local サービスが実行されているかどうかを確認します。
`startService()`	`() => Promise<void>`	Foundry Local サービスを開始します。
`serviceUrl`	`string`	Foundry Local サービスのベース URL。
`endpoint`	`string`	API エンドポイント (serviceUrl + `/v1`)。
`apiKey`	`string`	API キー (なし)。

カタログ管理

メソッド	署名	説明
`listCatalogModels()`	`() => Promise<FoundryModelInfo[]>`	カタログ内で使用可能なすべてのモデルを一覧表示します。
`refreshCatalog()`	`() => Promise<void>`	モデルカタログを更新します。
`getModelInfo()`	`(aliasOrModelId: string, throwOnNotFound = false) => Promise<FoundryModelInfo \\| null>`	エイリアスまたは ID でモデル情報を取得します。

キャッシュ管理

メソッド	署名	説明
`getCacheLocation()`	`() => Promise<string>`	モデルキャッシュディレクトリパスを返します。
`listCachedModels()`	`() => Promise<FoundryModelInfo[]>`	ローカルキャッシュにダウンロードされたモデルを一覧表示します。

モデル管理

メソッド	署名	説明
`downloadModel()`	`(aliasOrModelId: string, token?: string, force = false, onProgress?) => Promise<FoundryModelInfo>`	モデルをローカルキャッシュにダウンロードします。
`loadModel()`	`(aliasOrModelId: string, ttl = 600) => Promise<FoundryModelInfo>`	推論サーバーにモデルを読み込みます。
`unloadModel()`	`(aliasOrModelId: string, force = false) => Promise<void>`	推論サーバーからモデルをアンロードします。
`listLoadedModels()`	`() => Promise<FoundryModelInfo[]>`	サービスに現在読み込まれているすべてのモデルを一覧表示します。

使用例

次のコードは、 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

注

ブラウザーのバージョンでは、 init、 isServiceRunning、および startService メソッドはサポートされていません。ブラウザー環境で SDK を使用する前に、Foundry Local サービスが実行されていることを確認する必要があります。 Foundry ローカル CLI: foundry service startを使用してサービスを開始できます。 CLI 出力からサービス 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 });

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 リファレンス

再設計

デバイス上の AI を使用してアプリケーションを出荷する機能を向上させるために、バージョン 0.8.0 以降の C# SDK のアーキテクチャが大幅に変更されています。このセクションでは、アプリケーションを最新バージョンの SDK に移行するために役立つ主な変更について説明します。

注

SDK バージョン 0.8.0 以降では、以前のバージョンの API に破壊的変更があります。

アーキテクチャの変更

次の図は、以前のアーキテクチャ ( 0.8.0 より前のバージョン) が、REST Web サーバーを使用して、チャットの完了などのモデルと推論を管理するために大きく依存していた方法を示しています。

SDK では、リモート手続き型呼び出し (RPC) を使用してマシン上の Foundry ローカル CLI 実行可能ファイルを検索し、Web サーバーを起動してから、HTTP 経由で通信します。このアーキテクチャには、次のようないくつかの制限がありました。

Web サーバーのライフサイクルを管理する際の複雑さ。
困難なデプロイ: エンドユーザーは、マシンとアプリケーションに Foundry ローカル CLI をインストールする必要があります。
CLI と SDK のバージョン管理により、互換性の問題が発生する可能性があります。

これらの問題に対処するために、バージョン 0.8.0 以降で再設計されたアーキテクチャでは、より合理化されたアプローチが使用されます。新しいアーキテクチャは次のとおりです。

この新しいアーキテクチャでは、次の操作を行います。

アプリケーションは 自己完結型です。 Foundry Local CLI をエンドユーザーのマシンに個別にインストールする必要がないため、アプリケーションを簡単にデプロイできます。
REST Web サーバーは 省略可能です。 HTTP 経由で通信する他のツールと統合する場合は、引き続き Web サーバーを使用できます。この機能の使用方法の詳細については、「Foundry Local で REST サーバー経由でチャットの完了を使用する」を参照してください。
SDK では 、チャットの完了と音声の文字起こしがネイティブにサポートされているため、依存関係の少ない会話型 AI アプリケーションを構築できます。この機能の使用方法の詳細については、「 Foundry Local Native Chat Completions API を使用する」を参照してください。
Windows デバイスでは、適切なランタイムとドライバーをプルすることで、デバイス上のモデルの ハードウェアアクセラレーション を処理する Windows ML ビルドを使用できます。

API の変更

バージョン 0.8.0 以降では、オブジェクト指向で構成可能な API が提供されます。メインエントリポイントは引き続き FoundryLocalManager クラスですが、ステートレス HTTP API への静的呼び出しを介して動作するメソッドのフラットセットである代わりに、SDK はサービスとモデルに関する状態を維持する FoundryLocalManager インスタンス上のメソッドを公開するようになりました。

プリミティブ	バージョン < 0.8.0	バージョン >= 0.8.0
Configuration	N/A	`config = Configuration(...)`
マネージャーを取得する	`mgr = FoundryLocalManager();`	`await FoundryLocalManager.CreateAsync(config, logger);` `var mgr = FoundryLocalManager.Instance;`
カタログの取得	N/A	`catalog = await mgr.GetCatalogAsync();`
モデルの一覧表示	`mgr.ListCatalogModelsAsync();`	`catalog.ListModelsAsync();`
モデルの取得	`mgr.GetModelInfoAsync("aliasOrModelId");`	`catalog.GetModelAsync(alias: "alias");`
バリアントの取得	N/A	`model.SelectedVariant;`
バリアントの設定	N/A	`model.SelectVariant();`
モデルをダウンロードする	`mgr.DownloadModelAsync("aliasOrModelId");`	`model.DownloadAsync()`
モデルを読み込む	`mgr.LoadModelAsync("aliasOrModelId");`	`model.LoadAsync()`
モデルのアンロード	`mgr.UnloadModelAsync("aliasOrModelId");`	`model.UnloadAsync()`
読み込まれたモデルの一覧表示	`mgr.ListLoadedModelsAsync();`	`catalog.GetLoadedModelsAsync();`
モデルパスの取得	N/A	`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"
};

以前のバージョンの Foundry Local C# SDK では、SDK を使用してこれらの設定を直接構成できませんでした。これにより、サービスの動作をカスタマイズする機能が制限されました。

プロジェクトセットアップガイド

Foundry Local SDK には 2 つの NuGet パッケージ (WinML とクロスプラットフォームパッケージ) があり、 API サーフェスは同じです が、異なるプラットフォーム向けに最適化されています。

Windows: Windows アプリケーションに固有の Microsoft.AI.Foundry.Local.WinML パッケージを使用します。Windows Machine Learning (WinML) フレームワークを使用して、Windows デバイスで最適なパフォーマンスとユーザーエクスペリエンスを提供します。
クロスプラットフォーム: クロスプラットフォームアプリケーション (Windows、Linux、macOS) に使用できる Microsoft.AI.Foundry.Local パッケージを使用します。

ターゲットプラットフォームに応じて、次の手順に従って新しい C# アプリケーションを作成し、必要な依存関係を追加します。

Windows 固有またはクロスプラットフォーム (macOS/Linux/Windows) の手順に従って、C# プロジェクトで Foundry Local を使用します。

ウィンドウズ
クロスプラットフォーム

新しい C# プロジェクトを作成し、そこに移動します。
```
dotnet new console -n app-name
cd app-name
```

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>

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

</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>

新しい C# プロジェクトを作成し、そこに移動します。
```
dotnet new console -n app-name
cd app-name
```

app-name.csproj ファイルを開いて編集し、次の作業を行います。

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

    <PropertyGroup>
      <OutputType>Exe</OutputType>
      <TargetFramework>net9.0</TargetFramework>
      <ImplicitUsings>enable</ImplicitUsings>
      <Nullable>enable</Nullable>
    </PropertyGroup>

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

</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>

アプリケーションパッケージのサイズを小さくする

Foundry Local SDK は、依存関係として NuGet パッケージ Microsoft.ML.OnnxRuntime.Foundry プルします。 Microsoft.ML.OnnxRuntime.Foundry パッケージには、推論ランタイムバンドルが用意されています。これは、特定のベンダーハードウェアデバイスで推論を効率的に実行するために必要なライブラリのセットです。推論ランタイムバンドルには、次のコンポーネントが含まれています。

ONNX ランタイムライブラリ: コア推論エンジン (onnxruntime.dll)。
ONNX ランタイム実行プロバイダー (EP) ライブラリ。ハードウェアアクセラレータである機械学習モデルの一部を最適化して実行する ONNX Runtime のハードウェア固有のバックエンド。例えば：
- CUDA EP: onnxruntime_providers_cuda.dll
- QNN EP: onnxruntime_providers_qnn.dll
独立系ハードウェアベンダー (IHV) ライブラリ。例えば：
- WebGPU: DirectX の依存関係 (dxcompiler.dll、 dxil.dll)
- QNN: Qualcomm QNN の依存関係 (QnnSystem.dllなど)

次の表に、アプリケーションにバンドルされている EP ライブラリと IHV ライブラリと、実行時にダウンロードまたはインストールする WinML の概要を示します。

EP および IHV ライブラリを示すテーブルの図。

すべてのプラットフォーム/アーキテクチャで、CPU EPU が必要です。 WebGPU EP および IHV ライブラリはサイズが小さく (たとえば、WebGPU はアプリケーションパッケージに最大 7 MB しか追加されません)、Windows と macOS で必要です。ただし、CUDA と QNN の IP はサイズが大きいため (たとえば、CUDA によってアプリケーションパッケージに最大 1 GB が追加されます)、アプリケーションパッケージからこれらの IP を除外することをお勧めします。 WinML は、エンドユーザーが互換性のあるハードウェアを持っている場合、実行時に CUDA と QNN をダウンロード/インストールします。

注

今後のリリースでは、 Microsoft.ML.OnnxRuntime.Foundry パッケージから CUDA および QNN EP を削除し、アプリケーションパッケージから削除するために ExcludeExtraLibs.props ファイルを含める必要がないようにしています。

アプリケーションパッケージのサイズを小さくするには、次の内容を含む ExcludeExtraLibs.props ファイルをプロジェクトディレクトリに作成します。これにより、アプリケーションを発行するときに CUDA および QNN EP および IHV ライブラリが除外されます。

<Project>
  <!-- we want to ensure we're using the onnxruntime libraries from Foundry Local Core so 
  we delete the WindowsAppSdk versions once they're unzipped. -->
  <Target Name="ExcludeOnnxRuntimeLibs" AfterTargets="ExtractMicrosoftWindowsAppSDKMsixFiles">
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime.dll"/>
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime_providers_shared.dll"/>
    <Message Importance="Normal" Text="Deleted onnxruntime libraries from $(MicrosoftWindowsAppSDKMsixContent)." />
  </Target>

  <!-- Remove CUDA EP and IHV libraries on Windows x64 -->
  <Target Name="ExcludeCudaLibs" Condition="'$(RuntimeIdentifier)'=='win-x64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <!-- match onnxruntime*cuda.* (we're matching %(Filename) which excludes the extension) -->
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^onnxruntime.*cuda.*', RegexOptions.IgnoreCase))" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime CUDA libraries from package." />
  </Target>

  <!-- Remove QNN EP and IHV libraries on Windows arm64 -->
  <Target Name="ExcludeQnnLibs" Condition="'$(RuntimeIdentifier)'=='win-arm64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)%(Extension)', 
                                      '^QNN.*\.dll', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^libQNNhtp.*', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="'%(FileName)%(Extension)' == 'onnxruntime_providers_qnn.dll'" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime QNN libraries from package." />
  </Target>

  <!-- need to manually copy on linux-x64 due to the nuget packages not having the correct props file setup -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <!-- 'Update' as the Core package will add these dependencies, but we want to be explicit about the version -->
    <PackageReference Update="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Update="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
    <OrtNativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntime.gpu.linux/$(OnnxRuntimeVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
    <OrtGenAINativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntimegenai.cuda/$(OnnxRuntimeGenAIVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
  </ItemGroup>

  <Target Name="CopyOrtNativeLibs" AfterTargets="Build" Condition=" '$(RuntimeIdentifier)' == 'linux-x64'">
    <Copy SourceFiles="@(OrtNativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
    <Copy SourceFiles="@(OrtGenAINativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
  </Target>
</Project>

プロジェクトファイル (.csproj) に次の行を追加して、 ExcludeExtraLibs.props ファイルをインポートします。

<!-- other project file content -->
  
<Import Project="ExcludeExtraLibs.props" />

Linux: CUDA の依存関係

CUDA EP は、 Microsoft.ML.OnnxRuntime.Foundry経由で Linux アプリケーションにプルされますが、IHV ライブラリは含まれません。 CUDA 対応デバイスを持つエンドユーザーに高いパフォーマンスのメリットを得られるようにするには、次の CUDA IHV ライブラリをアプリケーションに追加する必要があります。

CUBLAS v12.8.4 (NVIDIA Developer からダウンロード)
- cublas64_12.dll
- cublasLt64_12.dll
CUDA RT v12.8.90 (NVIDIA Developer からダウンロード)
- cudart64_12.dll
CUDNN v9.8.0 (NVIDIA Developer からダウンロード)
- cudnn_graph64_9.dll
- cudnn_ops64_9.dll
- cudnn64_9.dll
CUDA FFT v11.3.3.83 (NVIDIA Developer からダウンロード)
- cufft64_11.dll

Warnung

CUDA EP および IHV ライブラリをアプリケーションに追加すると、アプリケーションパッケージのサイズが 1 GB 増加します。

Samples

Foundry Local C# SDK の使用方法を示すサンプルアプリケーションについては、 Foundry Local C# SDK Samples GitHub リポジトリを参照してください。

API リファレンス

Foundry Local C# SDK の詳細については、 Foundry Local C# SDK API リファレンスを参照してください。

Rust SDK リファレンス

Rust SDK for Foundry Local は、モデルの管理、キャッシュの制御、Foundry Local サービスとの対話を行う方法を提供します。

取り付け

Foundry Local Rust SDK を使用するには、 Cargo.tomlに次のコードを追加します。

[dependencies]
foundry-local-sdk = "0.1"

または、次の cargoを使用して Foundry Local クレートを追加することもできます。

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 Local サービスを開始します。
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: (省略可能) Time-to-Live (秒単位)。
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

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-02

次の方法で共有

Foundry Local SDK リファレンス

Python SDK リファレンス

取り付け

FoundryLocalManager クラス

初期化

エイリアスに関する注意事項

サービス管理

カタログ管理

キャッシュ管理

モデル管理

FoundryModelInfo

実行プロバイダー

使用例

OpenAI SDK との統合

JavaScript SDK リファレンス

取り付け

FoundryLocalManager クラス

初期化

エイリアスに関する注意事項

サービス管理

カタログ管理

キャッシュ管理

モデル管理

使用例

OpenAI クライアントとの統合

ブラウザー使用状況

使用例

C# SDK リファレンス

再設計

アーキテクチャの変更

API の変更

プロジェクトセットアップガイド

アプリケーション パッケージのサイズを小さくする

Linux: CUDA の依存関係

Samples

API リファレンス

Rust SDK リファレンス

取り付け

FoundryLocalManager

田畑

メソッド

FoundryLocalManagerBuilder

田畑

メソッド

FoundryModelInfo

田畑

メソッド

ExecutionProvider

メソッド

ModelRuntime

フィードバック

その他のリソース

アプリケーションパッケージのサイズを小さくする

`FoundryLocalManager`

`FoundryLocalManagerBuilder`

`FoundryModelInfo`

`ExecutionProvider`

`ModelRuntime`