共用方式為

基礎模型 REST API 參考

本文提供 Databricks Foundation 模型 API 及其支援的模型一般 API 資訊。 基礎模型 API 的設計類似於 OpenAI 的 REST API，讓移轉現有的專案更容易。 按令牌付費和預配置的吞吐量端點都接受相同的 REST API 請求格式。

端點

基礎模型介面支援按數據計費的 token 端點和預配置吞吐量端點。

每個支援令牌付費模型的工作區中都有預先設定的端點，使用者可以使用 HTTP POST 要求與這些端點互動。 如需支援的模型，請參閱 馬賽克 AI 模型服務上支援的基礎模型 。

您可以使用 API 或服務 UI來建立預置吞吐量端點 。 只要兩個服務模型都公開相同的 API 格式，這些端點會針對 A/B 測試的每個端點支援多個模型。 例如，這兩個模型都是聊天模型。 如需端點組態參數，請參閱 POST /api/2.0/service-endpoints。

要求和回應會使用 JSON，確切的 JSON 結構取決於端點的工作類型。 聊天和完成端點支援串流回應。

用法

回應包括 usage 子訊息，該訊息報告了要求和回應中的令牌數目。 此子訊息的格式在所有工作類型中都相同。

领域 類型 描述
completion_tokens 整數 產生的令牌數目。 不包含在內嵌回應中。
prompt_tokens 整數 輸入提示中的標記數量。
total_tokens 整數 令牌總數。
reasoning_tokens 整數 思維標記的數量。 它僅適用於推理模型。

對於像 databricks-meta-llama-3-3-70b-instruct 這樣的模型，使用者提示在傳遞到模型之前，會先使用提示範本進行轉換。 針對按令牌付費的端點，可能會新增系統提示。 prompt_tokens 包含伺服器新增的所有文字。

回應 API

這很重要

Responses API 僅與 OpenAI 模型相容。

回應 API 允許與模型進行多回合對話。 與聊天完成不同，回應 API 使用 input 來取代 messages。

回應 API 請求

领域 預設 類型 描述
model 字串 必要。 用於產生回應的型號ID。
input 字串或清單[回應輸入] 必要。 用來讓模型產生回應的文字、影像或檔案輸入。 與 messages不同，此欄位用於 input 指定對話內容。
instructions null 字串 插入模型內容中的系統（或開發人員）訊息。
max_output_tokens null null，這表示沒有限制，或大於零的整數 可對回應所能產生的令牌數量設定上限，包括可見的輸出令牌和推理令牌。
temperature 1.0 浮點數範圍為 [0,2] 之內 取樣溫度。 0 是具決定性的，且較高的值引進了更多的隨機性。
top_p 1.0 浮點數值範圍在 (0,1] 之內 用於核取樣的機率臨界值。
stream false 布林值 如果設定為 true，則模型回應資料將會串流至用戶端，因為它是使用伺服器傳送的事件產生的。
stream_options null StreamOptions 串流回應的選項。 只有在您設定 stream: true 時，才設定此選項。
text null TextConfig 來自模型的文字回應組態選項。 可以是純文字或結構化 JSON 數據。
reasoning null ReasoningConfig GPT-5 與 O 系列模型的推理配置。
tool_choice "auto" 字串或 ToolChoiceObject 模型應該如何選取產生回應時要使用的工具（或工具）。 tools請參閱 參數，以瞭解如何指定模型可以呼叫的工具。
tools null 清單[工具物件] 模型可能會在產生回應時呼叫的工具陣列。 注意：Databricks 不支援程式碼直譯器與網頁搜尋工具。
parallel_tool_calls true 布林值 是否允許模型平行執行工具呼叫。
max_tool_calls null 大於零的整數 回應中可處理的內建工具呼叫總數上限。
metadata null 物件 可附加至物件的索引鍵/值組 (16 個為一組)。
prompt_cache_key null 字串 用於緩存類似請求的回應，以優化快取命中率。 取代了欄位 user。
prompt_cache_retention null 字串 提示快取的資料保留政策。 設定為 "24h" 以啟用延長提示快取，讓快取前綴持續更久，最長可達 24 小時。
safety_identifier null 字串 一個穩定的識別碼，用來協助偵測可能違反使用政策的應用程式使用者。
user null 字串 已被取代。 請改用 safety_identifier 和 prompt_cache_key。
truncation null 字串 用於模型回應的截斷策略。
top_logprobs null 整數 介於 0 到 20 之間的整數，其會指定最有可能在每個語彙基元位置傳回的語彙基元數目，每個都有相關聯的對數機率。
include null 列表[字串] 指定要包含在模型回應中的其他輸出數據。
prompt null 物件 關於提示範本及其變數的參考。

