基礎模型 REST API 參考

  • 發行項

本文提供 Databricks 基礎模型 API 及其支援模型的一般 API 資訊。 基礎模型 API 的設計類似於 OpenAI 的 REST API，讓移轉現有專案更容易。 按權杖付費端點和佈建輸送量端點都接受相同的 REST API 要求格式。

端點

每個按權杖付費模型都有單一端點，而且使用者可以使用 HTTP POST 要求與這些端點互動。 可以使用 API 或服務 UI 來建立佈建的輸送量端點。 只要兩個服務模型都公開相同的 API 格式，這些端點也會針對 A/B 測試的每個端點支援多個模型。 例如，這兩個模型都是聊天模型。

要求和回應會使用 JSON，具體的 JSON 結構取決於端點的任務類型。 聊天端點和完成端點支援串流回應。

按權杖付費工作負載支援特定模型，請參閱按權杖付費的支援模型，以了解這些模型和接受的 API 格式。

使用方式

回應包含 usage 子訊息，其會報告要求和回應中的權杖數目。 此子訊息的格式在所有任務類型中都相同。

欄位 類型 描述
completion_tokens 整數 生成的權杖數目。 不包含在內嵌回應中。
prompt_tokens 整數 輸入提示中的權杖數目。
total_tokens 整數 權杖總數。

對於諸如 llama-2-70b-chat 等模型，使用者提示會在傳遞至模型之前，先使用提示範本進行轉換。 針對按權杖付費端點，可能也會新增系統提示。 prompt_tokens 包含伺服器新增的所有文字。

聊天任務

聊天任務已針對模型的多回合交談進行最佳化。 每個要求都會描述到目前為止的交談，其中 messages 欄位必須在 user 和 assistant 角色之間交替，並以 user 訊息結尾。 模型回應會在交談中提供下一則 assistant 訊息。

聊天要求

欄位 預設 類型 描述
messages ChatMessage 清單 必要。 代表目前交談的訊息清單。
max_tokens null null，表示沒有限制，或大於零的整數 生成的權杖數目上限。
stream true 布林值 將回應串流回用戶端，以允許要求的部分結果。 如果要求中包含此參數，則會使用伺服器傳送的事件標準來傳送回應。
temperature 1.0 [0,2] 範圍中的浮點數 取樣溫度。 0 具有確定性，較高的值會引入更多的隨機性。
top_p 1.0 (0,1] 範圍中的浮點數 用於核取樣的概率閾值。
top_k null null，表示沒有限制，或大於零的整數 定義最可能用於前 k 個篩選的 k 個標記數目。 將此值設定為 1，讓輸出具有確定性。
stop [] String 或 List[String] 當遇到 stop 中的任何序列時，模型會停止生成進一步的權杖。
n 1 大於零的整數 當指定 n 時，API 會傳回 n 獨立的聊天完成。 建議用於在相同輸入上生成多個完成的工作負載，以提高推斷效率並節省成本。 僅適用於佈建的輸送量端點。
tool_choice none String 或 ToolChoiceObject 僅搭配 tools 欄位使用。 tool_choice 支援各種關鍵字字串，例如 auto、required 和 none。 auto 表示您讓模型決定哪一種 (如果有的話) 工具與使用有關。 使用 auto 時，如果模型不認為 tools 中的任何工具有相關性，模型會生成標準助理訊息，而不是工具呼叫。 required 表示模型會在 tools 中挑選最相關的工具，而且必須生成工具呼叫。 none 表示模型不會生成任何工具呼叫，且必須生成標準助理訊息。 若要使用 tools 中定義的特定工具強制呼叫工具，請使用 ToolChoiceObject。 根據預設，如果 tools 欄位已填入 tool_choice = "auto"。 否則，tools 欄位預設為 tool_choice = "none"
tools null ToolObject 模型可以呼叫的 tools 清單。 目前，function 是唯一支援的 tool 類型，最多支援 32 個函數。
logprobs false 布林值 此參數指出是否提供取樣之權杖的記錄概率。
top_logprobs null 整數 此參數會控制每個取樣步驟中傳回記錄概率的最可能權杖候選項目數目。 可以為 0-20。 如果使用此欄位，logprobs 必須為 true。

ChatMessage

欄位 類型 描述
role String 必要。 訊息作者的角色。 可以是 "system"、"user"、"assistant" 或 "tool"。
content String 訊息的內容。 不涉及工具呼叫的聊天任務所需。
tool_calls ToolCall 清單 模型生成的 tool_calls 清單。 role 必須為 "assistant" 且 content 欄位沒有規格。
tool_call_id String 當 role 為 "tool" 時，與回應訊息之 ToolCall 相關聯的 ID。 其他 role 選項必須為空。

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

ToolCall

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

欄位 類型 描述
id String 必要。 此工具呼叫建議的唯一識別碼。
type String 必要。 只支援 "function"。
function FunctionCallCompletion 必要。 模型建議的函式呼叫。

FunctionCallCompletion

欄位 類型 描述
name String 必要。 模型建議的函式名稱。
arguments Object 必要。 函式的引數作為序列化 JSON 字典。

ToolChoiceObject

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

欄位 類型 描述
type String 必要。 工具的型別。 目前僅支援 "function"。
function Object 必要。 一個物件，它定義要呼叫表單 {"type": "function", "function": {"name": "my_function"}} 的工具，其中 "my_function 是 tools 欄位中 FunctionObject 的名稱。

