Foundry Local REST API リファレンス

2025-06-13

Von Bedeutung

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

注意事項

この API はアクティブな開発中であり、予告なしに破壊的変更が含まれる場合があります。運用アプリケーションをビルドする前に、変更ログを監視することを強くお勧めします。

OpenAI v1 の互換性

POST /v1/chat/completions

このエンドポイントは、チャット完了要求を処理します。
OpenAI チャット完了 API と完全に互換性がある

リクエストボディ:

---Standard OpenAI 特性---

model (文字列)
完了に使用する特定のモデル。
messages (配列)
メッセージの一覧としての会話履歴。
- 各メッセージには次のものが必要です。
  - role (文字列)
    メッセージ送信者のロール。 system、user、または assistant にする必要があります。
  - content (文字列)
    実際のメッセージテキスト。
temperature (数値、省略可能)
ランダム性を 0 から 2 の範囲で制御します。値が大きいほど (0.8) さまざまな出力が作成され、値が小さい (0.2) とフォーカスされた一貫性のある出力が作成されます。
top_p (数値、省略可能)
トークン選択の多様性を 0 から 1 に制御します。値が 0.1 の場合、上位 10 個のトークン% 確率のみが考慮されます。
n (整数、省略可能)
入力メッセージごとに生成する代替入力候補の数。
stream (ブール値、省略可能)
true の場合、サーバー送信イベントとして部分的なメッセージ応答を送信し、最後に data: [DONE] メッセージを送信します。
stop (文字列または配列、省略可能)
モデルが追加のトークンの生成を停止する最大 4 つのシーケンス。
max_tokens (整数、省略可能)
生成するトークンの最大数。新しいモデルの場合は、代わりに max_completion_tokens を使用します。
max_completion_token (整数、省略可能)
表示される出力と推論トークンの両方を含む、生成の最大トークン制限。
presence_penalty (数値、省略可能)
値の範囲は -2.0 から 2.0 です。正の値を指定すると、モデルは、既に出現しているトークンに対して罰を与えることで、新しいトピックについて話し合うことが推奨されます。
frequency_penalty (数値、省略可能)
値の範囲は -2.0 から 2.0 です。正の値は、テキスト内の頻度に基づいてトークンを罰することで繰り返しを推奨しません。
logit_bias (マップ、オプション)
完了時に特定のトークンが出現する確率を調整します。
user (string、省略可能)
監視と不正使用の防止に役立つエンドユーザーの一意の識別子。
functions (配列、オプション)
モデルが JSON 入力を生成できる使用可能な関数。
- 各関数には、次のものが含まれている必要があります。
  - name (文字列)
    関数名。
  - description (文字列)
    関数の説明。
  - parameters (オブジェクト)
    JSON スキーマオブジェクトとして記述された関数パラメーター。
function_call (文字列またはオブジェクト、省略可能)
モデルが関数呼び出しにどのように応答するかを制御します。
- オブジェクトの場合は、次のものが含まれます。
  - name (string、省略可能)
    呼び出す関数の名前。
  - arguments (オブジェクト、省略可能)
    関数に渡す引数。
metadata (オブジェクト、省略可能)
メタデータキーと値のペアのディクショナリ。
top_k (数値、省略可能)
上位 k フィルター処理のために保持する最も高い確率のボキャブラリトークンの数。
random_seed (整数、省略可能)
再現可能な乱数生成のシード。
ep (string、省略可能)
ONNX モデルのプロバイダーを上書きします。サポート: "dml"、 "cuda"、 "qnn"、 "cpu"、 "webgpu"。
ttl (整数、省略可能)
メモリ内のモデルの有効期間 (秒単位)。
tools (オブジェクト、省略可能)
要求に応じて計算されたツール。

応答本文:

id (文字列)
チャット入力候補の一意識別子。
object (文字列)
オブジェクトの種類。常に "chat.completion"。
created (整数)
エポック秒単位の作成タイムスタンプ。
model (文字列)
補完に使用されるモデル。
choices (配列)
完了の選択肢の一覧。各候補には次のものが含まれます。
- index (整数)
  この選択のインデックス。