不支援的參數：以下參數 Databricks 不支援，若指定將回傳 400 錯誤：

  • background - 不支援背景處理
  • store - 不支援儲存的回應
  • conversation - 不支援對話 API
  • service_tier - 服務層級選擇由 Databricks 管理

ResponsesInput

該 input 欄位可接受包含角色與內容的輸入訊息物件的字串或清單。

领域 類型 描述
role 字串 必要。 消息作者的角色。 可以是 "user" 或 "assistant"。
content 字串或清單[回應內容阻擋] 必要。 訊息的內容，無論是字串還是內容區塊陣列。

ResponsesContentBlock

內容區塊定義了輸入與輸出訊息中的內容類型。 內容區塊類型由 type 欄位決定。

InputText
领域 類型 描述
type 字串 必要。 必須是 "input_text"。
text 字串 必要。 文字內容。
OutputText
领域 類型 描述
type 字串 必要。 必須是 "output_text"。
text 字串 必要。 文字內容。
annotations 清單[物件] 文本內容的選擇性註解。
InputImage
领域 類型 描述
type 字串 必要。 必須是 "input_image"。
image_url 字串 必要。 圖片的 URL 或經 base64 編碼的數據 URI。
InputFile
领域 類型 描述
type 字串 必要。 必須是 "input_file"。
file_id 字串 如果使用上傳檔案，則使用檔案識別碼。
filename 字串 檔案的檔名。
file_data 字串 Base64 編碼的資料 URI，格式前綴。 例如，PDF 檔案使用格式 data:application/pdf;base64,<base64 data>。
FunctionCall
领域 類型 描述
type 字串 必要。 必須是 "function_call"。
id 字串 必要。 函式呼叫的唯一識別碼。
call_id 字串 必要。 呼叫識別碼。
name 字串 必要。 被呼叫的函式名稱。
arguments 物件/字串 必要。 函式參數會以 JSON 物件或字串的形式存在。
FunctionCallOutput
领域 類型 描述
type 字串 必要。 必須是 "function_call_output"。
call_id 字串 必要。 此輸出對應的通話識別碼。
output 字串/物件 必要。 函式輸出為字串或 JSON 物件。

StreamOptions

串流回應的設定。 只有在 stream: true 時使用。

领域 類型 描述
include_usage 布林值 如果屬實，請在串流中包含代幣使用資訊。 預設值為 false。

TextConfig

文字輸出的配置，包括結構化輸出。

领域 類型 描述
format 回應格式物件 文字輸出的格式規範。

ResponsesFormatObject

指定文字回應的輸出格式。

领域 類型 描述
type 字串 必要。 格式類型： "text" 純文字、 "json_object" JSON "json_schema" 或結構化 JSON。
json_schema 物件 當type是"json_schema"時為必需。 定義輸出結構的 JSON 架構物件。

這個 json_schema 物件的結構與 Chat Completions API 中所記載的 JsonSchemaObject 相同。

ReasoningConfig

推理模型（O系列及GPT-5模型）中推理行為的配置。

领域 類型 描述
effort 字串 推理努力程度為： "low"、、 "medium"或 "high"。 預設值為 "medium"。
encrypted_content 字串 無狀態模式的加密推理內容。 模型在先前的回應中提供了這些資訊。

ToolObject

請參閱 Azure Databricks上的 函式呼叫。

领域 類型 描述
type 字串 必要。 工具的類型。 目前僅支援 function。
function FunctionObject 必要。 與工具相關聯的函式定義。

FunctionObject

领域 類型 描述
name 字串 必要。 要呼叫之函式的名稱。
description 物件 必要。 函式的詳細描述。 此模型會使用此描述來瞭解函式與提示的相關性，併產生具有較高精確度的工具呼叫。
parameters 物件 函式接受的參數，描述為有效的 JSON 架構 物件。 如果呼叫此工具，則工具呼叫會符合提供的 JSON 架構。 省略參數會定義不含任何參數的函式。 properties 的數量限制為 15 個鍵。
strict 布林值 是否要在產生函數調用時啟用嚴格的架構遵循。 如果設定為 true，則模型會遵循架構字段中定義的確切架構。 當 strict 為 true 時，僅支援 JSON 架構的子集

ToolChoiceObject

請參閱 Azure Databricks上的 函式呼叫。