ToolObject

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

欄位 類型 描述
type String 必要。 工具的型別。 目前僅支援 function。
function FunctionObject 必要。 與工具相關聯的函式定義。

FunctionObject

欄位 類型 描述
name String 必要。 要呼叫函式的名稱。
description Object 必要。 函式的詳細說明。 此模型會使用此描述來了解函式與提示的相關性，並生成具有較高精確度的工具呼叫。
parameters Object 函式接受的參數，描述為有效的 JSON 結構描述物件。 如果呼叫此工具，則工具呼叫會符合提供的 JSON 結構描述。 省略參數會定義不含任何參數的函式。 properties 的數目限制為 15 個索引鍵。

聊天回應

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

欄位 類型 描述
id String 聊天完成的唯一識別碼。
choices List[ChatCompletionChoice] 或 List[ChatCompletionChunk] (串流) 聊天完成文字的清單。 如果指定 n 參數，則會傳回 n 選擇。
object String 物件類型。 等於非串流的 "chat.completions" 或串流的 "chat.completion.chunk"。
created 整數 聊天完成的時間以秒為單位。
model String 用來生成回應的模型版本。
usage 使用方式 權杖使用方式中繼資料。 可能不會出現在串流回應中。

ChatCompletionChoice

欄位 類型 描述
index 整數 生成的選擇清單中的選擇索引。
message ChatMessage 模型傳回的聊天完成訊息。 角色將會是 assistant。
finish_reason String 模型停止產生權杖的原因。

ChatCompletionChunk

欄位 類型 描述
index 整數 生成的選擇清單中的選擇索引。
delta ChatMessage 模型所生成串流回應的聊天完成訊息部分。 只保證第一個區塊會填入 role。
finish_reason String 模型停止產生權杖的原因。 只有最後一個區塊才會填入。

完成任務

文字完成任務用來生成單一提示的回應。 不同於聊天，此任務支援批次輸入：可以在一個要求中傳送多個獨立提示。

完成要求

欄位 預設 類型 描述
prompt String 或 List[String] 必要。 模型的提示。
max_tokens null null，表示沒有限制，或大於零的整數 生成的權杖數目上限。
stream true 布林值 將回應串流回用戶端，以允許要求的部分結果。 如果要求中包含此參數，則會使用伺服器傳送的事件標準來傳送回應。
temperature 1.0 [0,2] 範圍中的浮點數 取樣溫度。 0 具有確定性，較高的值會引入更多的隨機性。
top_p 1.0 (0,1] 範圍中的浮點數 用於核取樣的概率閾值。
top_k null null，表示沒有限制，或大於零的整數 定義最可能用於前 k 個篩選的 k 個標記數目。 將此值設定為 1，讓輸出具有確定性。
error_behavior "error" "truncate" 或 "error" 針對逾時和超過內容長度的錯誤。 其中一個："truncate" (傳回盡可能多的權杖) 和 "error" (傳回錯誤)。 僅按權杖付費端點接受此參數。
n 1 大於零的整數 當指定 n 時，API 會傳回 n 獨立的聊天完成。 建議用於在相同輸入上生成多個完成的工作負載，以提高推斷效率並節省成本。 僅適用於佈建的輸送量端點。
stop [] String 或 List[String] 當遇到 stop 中的任何序列時，模型會停止生成進一步的權杖。
suffix "" String 附加至每個完成結尾的字串。
echo false 布林值 傳回提示以及完成。
use_raw_prompt false 布林值 如果為 true，則直接將 prompt 傳遞至模型，而不需要任何轉換。

完成回應

欄位 類型 描述
id String 文字完成的唯一識別碼。
choices CompletionChoice 文字完成的清單。 針對傳入的每個提示，如果已指定 n，就會產生 n 個選擇。 預設 n 為 1。
object String 物件類型。 等於 "text_completion"
created 整數 完成時間以秒為單位。
usage 使用方式 權杖使用方式中繼資料。

CompletionChoice

欄位 類型 描述
index 整數 要求中提示的索引。
text String 生成的完成。
finish_reason String 模型停止產生權杖的原因。

內嵌任務

內嵌任務會將輸入字串對應至內嵌向量。 在每個要求中，可以一起批處理許多輸入。

內嵌要求

欄位 類型 描述
input String 或 List[String] 必要。 要內嵌的輸入文字。 可以是字串或字串清單。
instruction String 傳遞至內嵌模型的選擇性指示。

指示是可選的且高度特定於模型。 例如，BGE 作者建議在編製區塊索引時不要使用指示，而建議使用指示 "Represent this sentence for searching relevant passages:" 來擷取查詢。 Instructor-XL 等其他模型支援多種指令字串。

內嵌回應

欄位 類型 描述
id String 內嵌的唯一識別碼。
object String 物件類型。 等於 "list"。
model String 用於建立內嵌的內嵌模型名稱。
data EmbeddingObject 內嵌物件。
usage 使用方式 權杖使用方式中繼資料。

EmbeddingObject

欄位 類型 描述
object String 物件類型。 等於 "embedding"。
index 整數 模型生成的內嵌清單中的內嵌索引。
embedding List[Float] 內嵌向量。 每個模型都會傳回固定大小的向量 (BGE-Large 為 1024)

其他資源