- message (オブジェクト)
  生成されたメッセージの内容は次のとおりです。
  - role (文字列)
    応答の際は常に"assistant"を使用します。
  - content (文字列)
    実際に生成されたテキスト。
- finish_reason (文字列)
  生成が停止した理由 (たとえば、 "stop"、 "length"、 "function_call")。
usage (オブジェクト)
トークンの使用状況の統計情報:
- prompt_tokens (整数)
  プロンプト内のトークン。
- completion_tokens (整数)
  完了のトークン。
- total_tokens (整数)
  使用されたトークンの合計数。

例:

要求本文

{
  "model": "Phi-4-mini-instruct-generic-cpu",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "temperature": 0.7,
  "top_p": 1,
  "n": 1,
  "stream": false,
  "stop": null,
  "max_tokens": 100,
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "logit_bias": {},
  "user": "user_id_123",
  "functions": [],
  "function_call": null,
  "metadata": {}
}

応答本文

{
  "id": "chatcmpl-1234567890",
  "object": "chat.completion",
  "created": 1677851234,
  "model": "Phi-4-mini-instruct-generic-cpu",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'm doing well, thank you! How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

POST /v1/embeddings

埋め込み生成リクエストを処理します。
OpenAI Embeddings API と互換性がある

リクエストボディ:

model (文字列)
使用する埋め込みモデル (例: "text-embedding-ada-002")。
input (文字列または配列)
埋め込むテキストを入力します。 1 つの文字列または文字列/トークンの配列を指定できます。
encoding_format (string、省略可能)
エンコード形式 ("base64" または "float")。

応答本文:

object (文字列)
常に "list" です。
data (配列)
以下を含む埋め込みオブジェクトの一覧。
- object (文字列)
  常に "embedding" です。
- embedding (配列)
  入力テキストのベクター表現。
- index (整数)
  入力配列内のこの埋め込みの位置。
model (文字列)
埋め込み生成に使用されるモデル。
usage (オブジェクト)
トークンの使用状況の統計情報:
- prompt_tokens (整数)
  プロンプト内のトークンの数。
- total_tokens (整数)
  使用されたトークンの合計数。

例:

要求本文

{
  "model": "qwen_w_embeddings",
  "input": "Hello, how are you?"
}

応答本文

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.1, 0.2, 0.3, ...],
      "index": 0
    }
  ],
  "model": "qwen_w_embeddings",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

カスタム API

GET /foundry/list

カタログ内で使用可能なすべての Foundry Local モデルの一覧を取得します。

応答：

models (配列)
以下を含むモデルオブジェクトの一覧。
- name: モデルの一意識別子。
- displayName: モデルの人間が判読できる名前。多くの場合、名前と同じです。
- providerType: モデルをホストしているプロバイダーの種類 (例: AzureFoundry)。
- uri: レジストリ内のモデルの場所を指すリソース URI。
- version: モデルのバージョン番号。
- modelType: モデルの形式または型 (ONNX など)。
- promptTemplate:
  - assistant: アシスタントの応答のテンプレート。
  - prompt: ユーザーアシスタント操作のテンプレート。
- publisher: モデルを公開したエンティティまたは組織。
- task: モデルが実行するように設計されている主なタスク (チャット完了など)。
- runtime:
  - deviceType: モデルが実行するように設計されているハードウェアの種類 (CPU など)。
  - executionProvider: モデルの実行に使用される実行プロバイダー。
- fileSizeMb: モデルファイルのサイズ (MB 単位)。
- modelSettings:
  - parameters: モデルの構成可能なパラメーターの一覧。
- alias: モデルの別名または短縮形
- supportsToolCalling: モデルがツール呼び出し機能をサポートしているかどうかを示します。
- license: モデルが配布されるライセンスの種類。
- licenseDescription: 詳細な説明またはライセンス条項へのリンク。
- parentModelUri: このモデルの派生元となる親モデルの URI。

POST /openai/register

Foundry Local で使用する外部モデルプロバイダーを登録します。

リクエストボディ:

TypeName (文字列)
プロバイダー名 (例: "deepseek")
ModelName (文字列)
登録するモデル名 (例: "deepseek-chat")
BaseUri (文字列)
プロバイダー向けの OpenAI 互換のベース URI

応答：

200 OK（正常に処理されました）
空の応答本文

例:

要求本文

{
  "TypeName": "deepseek",
  "ModelName": "deepseek-chat",
  "BaseUri": "https://api.deepseek.com/v1"
}

GET /openai/models

ローカルモデルと登録済みの外部モデルの両方を含む、使用可能なすべてのモデルを取得します。

応答：

200 OK（正常に処理されました）
文字列としてのモデル名の配列。

例:

応答本文

["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

GET /openai/load/{name}

推論を高速化するために、モデルをメモリに読み込みます。

URI パラメーター:

name (文字列)
読み込むモデルの名前。

クエリパラメーター:

unload (ブール値、省略可能)
アイドル時間後にモデルを自動的にアンロードするかどうかを指定します。既定値は true です。
ttl (整数、省略可能)
Time to Live (秒単位) 0 より大きい場合は、パラメーター unload オーバーライドします。
ep (string、省略可能)
このモデルを実行する実行プロバイダー。サポート: "dml"、 "cuda"、 "qnn"、 "cpu"、 "webgpu"。
指定しない場合は、 genai_config.jsonの設定を使用します。

応答：

200 OK（正常に処理されました）
空の応答本文

例:

要求 URI

GET /openai/load/Phi-4-mini-instruct-generic-cpu?ttl=3600&ep=dml

GET /openai/unload/{name}

メモリからモデルをアンロードします。

URI パラメーター:

name (文字列)
アンロードするモデルの名前。

クエリパラメーター:

force (ブール値、省略可能)
true場合、TTL 設定は無視され、すぐにアンロードされます。

応答：

200 OK（正常に処理されました）
空の応答本文

例:

要求 URI

GET /openai/unload/Phi-4-mini-instruct-generic-cpu?force=true

GET /openai/unloadall

メモリからすべてのモデルをアンロードします。

応答：

200 OK（正常に処理されました）
空の応答本文

GET /openai/loadedmodels

現在読み込まれているモデルの一覧を取得します。

応答：

200 OK（正常に処理されました）
文字列としてのモデル名の配列。

例:

応答本文

["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

GET /openai/getgpudevice

現在選択されている GPU デバイス ID を取得します。

応答：

200 OK（正常に処理されました）
現在の GPU デバイス ID を表す整数。

GET /openai/setgpudevice/{deviceId}

アクティブな GPU デバイスを設定します。

URI パラメーター:

deviceId (整数)
使用する GPU デバイス ID。

応答：

200 OK（正常に処理されました）
空の応答本文

例:

要求 URI
```
GET /openai/setgpudevice/1
```

POST /openai/download

モデルをローカルストレージにダウンロードします。

注

モデルのダウンロードには、特に大規模なモデルの場合、かなりの時間がかかる場合があります。早期終了を回避するために、この要求に対して高いタイムアウトを設定することをお勧めします。

リクエストボディ:

model (WorkspaceInferenceModel オブジェクト)
- Uri (文字列)
  ダウンロードするモデルの URI。
- Name (文字列)モデル名。
- ProviderType (string、省略可能)
  プロバイダーの種類 (たとえば、 "AzureFoundryLocal"、"HuggingFace")。
- Path (string、省略可能)
  モデルが格納されているリモートパス。たとえば、Hugging Face リポジトリでは、これはモデルファイルへのパスになります。
- PromptTemplate (Dictionary<string, string>、省略可能)
  内容：
  - system (string、省略可能)
    システムメッセージのテンプレート。
  - user (string、省略可能)ユーザーのメッセージのテンプレート。
  - assistant (string、省略可能)
    アシスタントの応答のテンプレート。
  - prompt (string、省略可能)
    ユーザーアシスタント操作のテンプレート。
- Publisher (string、省略可能)
  モデルの発行元です。
token (string、省略可能)
保護されたモデルの認証トークン (GitHub または Hugging Face)。
progressToken (オブジェクト、省略可能)
AITK の場合のみ。ダウンロードの進行状況を追跡するトークン。
customDirPath (string、省略可能)
カスタムダウンロードディレクトリ (CLI に使用されます。AITK には必要ありません)。
bufferSize (整数、省略可能)
HTTP ダウンロードバッファーサイズ (KB 単位)。 NIM または Azure Foundry モデルには影響しません。
ignorePipeReport (ブール値、省略可能)
true場合は、パイプではなく HTTP ストリーム経由で進行状況レポートを強制します。 AITK の場合は false 、Foundry Local の場合は true が既定値です。

ストリーミング応答:

ダウンロード中、サーバーは進行状況の更新を次の形式でストリーミングします。

("file name", percentage_complete)

最終的な応答本文:

Success (ブール値)
ダウンロードが正常に完了したかどうか。
ErrorMessage (string、省略可能)
ダウンロードに失敗した場合のエラーの詳細。

例:

リクエストの本文

{
  "model":{
    "Uri": "azureml://registries/azureml/models/Phi-4-mini-instruct-generic-cpu/versions/4",
    "ProviderType": "AzureFoundryLocal",
    "Name": "Phi-4-mini-instruct-generic-cpu",
    "Publisher": "",
    "promptTemplate" : {
      "system": "<|system|>{Content}<|end|>",
      "user": "<|user|>{Content}<|end|>", 
      "assistant": "<|assistant|>{Content}<|end|>", 
      "prompt": "<|user|>{Content}<|end|><|assistant|>"
    }
  }
}

応答ストリーム

("genai_config.json", 0.01)
("genai_config.json", 0.2)
("model.onnx.data", 0.5)
("model.onnx.data", 0.78)
...
("", 1)

最終的な応答

{
  "Success": true,
  "ErrorMessage": null
}

GET /openai/status

サーバーの状態情報を取得します。

応答本文:

Endpoints (文字列の配列)
HTTP サーバーバインドエンドポイント。
ModelDirPath (文字列)
ローカルモデルが格納されているディレクトリ。
PipeName (文字列)
現在の NamedPipe サーバー名。

例:

応答本文

{
  "Endpoints": ["http://localhost:5272"],
  "ModelDirPath": "/path/to/models",
  "PipeName": "inference_agent"
}

POST /v1/chat/completions/tokenizer/encode/count

推論を実行せずに、特定のチャット完了要求のトークンをカウントします。

リクエストボディ:

コンテンツタイプ: application/json
次の形式の JSON オブジェクト ChatCompletionCreateRequest 。
- model (文字列)
  トークン化に使用するモデル。
- messages (配列)
  roleとcontentを持つメッセージオブジェクトの配列。

レスポンスボディ:

コンテンツタイプ: application/json
トークン数を持つ JSON オブジェクト:
- tokenCount (整数)
  要求内のトークンの数。

例:

要求本文

{
  "messages": [
    {
      "role": "system",
      "content": "This is a system message"
    },
    {
      "role": "user",
      "content": "Hello, what is Microsoft?"
    }
  ],
  "model": "Phi-4-mini-instruct-cuda-gpu"
}

応答本文
```
{
  "tokenCount": 23
}
```

次の方法で共有

Foundry Local REST API リファレンス

OpenAI v1 の互換性

POST /v1/chat/completions

POST /v1/embeddings

カスタム API

GET /foundry/list

POST /openai/register

GET /openai/models

GET /openai/load/{name}

GET /openai/unload/{name}

GET /openai/unloadall

GET /openai/loadedmodels

GET /openai/getgpudevice

GET /openai/setgpudevice/{deviceId}

POST /openai/download

GET /openai/status

POST /v1/chat/completions/tokenizer/encode/count

フィードバック

その他のリソース