Foundry Local REST API 指南參考

這很重要

Foundry Local 提供預覽版。公開預覽版本可讓您搶先試用正在開發期間的功能。
正式發行前的功能、方法和程序可能會變更或有功能上的限制。

謹慎

此 API 指的是 Foundry 本地 CLI 中可用的 REST API。此 API 正在積極開發中，且可能包含重大變更，不另行通知。強烈建議在建置生產應用程式之前監視變更記錄。

POST /v1/聊天/完成項目

此端點會處理聊天完成要求。
它與 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_tokens （整數，選擇性）
模型可以產生的字元數目上限，包括可見結果和推理過程中的字元。
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": "qwen2.5-0.5b-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": "qwen2.5-0.5b-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
    }
  }

取得 /openai/status

取得伺服器狀態資訊。

回應主體：

Endpoints （字串陣列）
HTTP 伺服器系結端點。
ModelDirPath (字串)
儲存本機模型的目錄。
PipeName (字串)
目前的 NamedPipe 伺服器名稱。

範例：

回應主體

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

取得/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。

取得 /openai/models

取得快取模型清單，包括本地及註冊的外部模型。

回應：

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

範例：

回應主體

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

POST /openai/下載

從目錄下載模型到本地儲存。

備註

大型模型下載可能需要很長時間。為此請求設定高逾時，以避免提前終止。

請求主體：

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 （字串，選擇性）
下載失敗時的錯誤詳細數據。

範例：

請求網址識別碼 (URI)

POST /openai/download

請求主體

請注意，型號名稱中必須加上版本後綴。

{
  "model": {
    "Uri": "azureml://registries/azureml/models/Phi-4-mini-instruct-generic-cpu/versions/4",
    "ProviderType": "AzureFoundryLocal",
    "Name": "Phi-4-mini-instruct-generic-cpu:4",
    "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
  }

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

取得 /openai/unload/{name}

從記憶體中卸載模型。

URI 參數：

name （弦樂）要卸貨的型號名稱。

查詢參數：

force （布林值，選用）如果 true，則會忽略 TTL 設定並立即卸載。

回應：

200 OK 空回應體

範例：

請求網址識別碼 (URI)

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

取得 /openai/unloadall

從記憶體卸除所有模型。

回應：

200 確定
空白回應內容

取得 /openai/loadedmodels

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

回應：

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

範例：

回應主體

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

取得 /openai/getgpu裝置

取得目前的 GPU 裝置識別碼。

回應：

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

取得 /openai/setgpudevice/{deviceId}

設定作用中的 GPU 裝置。

URI 參數：

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

回應：

200 確定
空白回應內容

範例：

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

發布 /v1/聊天/完成/標記器/編碼/計數

計算指定的聊天完成請求的令牌 (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
  }

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-02-28

共用方式為

Foundry Local REST API 指南參考

POST /v1/聊天/完成項目

取得 /openai/status

取得/foundry/list

取得 /openai/models

POST /openai/下載

獲取 /openai/load/{name}

取得 /openai/unload/{name}

取得 /openai/unloadall

取得 /openai/loadedmodels

取得 /openai/getgpu裝置

取得 /openai/setgpudevice/{deviceId}

發布 /v1/聊天/完成/標記器/編碼/計數

意見反應

其他資源