领域 類型 描述
type 字串 必要。 工具的類型。 目前僅支援 "function"。
function 物件 必要。 對象，定義要呼叫表單 {"type": "function", "function": {"name": "my_function"}} 的工具，其中 "my_function 是 欄位中 tools 的名稱。

回應 API 回應

對於非串流請求，回應為單一回應物件。 對於串流請求，回應是 a text/event-stream ，每個事件都是一個回應區塊。

领域 類型 描述
id 字串 回應的唯一標識碼。 注意：Databricks 會加密此 ID。
object 字串 物件類型。 等於 "response"。
created_at 整數 回應產生時的 Unix 時間戳記（以秒計）。
status 字串 回應的狀態。 其中一個：completed、failed、in_progress、cancelledqueued或incomplete。
model 字串 用來產生回應的模型版本。
output 清單[回應訊息] 模型產生的輸出通常包含訊息物件。
usage 使用量 令牌使用情況元數據。
error Error 如果回應失敗，則提供錯誤資訊。
incomplete_details 不完整的詳細資料 如果適用，請說明為何回應不完整。
instructions 字串 請願書中提供的指示。
max_output_tokens 整數 請求中指定的最大輸出標記。
temperature 浮動 產生時使用的溫度。
top_p 浮動 產生時使用的 top_p 值。
tools 清單[工具物件] 申請中指定的工具。
tool_choice 字串或 ToolChoiceObject 請求中的 tool_choice 設定。
parallel_tool_calls 布林值 是否啟用了平行工具呼叫。
store 布林值 是否儲存了回應。
metadata 物件 附帶在回應上的元資料。

ResponsesMessage

包含模型回應內容的 output 欄位中的訊息物件。

领域 類型 描述
id 字串 必要。 訊息的唯一識別碼。
role 字串 必要。 訊息的角色。 "user" 或 "assistant"。
content 列表[回應內容區塊] 必要。 訊息中的內容區塊。
status 字串 訊息處理狀態。
type 字串 必要。 物件類型。 等於 "message"。

Error

回應失敗時的錯誤資訊。

领域 類型 描述
code 字串 必要。 錯誤碼。
message 字串 必要。 人類可以看懂的錯誤訊息。
param 字串 如果適用，造成錯誤的參數。
type 字串 必要。 錯誤類型。

IncompleteDetails

說明回應不完整的原因。

领域 類型 描述
reason 字串 必要。 原因在於回答不完整。

聊天完成 API

聊天完成 API 允許與模型進行多回合對話。 模型回應會在交談中提供下一個 assistant 訊息。 如需查詢端點參數，請參閱 POST /serving-endpoints/{name}/invocations。

聊天要求

领域 預設 類型 描述
messages ChatMessage 清單 必要。 代表目前交談的訊息清單。
max_tokens null null，這表示沒有限制，或大於零的整數 要產生的令牌數目上限。
stream true 布林值 將回應以串流方式發送回用戶端，從而允許返回部分結果。 如果要求中包含此參數，則會使用 伺服器傳送的事件 標準來傳送回應。
temperature 1.0 浮點數範圍為 [0,2] 之內 取樣溫度。 0 是具決定性的，且較高的值引進了更多的隨機性。
top_p 1.0 浮點數值範圍在 (0,1] 之內 用於核取樣的機率臨界值。
top_k null null，這表示沒有限制，或大於零的整數 定義最可能用於 top-k-filtering 的 k 標記數目。 將此值設定為 1，讓輸出具決定性。
stop [] 字串或清單[字串] 當遇到 stop 中的任何序列時，模型會停止產生進一步的令牌。
n 1 大於零的整數 API 在指定 n 時會返回 n 個獨立的聊天完成結果。 建議用於在相同輸入上產生多個完成的工作負載，這樣可以提高推斷效能並節省成本。 僅適用於已配置的吞吐量端點。
tool_choice none 字串或 ToolChoiceObject 僅與 [tools] 字段搭配使用。 tool_choice 支援各種關鍵字字串，例如 auto、required和 none。 auto 表示您讓模型決定哪一個工具（如果有的話）是適合使用的。 如果模型不認為auto中的任何工具相關，模型會產生標準助理訊息，而不是進行工具呼叫。 required 表示模型會挑選 tools 中最相關的工具，而且必須產生工具呼叫。 none 表示模型不會產生任何工具呼叫，而必須產生標準助理訊息。 若要強制呼叫在tools中定義的特定工具，請使用ToolChoiceObject。 根據預設，當 tools 欄位已填入時 tool_choice = "auto"。 否則，tools 欄位預設為 tool_choice = "none"
tools null ToolObject 模型可以呼叫的 tools 清單。 目前，function 是唯一支援的 tool 類型，最多支援32個函式。
response_format null ResponseFormatObject 物件，指定模型必須輸出的格式。 接受的類型為 text、json_schema 或 json_object
將 設定為 { "type": "json_schema", "json_schema": {...} } 可啟用結構化輸出，以確保模型遵循您提供的 JSON 架構。
將 設定為 { "type": "json_object" } 可確保模型產生的回應是有效的 JSON，但不會確保回應遵循特定架構。
logprobs false 布林值 此參數指出是否提供取樣字詞的對數機率。
top_logprobs null 整數 此參數會調整每個取樣步驟中傳回對數機率的最有可能標記候選項目數目。 可以是 0-20。 如果使用此欄位，則 logprobs 必須是 true。
reasoning_effort "medium" 字串 控制產生回應時，模型應套用的推理工作層級。 接受的值為 "low"、 "medium"或 "high"。 較高的推理工作可能會導致更周到且精確的回應，但可能會增加延遲和令牌使用量。 此參數只接受一組有限的模型，包括 databricks-gpt-oss-120b 和 databricks-gpt-oss-20b。

