Foundry Local SDK リファレンス

Foundry Local SDK を使用すると、シンプルで直感的な API を使用して、ローカル AI モデルを使用する AI 機能をアプリケーションに実装できます。 SDK は、AI モデルの管理の複雑さを取り除き、ローカル AI 機能をアプリケーションに統合するためのシームレスなエクスペリエンスを提供します。 このリファレンスでは、C#、C++、JavaScript、Python、Rust の SDK 実装について説明します。

SDK では、Foundry Local CLI をエンド ユーザー マシンにインストールする必要はありません。これにより、ユーザーに追加のセットアップ手順を行わずにアプリケーションを出荷できます。アプリケーションは自己完結型です。 Foundry Local SDK のその他の利点は次のとおりです。

  • ハードウェアの検出と最適化: GPU、NPU、CPU の自動機能評価。
  • Execution プロバイダー管理 (Windows): デバイスの機能に基づく適切な ONNX ランタイム実行プロバイダー (CUDA、Vitis、QNN、OpenVINO、TensorRT) の自動ダウンロードと登録。
  • WebGpu (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 を使用して C# プロジェクトを設定する方法の詳細については、 Foundry Local SDK リファレンスを参照 してください。

プロジェクト構成

サンプル リポジトリには、プラットフォーム検出を自動的に処理する .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 Windows、macOS、Linux 用の Foundry Local SDK パッケージ。

クイック スタート

このスニペットを使用して、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 には、デバイス上でささやきモデルを使用してオーディオ ファイルを文字起こしするためのネイティブ オーディオ クライアントが含まれています。 これにより、REST Web サーバーを必要とせずに、インプロセスで推論が実行されます。

オーディオ クライアントを取得する

ささやきモデルを読み込んだ後、オーディオ クライアントを取得します。

var audioClient = await model.GetAudioClientAsync();

オーディオ文字起こしメソッド

メソッド 署名 説明
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 リファレンス

References

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 クラスを使用すると、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 キーを使用した Web サービスの構成。

コア 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

ささやきモデルを読み込んだ後、オーディオ クライアントを取得します。

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(())
}

次の使用例は、ハードウェアで使用できるモデルの数を出力します。

サンプル

コンフィギュレーション

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

ささやきモデルを読み込んだ後、オーディオ クライアントを作成します。

let audio_client = model.create_audio_client();
メソッド 説明
audio_client.transcribe(file_path).await オーディオ ファイルを文字起こしします。 text フィールドを持つオブジェクトを返します。

参考資料:

C++ SDK リファレンス

Prerequisites

C++ SDK は、ネイティブ Foundry Local ランタイムに対してヘッダーのみのラッパーを提供します。 デプロイされたアプリケーションでは、Foundry Local 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

構成時に、このサンプルは Microsoft.AI.Foundry.Local.Runtime NuGet パッケージのバージョン 2.2.1 を build/_packages に復元します。 パッケージには、Windows、Linux、および macOS 用の C++ ヘッダーとネイティブ ライブラリが含まれています。 別の WinML パッケージは必要ありません。

CMake 構成では、オペレーティング システムとアーキテクチャのランタイム資産が選択され、必要なネイティブ ライブラリが実行可能ファイルの横にコピーされます。 macOS と Linux では、build から実行ファイルを実行します。 Windows で、.exe の build ファイルを実行します。

アプリケーションのオペレーティング システムとアーキテクチャに一致するネイティブ アセットを選択してください。

オペレーティング システム Architecture ランタイム識別子 (RID)
Windows x64 または ARM64 win-x64 または win-arm64
Linux x64 または ARM64 linux-x64 または linux-arm64
macOS Apple Silicon (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 ディレクトリ:

  • Windows では foundry_local.lib。
  • Linux 上の libfoundry_local.so。
  • 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: を出力し、その後にカタログのモデル数を出力します。 モデルをダウンロードまたは読み込めません。 そのマネージャーから取得したカタログ、モデル、またはメタデータ オブジェクトを使用している間は、そのマネージャーを存続させておいてください。

リファレンス: Configuration、Manager、およびCatalogの C++ ラッパー宣言。

コア API

ラッパーは、RAII（Resource Acquisition Is Initialization）により、オブジェクトがスコープを抜けるときにネイティブ ハンドルを解放します。

API 説明
Manager{Configuration("app-name")} アプリケーション名を使用してマネージャーを初期化します。
manager.GetCatalog() モデル カタログを取得します。
catalog.GetModels() カタログ内のモデルを一覧表示します。
catalog.GetModel(alias) 別名でモデルを検索します。 返されたポインターを使用する前に確認してください。
model->Download() モデルをローカル キャッシュにダウンロードします。
model->Load() 推論用のモデルを読み込みます。
model->Unload() メモリからモデルをアンロードします。
ChatSession::ProcessRequest(request) チャット要求を実行し、応答を返します。

API リファレンスとサンプル

完全な API および推論ワークフローについては、パブリック ヘッダーとメンテナンスされている例を参照してください。

  • 最終更新: