Foundry Local REST API 指南參考

2025-06-10

這很重要

Foundry Local 可在預覽中取得。公開預覽版本提供使用中部署中功能的早期存取權。
正式運作前的功能、方法和程式可以變更或具有有限的功能。

謹慎

此 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 （字串，選擇性）
使用者的唯一標識符，可協助監視和濫用預防。
functions （陣列，選擇性）
模型可以產生 JSON 輸入的可用函式。
- 每個函式都必須包含：
  - name (字串)
    函式名稱。
  - description (字串)
    功能描述。
  - parameters （物件）
    定義為 JSON 架構物件的函式參數。
function_call （字串或物件，選擇性）
控制模型回應函式呼叫的方式。
- 如果是物件，則可能包括：
  - name （字串，選擇性）
    要呼叫的函式名稱。
  - arguments （物件，選擇性）
    要傳遞至函式的參數。
metadata （物件，選擇性）
元數據索引鍵/值組的字典。
top_k （數字，選擇性）
保留用於 top-k 篩選的最高機率詞彙標籤數量。
random_seed （整數，選擇性）
為生成可重現隨機數的過程設置的種子。
ep （字串，選擇性）
覆寫 ONNX 模型的提供者。支援："dml"、"cuda"、"qnn"、"cpu"、"webgpu"。
ttl （整數，選擇性）
記憶體中模型存留時間以秒為單位。
tools （物件，選擇性）
針對要求計算的工具。

回應主體：

id (字串)
聊天完成的唯一識別碼。
object (字串)
物件類型，總是"chat.completion"。
created （整數）
在 Epoch 秒內建立時間戳。
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 內嵌 API 相容

請求主體：

model (字串)
要使用的內嵌模型（例如）。 "text-embedding-ada-002"
input （字串或陣列）
要嵌入的文字輸入。可以是單一字串或字串/令牌陣列。
encoding_format （字串，選擇性）
編碼格式（"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 確定
空白回應內容

範例︰

請求內容

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

GET /openai/models

擷取所有可用的模型，包括本機模型和已註冊的外部模型。

回應：

200 確定
模型名稱陣列，每個元素皆為字串。

範例︰

回應內容

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

GET /openai/load/{name}

將模型載入記憶體中，以加快推斷速度。

URI 參數：

name (字串)
要載入的模型名稱。

查詢參數：

unload （布爾值，選擇性）
是否要在模型閒置時間後自動卸載模型。預設為 true。
ttl （整數，選擇性）
存留時間（秒）。如果大於 0，則會覆蓋unload參數。
ep （字串，選擇性）
執行提供者用來運行此模型。支援："dml"、"cuda"、"qnn"、"cpu"、"webgpu"。
如果未指定，將使用genai_config.json的設定。

回應：

200 確定
空白回應內容

範例︰

要求 URI

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

GET /openai/unload/{name}

從記憶體卸載模型。

URI 參數：

name (字串)
要卸除的模型名稱。

查詢參數：

force （布爾值，選擇性）
如果 true 為空，則會忽略 TTL 設定並立即卸載。

回應：

200 確定
空白回應內容

範例︰

要求 URI

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

GET /openai/unloadall

從記憶體卸除所有模型。

回應：

200 確定
空白回應內容

GET /openai/loadedmodels

擷取目前載入的模型清單。

回應：

200 確定
模型名稱陣列，每個元素皆為字串。

範例︰

回應內容

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

GET /openai/getgpudevice

擷取目前選取的 GPU 裝置標識碼。

回應：

200 確定
表示目前 GPU 裝置識別碼的整數。

GET /openai/setgpudevice/{deviceId}

設定作用中的 GPU 裝置。

URI 參數：

deviceId （整數）
要使用的 GPU 裝置識別碼。

回應：

200 確定
空白回應內容

範例︰

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

POST /openai/download

將模型下載到本機記憶體。

備註

模型下載可能需要相當長的時間，尤其是大型模型。建議您為此要求設定高逾時，以避免過早終止。

請求主體：

model （WorkspaceInferenceModel 物件）
- Uri (字串)
  要下載的模型 URI。
- Name （字串）模型名稱。
- ProviderType （字串，選擇性）
  提供者類型（例如，"AzureFoundryLocal""HuggingFace"）。
- Path （字串，選擇性）
  存放模型的遠端路徑。例如，在 Hugging Face 資料庫中，這會是模型檔案所在的路徑。
- PromptTemplate （Dictionary<string, string>，選擇性）
  包含：
  - system （字串，選擇性）
    系統訊息的範本。
  - user （字串，選擇性）使用者訊息的範本。
  - assistant （字串，選擇性）
    助理回應的範本。
  - prompt （字串，選擇性）
    使用者助理互動的範本。
- Publisher （字串，選擇性）
  模型的發行者。
token （字串，選擇性）
用於受保護模型的驗證 token（GitHub 或 Hugging Face）。
progressToken （物件，選擇性）
僅適用於 AITK。追蹤下載進度的令牌。
customDirPath （字串，選擇性）
自定義下載目錄（用於 CLI，AITK 不需要）。
bufferSize （整數，選擇性）
以 KB 為單位的 HTTP 下載緩衝區大小。對 NIM 或 Azure Foundry 模型沒有任何影響。
ignorePipeReport （布爾值，選擇性）
如果 true為，則會強制透過 HTTP 數據流進行進度報告，而不是使用管道。預設 false 為 AITK，true 為 Foundry Local。

串流回應：

在下載期間，伺服器會以下列格式串流進行更新：

("file name", percentage_complete)

最終回應內容：

Success (布林值)
下載是否成功完成。
ErrorMessage （字串，選擇性）
下載失敗時的錯誤詳細數據。

範例︰

請求主體

{
  "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

計算指定的聊天完成請求的令牌 (token)，而不進行推斷。

請求主體：

Content-Type：application/json
JSON 物件 ChatCompletionCreateRequest 格式為：
- model (字串)
  要用於標記化的模型。
- messages （陣列）
  具有 role 和 content的訊息物件陣列。

回應主體：

Content-Type：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

意見反應

其他資源