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

サービス管理

カタログ管理

キャッシュ管理

モデル管理

使用例

次のコードは、 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 = "phi-3.5-mini"

# 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 = "phi-3.5-mini"

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

サービス管理

カタログ管理

キャッシュ管理

モデル管理

使用例

次のコードは、 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 = "phi-3.5-mini";

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 = "phi-3.5-mini";

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

使用例

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 = 'phi-3.5-mini'

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

取り付け

Foundry Local C# SDK を使用するには、NuGet パッケージをインストールする必要があります。

dotnet add package Microsoft.AI.Foundry.Local

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

このリファレンスで概説されている多くのメソッドには、シグネチャに aliasOrModelId パラメーターがあります。 エイリアスまたはモデル ID を値としてメソッドに渡すことができます。 エイリアスを使用すると、次のようになります。

• 使用可能なハードウェアに 最適なモデル を選択します。 たとえば、Nvidia CUDA GPU が使用可能な場合、Foundry Local は CUDA モデルを選択します。 サポートされている NPU が使用可能な場合、Foundry Local は NPU モデルを選択します。
• モデル ID を覚えておく必要なく、短い名前を使用できます。

列挙型

DeviceType

モデルの実行に使用されるデバイスの種類を表します。

ExecutionProvider

モデル推論の実行プロバイダーを表します。

FoundryLocalManager クラス

モデル、キャッシュ、Foundry Local サービスを管理するためのメイン エントリ ポイント。

建設

var manager = new FoundryLocalManager();

特性

サービス管理

サービスを開始する

await manager.StartServiceAsync(CancellationToken.None);

Foundry Local サービスがまだ実行されていない場合は開始します。

サービスを停止する

await manager.StopServiceAsync(CancellationToken.None);

Foundry Local サービスを停止します。

モデルの開始と読み込み (静的ヘルパー)

var manager = await FoundryLocalManager.StartModelAsync("aliasOrModelId");

サービスを開始し、指定したモデルを読み込みます。

カタログ管理

すべてのカタログ モデルを一覧表示する

List<ModelInfo> models = await manager.ListCatalogModelsAsync();

カタログ内で使用可能なすべてのモデルを返します。

カタログを更新する

manager.RefreshCatalog();

キャッシュされたカタログをクリアして、次のアクセス時に再読み込みできるようにします。

エイリアスまたは ID でモデル情報を取得する

ModelInfo? info = await manager.GetModelInfoAsync("aliasOrModelId");

見つからない場合は、モデル情報または null を返します。

キャッシュ管理

キャッシュの場所を取得する

string cachePath = await manager.GetCacheLocationAsync();

モデルがキャッシュされるディレクトリ パスを返します。

キャッシュされたモデルを一覧表示する

List<ModelInfo> cached = await manager.ListCachedModelsAsync();

ローカル キャッシュにダウンロードされたモデルを返します。

モデル管理

モデルをダウンロードする

ModelInfo? model = await manager.DownloadModelAsync("aliasOrModelId");

モデルをローカル キャッシュにダウンロードします。

進行状況のあるモデルをダウンロードする

await foreach (var progress in manager.DownloadModelWithProgressAsync("aliasOrModelId"))
{
    // progress.Percentage, progress.Status, etc.
}

ダウンロードの進行状況はストリームによって更新されます。

モデルを読み込む

ModelInfo loaded = await manager.LoadModelAsync("aliasOrModelId");

推論サーバーにモデルを読み込みます。

読み込まれたモデルを一覧表示する

List<ModelInfo> loaded = await manager.ListLoadedModelsAsync();

サービスに現在読み込まれているすべてのモデルを一覧表示します。

モデルをアンロードする

await manager.UnloadModelAsync("aliasOrModelId");

推論サーバーからモデルをアンロードします。

廃棄

適切なクリーンアップのために、 IDisposable と IAsyncDisposable の両方を実装します。

manager.Dispose();
// or
await manager.DisposeAsync();

モデルの種類

このページでは、Foundry Local C# SDK でモデル、ダウンロード、ランタイム情報を記述するために使用される主要なデータ型について説明します。

PromptTemplate

モデルのプロンプト テンプレートを表します。

Runtime

モデルのランタイム環境について説明します。

ModelSettings

モデル固有のパラメーターを表します。

ModelInfo

Foundry Local カタログまたはキャッシュ内のモデルについて説明します。

ModelDownloadProgress

モデルのダウンロード操作の進行状況を表します。

静的メソッド:

• Progress(double percentage): 進行状況の更新を作成します。
• Completed(ModelInfo modelInfo): 完了した進捗結果を作成します。
• Error(string errorMessage): エラー結果を作成します。

使用例

using Microsoft.AI.Foundry.Local;

var manager = new FoundryLocalManager();
await manager.StartServiceAsync();

var models = await manager.ListCatalogModelsAsync();
var alias = "phi-3.5-mini";

await manager.DownloadModelAsync(alias);
await manager.LoadModelAsync(alias);

var loaded = await manager.ListLoadedModelsAsync();

await manager.UnloadModelAsync(alias);

manager.Dispose();

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