基礎模型 REST API 參考

文章
11/02/2024

本文提供 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 個函數。
`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`	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 個索引鍵。
`strict`	布林值	是否要在產生函式呼叫時啟用嚴格的結構描述遵循。如果設定為 `true`，則模型會遵循架構字段中定義的確切架構。當 strict 為時，僅支援 JSON 架構的子集 `true`

`ResponseFormatObject`

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

欄位	類型	描述
`type`	String	必要。正在定義的回應格式類型。 `text`適用於非結構化文字、`json_object`非結構化 JSON 物件，或`json_schema`針對遵守特定架構的 JSON 物件。
`json_schema`	JsonSchemaObject	必要。如果 `type` 設定為，則遵守的 JSON 架構 `json_schema`

`JsonSchemaObject`

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

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

聊天回應

對於非串流要求，回應是單一聊天完成物件。對於串流要求，回應是 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)

分享方式：