ChatMessage

领域 類型 描述
role 字串 必要。 訊息作者的角色。 可以是 "system"、"user"、"assistant" 或 "tool"。
content 字串 訊息的內容。 必要的，適用於不需要工具呼叫的聊天工作。
tool_calls ToolCall 清單 模型產生的 tool_calls 清單。 必須具有 role 作為 "assistant"，且沒有 content 字段的規格。
tool_call_id 字串 當 role 是 "tool"時，ID 與訊息回應的 ToolCall 相關聯。 其他 role 選項必須空白。

system 角色只能使用一次，作為交談中的第一則訊息。 它會覆寫模型的預設系統提示。

ToolCall

由模型提供的工具調用動作建議。 請參閱 Azure Databricks上的 函式呼叫。

领域 類型 描述
id 字串 必要。 此工具呼叫建議的唯一識別碼。
type 字串 必要。 僅支援 "function"。
function 函數呼叫完成 必要。 模型建議的函式呼叫。
cache_control 字串 啟用您的請求的快取功能。 此參數僅供 Databricks 裝載的 Claude 模型接受。 如需範例，請參閱 提示緩存 。

FunctionCallCompletion

领域 類型 描述
name 字串 必填。 模型建議的函式名稱。
arguments 物件 必填。 函式的參數作為序列化的 JSON 字典。

注意：ToolChoiceObject、ToolObject 和 FunctionObject 是在 回應 API 章節 中定義的，並且在兩個 API 之間共用。

ResponseFormatObject

請參閱 Azure Databricks上的 結構化輸出。

领域 類型 描述
type 字串 必要。 正在定義的回應格式類型。 選擇 text 用於非結構化文字，或 json_object 用於非結構化的 JSON 物件，或 json_schema 用於符合特定架構的 JSON 物件。
json_schema JsonSchemaObject 必要。 如果 type 被設定為 json_schema，必須遵從的 JSON 架構

JsonSchemaObject

請參閱 Azure Databricks上的 結構化輸出。

领域 類型 描述
name 字串 必要。 回應格式的名稱。
description 字串 模型使用回應格式的描述來確定如何以該格式進行回應。
schema 物件 必要。 回應格式的架構，描述為 JSON 架構物件。
strict 布林值 是否要在產生輸出時啟用嚴格的架構遵循。 如果設定為 true，則模型會遵循架構字段中定義的確切架構。 當 strict 為 true 時，僅支援 JSON 架構的子集

聊天回應

對於非串流要求，回應是單一聊天完成物件。 對於串流請求，回應是 text/event-stream，其中每個事件都是一個完成的分塊物件。 完成和區塊物件的最上層結構幾乎完全相同：只有 choices 具有不同的類型。

领域 類型 描述
id 字串 聊天完成的唯一識別碼。
choices List[ChatCompletionChoice] 或 List[ChatCompletionChunk]（串流） 聊天完成文本列表。 如果指定了 n 參數，則會傳回 n 選項。
object 字串 物件類型。 等於非串流的 "chat.completions" 或串流的 "chat.completion.chunk"。
created 整數 聊天完成的時間以秒為單位。
model 字串 用來產生回應的模型版本。
usage 使用量 令牌使用情況元數據。 串流回應中可能不存在。

ChatCompletionChoice

