本文提供 Databricks Foundation 模型 API 及其支援的模型一般 API 資訊。 基礎模型 API 的設計類似於 OpenAI 的 REST API，讓移轉現有的專案更容易。 按令牌付費和預配置的吞吐量端點都接受相同的 REST API 請求格式。
端點
基礎模型介面支援按數據計費的 token 端點和預配置吞吐量端點。
每個支援令牌付費模型的工作區中都有預先設定的端點，使用者可以使用 HTTP POST 要求與這些端點互動。 如需支援的模型，請參閱 馬賽克 AI 模型服務上支援的基礎模型 。
您可以使用 API 或服務 UI來建立預置吞吐量端點
要求和回應會使用 JSON，確切的 JSON 結構取決於端點的工作類型。 聊天和完成端點支援串流回應。
用法
回應包括 usage 子訊息，該訊息報告了要求和回應中的令牌數目。 此子訊息的格式在所有工作類型中都相同。
| 领域 | 類型 | 描述 |
|---|---|---|
completion_tokens |
整數 | 產生的令牌數目。 不包含在內嵌回應中。 |
prompt_tokens |
整數 | 輸入提示中的標記數量。 |
total_tokens |
整數 | 令牌總數。 |
對於像 databricks-meta-llama-3-3-70b-instruct 這樣的模型，使用者提示在傳遞到模型之前，會先使用提示範本進行轉換。 針對按令牌付費的端點，可能會新增系統提示。
prompt_tokens 包含伺服器新增的所有文字。
聊天任務
聊天任務已針對使用模型進行多回合對話的情境進行優化。 模型回應會在交談中提供下一個 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。 |
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 |
函數呼叫完成 | 必要。 模型建議的函式呼叫。 |
FunctionCallCompletion
| 领域 | 類型 | 描述 |
|---|---|---|
name |
字串 | 必填。 模型建議的函式名稱。 |
arguments |
物件 | 必填。 函式的參數作為序列化的 JSON 字典。 |
ToolChoiceObject
請參閱 Azure Databricks上的
| 领域 | 類型 | 描述 |
|---|---|---|
type |
字串 |
必要。 工具的類型。 目前僅支援 "function"。 |
function |
物件 |
必要。 對象，定義要呼叫表單 {"type": "function", "function": {"name": "my_function"}} 的工具，其中 "my_function 是 欄位中 tools 的名稱。 |
ToolObject
請參閱 Azure Databricks上的
| 领域 | 類型 | 描述 |
|---|---|---|
type |
字串 |
必要。 工具的類型。 目前僅支援 function。 |
function |
FunctionObject | 必要。 與工具相關聯的函式定義。 |
FunctionObject
| 领域 | 類型 | 描述 |
|---|---|---|
name |
字串 | 必要。 要呼叫之函式的名稱。 |
description |
物件 | 必要。 函式的詳細描述。 此模型會使用此描述來瞭解函式與提示的相關性，併產生具有較高精確度的工具呼叫。 |
parameters |
物件 | 函式接受的參數，描述為有效的 JSON 架構 物件。 如果呼叫此工具，則工具呼叫會符合提供的 JSON 架構。 省略參數會定義不含任何參數的函式。
properties 的數量限制為 15 個鍵。 |
strict |
布爾 | 是否要在產生函數調用時啟用嚴格的架構遵循。 如果設定為 true，則模型會遵循架構字段中定義的確切架構。 當 strict 為 true 時，僅支援 JSON 架構的子集 |
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 |
字串 | 模型停止產生令牌的原因。 只有最後一個區塊會有這個內容。 |
完成任務
文字完成任務是用來生成對單一提示的回應。 不同於聊天，此工作支援批次輸入：可以在一個要求中傳送多個獨立提示。 如需查詢端點參數，請參閱 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 |
字串 | 模型停止產生令牌的原因。 |
內嵌工作
內嵌工作會將輸入字串對應至內嵌向量。 每個請求中可以將許多輸入一起進行批次處理。 如需查詢端點參數，請參閱 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） |