基礎模型 REST API 參考
本文提供 Databricks Foundation 模型 API 及其支援的模型一般 API 資訊。 基礎模型 API 的設計類似於 OpenAI 的 REST API，讓移轉現有的專案更容易。 按令牌付費和預配置的吞吐量端點都接受相同的 REST API 請求格式。
端點
每個付費模式的模型都有單一端點，而且使用者可以使用 HTTP POST 要求與這些端點進行互動。 您可以使用 API 或服務 UI來建立預置吞吐量端點
要求和回應會使用 JSON，確切的 JSON 結構取決於端點的工作類型。 聊天和完成端點支援串流回應。
某些模型支持按令牌付費作業，請參閱 支援的模型和可接受的 API 格式，了解這些模型與按令牌付費相關的資訊。
用法
回應包括 usage 子訊息，該訊息報告了要求和回應中的令牌數目。 此子訊息的格式在所有工作類型中都相同。
| 领域 | 類型 | 描述 |
|---|---|---|
completion_tokens |
整數 | 產生的令牌數目。 不包含在內嵌回應中。 |
prompt_tokens |
整數 | 輸入提示中的字串數量。 |
total_tokens |
整數 | 令牌總數。 |
對於像 llama-2-70b-chat 這樣的模型，使用者提示在傳遞到模型之前，會先使用提示範本進行轉換。 針對按令牌付費的端點，可能會新增系統提示。
prompt_tokens 包含伺服器新增的所有文字。
聊天任務
聊天任務已針對模型的多回合對話進行優化。 模型回應會在交談中提供下一個 assistant 訊息。 如需查詢端點 ，請參閱 parameters。
聊天要求
| 领域 | 預設 | 類型 | 描述 |
|---|---|---|---|
messages |
ChatMessagelist | 必要。 代表目前交談之訊息的 list。 | |
max_tokens |
null |
null，這表示沒有 limit，或大於零的整數 |
用於 generate的令牌數目上限。 |
stream |
true |
布爾 | 將回應以串流方式發送回用戶端，從而允許返回部分結果。 如果要求中包含此參數，則會使用 伺服器傳送的事件 標準來傳送回應。 |
temperature |
1.0 |
浮點數在 [0,2] 之間 | 取樣溫度。 0 具決定性且較高 values 引進更多隨機性。 |
top_p |
1.0 |
浮點數在 (0,1] 之間 | 用於核取樣的機率臨界值。 |
top_k |
null |
null，這表示沒有 limit，或大於零的整數 |
定義最可能用於 top-k-filtering 的 k 標記數目。 Set 此值設定為 1，讓輸出具決定性。 |
stop |
[] | 字串或 List[字串] | 當遇到 stop 中的任何序列時，模型會停止產生進一步的令牌。 |
n |
1 | 大於零的整數 | API 在指定 n 時會返回 n 個獨立的聊天完成結果。 建議用於在相同輸入上 generate 多個完成的工作負載，以節省額外的推斷效率和節省成本。 僅適用於已配置的吞吐量端點。 |
tool_choice |
none |
字串或 ToolChoiceObject | 僅與 [tools] 字段搭配使用。
tool_choice 支援各種關鍵字字串，例如 auto、required和 none。
auto 表示您讓模型決定哪一種（如果有的話）工具與使用有關。
auto 如果模型不認為 tools 中的任何工具都相關，則模型會產生標準助理訊息，而不是工具呼叫。
required 表示模型會從 tools 中挑選最相關的工具，並且必須進行 generate 工具呼叫。
none 表示模型不會 generate 任何工具呼叫，而必須 generate 標準助理訊息。 若要使用 tools中定義的特定工具強制呼叫工具，請使用 ToolChoiceObject。 根據預設，如果填入 tools 欄位 tool_choice = "auto"。 否則，tools 欄位預設為 tool_choice = "none" |
tools |
null |
ToolObject | 模型可以呼叫的 list 的 tools。 目前，function 是唯一支援的 tool 類型，最多支援32個函式。 |
response_format |
null |
ResponseFormatObject | 物件，指定模型必須輸出的格式。 接受的類型為 text、json_schema 或 json_object將 設定為 { "type": "json_schema", "json_schema": {...} } 可開啟結構化輸出，以確保模型遵循您提供的 JSON schema。設定為 { "type": "json_object" } 可確保模型產生的回應是有效的 JSON，但無法確保回應遵循特定的 schema。 |
logprobs |
false |
布爾 | 此參數指出是否提供取樣字詞的對數機率。 |
top_logprobs |
null |
整數 | 此參數會調整每個取樣步驟中傳回對數機率的最有可能標記候選項目數目。 可以是 0-20。 如果使用此欄位，則 logprobs 必須是 true。 |
ChatMessage
| 领域 | 類型 | 描述 |
|---|---|---|
role |
字串 |
必要。 訊息作者的角色。 可以是 "system"、"user"、"assistant" 或 "tool"。 |
content |
字串 | 訊息的內容。 必要的，適用於不需要工具呼叫的聊天工作。 |
tool_calls |
ToolCalllist | 模型產生的 listtool_calls。 必須具有 role 作為 "assistant"，且沒有 content 字段的規格。 |
tool_call_id |
字串 | 當 role 是 "tool"時，標識符與該訊息所回應的 ToolCall 相關聯。 其他 role 選項必須空白。 |
system 角色只能使用一次，作為交談中的第一則訊息。 它會覆寫模型的預設系統提示字元。
ToolCall
模型的工具呼叫動作建議。 請參閱 Azure Databricks上的
| 领域 | 類型 | 描述 |
|---|---|---|
id |
字串 | 必要。 呼叫建議用的這個工具有一個獨特的 identifier。 |
type |
字串 |
必要。 僅支援 "function"。 |
function |
函數呼叫完成 | 必要。 模型建議的函式呼叫。 |
FunctionCallCompletion
| 领域 | 類型 | 描述 |
|---|---|---|
name |
字串 | 必填。 模型建議的函式名稱。 |
arguments |
物件 | 必填。 函式的參數作為序列化的 JSON 字典。 |
ToolChoiceObject
請參閱 Azure Databricks上的
| 领域 | 類型 | 描述 |
|---|---|---|
type |
字串 |
必要。 工具的類型。 目前僅支援 "function"。 |
function |
物件 |
必要。 對象，定義表單 {"type": "function", "function": {"name": "my_function"}}where"my_function 呼叫的工具是 欄位中 tools 的名稱。 |
ToolObject
請參閱 Azure Databricks上的
| 领域 | 類型 | 描述 |
|---|---|---|
type |
字串 |
必要。 工具的類型。 目前僅支援 function。 |
function |
FunctionObject | 必要。 與工具相關聯的函式定義。 |
FunctionObject
| 领域 | 類型 | 描述 |
|---|---|---|
name |
字串 | 必要。 要呼叫之函式的名稱。 |
description |
物件 | 必要。 函式的詳細描述。 此模型使用這個描述來理解函式與提示的相關性，並能更準確地進行工具呼叫（generate）。 |
parameters |
物件 |
parameters 函式接受的物件，被描述為有效的 JSON schema 物件。 如果呼叫此工具，則工具呼叫會符合提供的 JSON schema 中的要求。 省略 parameters 會定義一個沒有 parameters的函式。
properties 的數量限制為 15 個鍵。 |
strict |
布爾 | 是否要在產生函數調用時啟用嚴格 schema 遵循。 如果 set，true，模型會遵循在 schema 欄位中定義的確切 schema。 當 strict 為 schema 時，僅支援 JSON true 子集 |
ResponseFormatObject
請參閱 Azure Databricks上的
| 领域 | 類型 | 描述 |
|---|---|---|
type |
字串 |
必要。 正在定義的回應格式類型。 非結構化文字使用 text，非結構化 JSON 物件使用 json_object，或符合特定 json_schema的 JSON 物件使用 schema。 |
json_schema |
JsonSchemaObject |
必要。 當 schema 是 type 到 set 時，需要遵守的 JSON 是 json_schema |
JsonSchemaObject
請參閱 Azure Databricks上的
| 领域 | 類型 | 描述 |
|---|---|---|
name |
字串 | 必要。 回應格式的名稱。 |
description |
字串 | 模型會使用回應格式的描述，以判斷如何以格式回應。 |
schema |
物件 | 必要。 回應格式的 schema，被描述為一個 JSON schema 物件。 |
strict |
布爾 | 是否要在產生輸出時啟用嚴格的 schema 遵循。 如果 set，true，模型會遵循在 schema 欄位中定義的確切 schema。 當 strict 為 schema 時，僅支援 JSON true 子集 |
聊天回應
對於非串流要求，回應是單一聊天完成物件。 對於串流請求，回應是 text/event-streamwhere，各事件為完成區塊物件。 完成和區塊物件的最上層結構幾乎完全相同：只有 choices 具有不同的類型。
| 领域 | 類型 | 描述 |
|---|---|---|
id |
字串 | 聊天完成的唯一識別碼 identifier。 |
choices |
List[ChatCompletionChoice] 或 List[ChatCompletionChunk] （streaming） |
List 聊天完成文本。 如果指定了 n 參數，則會傳回 n 選項。 |
object |
字串 | 物件類型。 等於非串流的 "chat.completions" 或串流的 "chat.completion.chunk"。 |
created |
整數 | 聊天完成的時間以秒為單位。 |
model |
字串 | 用來 generate 回應的模型版本。 |
usage |
使用量 | 令牌使用方式元數據。 串流回應中可能不存在。 |
ChatCompletionChoice
| 领域 | 類型 | 描述 |
|---|---|---|
index |
整數 | 生成選項 list 中所選擇的索引。 |
message |
ChatMessage | 模型傳回的聊天完成訊息。 角色將會 assistant。 |
finish_reason |
字串 | 模型停止產生令牌的原因。 |
ChatCompletionChunk
| 领域 | 類型 | 描述 |
|---|---|---|
index |
整數 | 生成選項 list 中所選擇的索引。 |
delta |
ChatMessage | 來自模型所產生串流回應的聊天完成訊息部分。 只有第一個區塊的保證包含 role。 |
finish_reason |
字串 | 模型停止產生令牌的原因。 只有最後一個區塊會被填滿。 |
完成任務
文字完成任務是用來生成對單一提示的回應。 不同於聊天，此工作支援批次輸入：可以在一個要求中傳送多個獨立提示。 如需查詢端點 ，請參閱 parameters。
完成請求
| 领域 | 預設 | 類型 | 描述 |
|---|---|---|---|
prompt |
字串或 List[字串] | 必要。 模型的提示。 | |
max_tokens |
null |
null，這表示沒有 limit，或大於零的整數 |
用於 generate的令牌數目上限。 |
stream |
true |
布爾 | 將回應以串流方式發送回用戶端，從而允許返回部分結果。 如果要求中包含此參數，則會使用 伺服器傳送的事件 標準來傳送回應。 |
temperature |
1.0 |
浮點數在 [0,2] 之間 | 取樣溫度。 0 具決定性且較高 values 引進更多隨機性。 |
top_p |
1.0 |
浮點數在 (0,1] 之間 | 用於核取樣的機率臨界值。 |
top_k |
null |
null，這表示沒有 limit，或大於零的整數 |
定義最可能用於 top-k-filtering 的 k 標記數目。 Set 此值設定為 1，讓輸出具決定性。 |
error_behavior |
"error" |
"truncate" 或 "error" |
針對逾時或上下文長度超出的錯誤。 其中之一："truncate"（盡可能多地傳回令牌）或 "error"（傳回錯誤）。 此參數僅被每次支付以令牌計價的端點所接受。 |
n |
1 | 大於零的整數 | API 在指定 n 時會返回 n 個獨立的聊天完成結果。 建議用於在相同輸入上 generate 多個完成的工作負載，以節省額外的推斷效率和節省成本。 僅適用於已配置的吞吐量端點。 |
stop |
[] | 字串或 List[字串] | 當遇到 stop 中的任何序列時，模型會停止產生進一步的令牌。 |
suffix |
"" |
字串 | 附加至每個完成結尾的字串。 |
echo |
false |
布爾 | 傳回提示詞與完成的結果。 |
use_raw_prompt |
false |
布爾 | 如果 true，請將 prompt 直接傳遞至模型，而不需要任何轉換。 |
完成回應
| 领域 | 類型 | 描述 |
|---|---|---|
id |
字串 | 文字完成的獨特 identifier。 |
choices |
完成選擇 |
list 的文字完成。 針對傳入的每個提示，如果指定 n，就會產生 n 選項。 默認 n 為 1。 |
object |
字串 | 物件類型。 等於 "text_completion" |
created |
整數 | 生成完成時間以秒為單位。 |
usage |
使用量 | 令牌使用方式元數據。 |
CompletionChoice
| 领域 | 類型 | 描述 |
|---|---|---|
index |
整數 | 要求中的提示索引號。 |
text |
字串 | 生成的結果 |
finish_reason |
字串 | 模型停止產生令牌的原因。 |
內嵌工作
內嵌工作會將輸入字串對應至內嵌向量。 每個請求中可以將許多輸入一起進行批次處理。 如需查詢端點 ，請參閱 parameters。
內嵌要求
| 领域 | 類型 | 描述 |
|---|---|---|
input |
字串或 List[字串] | 必要。 需要嵌入的輸入文字。 可以是字串或 list 格式的字串。 |
instruction |
字串 | 傳遞至嵌入模型的可選指令。 |
說明是選擇性的，且非常依賴具體的模型。 例如，BGE 作者建議在編製區塊索引時不要使用任何指令，並建議在檢索查詢時使用指令 "Represent this sentence for searching relevant passages:"。 其他模型，例如 Instructor-XL 支持各種不同的指令字串。
內嵌回應
| 领域 | 類型 | 描述 |
|---|---|---|
id |
字串 | 嵌入的唯一編號 identifier。 |
object |
字串 | 物件類型。 等於 "list"。 |
model |
字串 | 用於生成嵌入的嵌入模型名稱。 |
data |
EmbeddingObject | 內嵌物件。 |
usage |
使用量 | 令牌使用方式元數據。 |
EmbeddingObject
| 领域 | 類型 | 描述 |
|---|---|---|
object |
字串 | 物件類型。 等於 "embedding"。 |
index |
整數 | 在模型生成的嵌入物中，特定於list的嵌入索引。 |
embedding |
List[浮點數] | 內嵌向量。 每個模型都會傳回固定大小向量（BGE-Large為 1024） |