领域 類型 描述
index 整數 所產生選項清單中的選擇索引。
message ChatMessage 模型傳回的聊天完成訊息。 角色將會 assistant。
finish_reason 字串 模型停止產生令牌的原因。
extra_fields 字串 從外部模型提供者使用專屬模型時，提供者的 API 可能會包含回應中的其他元數據。 Databricks 會篩選這些回應，並只傳回提供者原始欄位的子集。 safetyRating這是目前唯一支援的額外字段，請參閱雙子座檔以取得詳細數據。

ChatCompletionChunk

领域 類型 描述
index 整數 所產生選項清單中的選擇索引。
delta ChatMessage 由模型生成的串流回應中的聊天完成訊息部分。 只有第一個區塊保證填入 role。
finish_reason 字串 模型停止產生令牌的原因。 只有最後一個區塊會有這個內容。

嵌入 API

內嵌工作會將輸入字串對應至內嵌向量。 每個請求中可以將許多輸入一起進行批次處理。 如需查詢端點參數，請參閱 POST /serving-endpoints/{name}/invocations。

嵌入請求

领域 類型 描述
input 字串或清單[字串] 必要。 需要嵌入的輸入文字。 可以是字串或字串清單。
instruction 字串 傳遞至嵌入模型的可選指令。

說明是選擇性的，且非常依賴具體的模型。 例如，BGE 作者建議在索引區塊時不使用指令，並建議使用該指令 "Represent this sentence for searching relevant passages:" 進行擷取查詢。 其他模型，例如 Instructor-XL 支持各種不同的指令字串。

內嵌回應

领域 類型 描述
id 字串 嵌入的唯一標識碼。
object 字串 物件類型。 等於 "list"。
model 字串 用於生成嵌入的嵌入模型名稱。
data EmbeddingObject 內嵌物件。
usage 使用量 令牌使用情況元數據。

EmbeddingObject

领域 類型 描述
object 字串 物件類型。 等於 "embedding"。
index 整數 生成模型的嵌入列表中的嵌入索引。
embedding 列表[List[Float]] 內嵌向量。 每個模型都會傳回固定大小向量（BGE-Large為 1024）

自動完成 API

文字完成任務是用來生成對單一提示的回應。 不同於聊天，此工作支援批次輸入：可以在一個要求中傳送多個獨立提示。 如需查詢端點參數，請參閱 POST /serving-endpoints/{name}/invocations。

完成請求

领域 預設 類型 描述
prompt 字串或清單[字串] 必要。 模型的提示詞。
max_tokens null null，這表示沒有限制，或大於零的整數 要產生的令牌數目上限。
stream true 布林值 將回應以串流方式發送回用戶端，從而允許返回部分結果。 如果要求中包含此參數，則會使用 伺服器傳送的事件 標準來傳送回應。
temperature 1.0 浮點數範圍為 [0,2] 之內 取樣溫度。 0 是具決定性的，且較高的值引進了更多的隨機性。
top_p 1.0 浮點數值範圍在 (0,1] 之內 用於核取樣的機率臨界值。
top_k null null，這表示沒有限制，或大於零的整數 定義最可能用於 top-k-filtering 的 k 標記數目。 將此值設定為 1，讓輸出具決定性。
error_behavior "error" "truncate" 或 "error" 針對逾時或上下文長度超出的錯誤。 其中之一："truncate"（盡可能多地傳回令牌）或 "error"（傳回錯誤）。 此參數僅適用於按令牌計費的端點。
n 1 大於零的整數 API 在指定 n 時會返回 n 個獨立的聊天完成結果。 建議用於在相同輸入上產生多個完成的工作負載，這樣可以提高推斷效能並節省成本。 僅適用於已配置的吞吐量端點。
stop [] 字串或清單[字串] 當遇到 stop 中的任何序列時，模型會停止產生進一步的令牌。
suffix "" 字串 附加至每個完成結尾的字串。
echo false 布林值 傳回提示詞與完成的結果。
use_raw_prompt false 布林值 如果 true，請將 prompt 直接傳遞至模型，而不需要任何轉換。

完成回應

领域 類型 描述
id 字串 文字完成的唯一識別碼。
choices 完成選擇 文本完成清單。 針對傳入的每個提示，如果指定 n，就會產生 n 選項。 默認 n 為 1。
object 字串 物件類型。 等於 "text_completion"
created 整數 生成完成時間以秒為單位。
usage 使用量 令牌使用情況元數據。

CompletionChoice

领域 類型 描述
index 整數 要求中的提示索引號。
text 字串 生成的結果
finish_reason 字串 模型停止產生令牌的原因。

其他資源

  • Last updated on