基盤モデルの REST API リファレンス

この記事では、Databricks 基盤APIsとそれらがサポートするモデルの一般的な API 情報を提供します。 基盤モデルAPI既存のプロジェクトの移行を容易にするために、OpenAI の REST API と同様になるように設計されています。 トークン単位の従量課金のエンドポイントとプロビジョニングスループットのエンドポイントはどちらも、同じ REST API リクエスト形式を受け入れます。

エンドポイント

トークン単位の従量課金の各モデルには単一のエンドポイントがあり、ユーザーは HTTP POST リクエストを使用してこれらのエンドポイントと対話できます。 プロビジョニングされたスループット エンドポイントは、API または Serving UI を使用して作成できます。 これらのエンドポイントは、提供される両方のモデルが同じ API 形式を公開している限り、A/B テスト用のエンドポイントごとに複数のモデルもサポートします。 たとえば、どちらのモデルもチャット モデルです。POST /api/2.0/serving-endpoints をエンドポイント構成パラメーターのために参照することができます。

リクエストとレスポンスはJSONを使用し、正確なJSON構造はエンドポイントのタスクタイプによって異なります。 チャットと完了エンドポイントは、ストリーミング応答をサポートします。

トークン単位の従量課金のワークロードは特定のモデルをサポートしています。これらのモデルと受け入れられる API 形式については、トークン単位の従量課金がサポートされるモデルを参照してください。

使い方

応答には、要求と応答のトークンの数を報告する usage サブメッセージが含まれます。 このサブメッセージの形式は、すべてのタスクタイプで同じです。

フィールド	タイプ	説明
completion_tokens	Integer	生成されたトークンの数。 埋め込み応答には含まれません。
prompt_tokens	Integer	入力プロンプトからのトークンの数。
total_tokens	Integer	トークンの合計数。

llama-2-70b-chat のようなモデルの場合、ユーザー プロンプトは、モデルに渡される前にプロンプト テンプレートを使用して変換されます。トークン単位の従量課金エンドポイントの場合、システム・プロンプトも追加される場合があります。 prompt_tokens には、サーバーによって追加されたすべてのテキストが含まれます。

チャットタスク

チャット タスクは、モデルとの複数ターンの会話に最適化されています。 モデル応答は、会話の次の assistant メッセージを提供します。 エンドポイント パラメーターのクエリについては、 POST /serving-endpoints/{name}/invocations を参照してください。

チャットリクエスト

フィールド	デフォルト	タイプ	説明
messages		ChatMessage 一覧	必須です。 現在の会話を表すメッセージの一覧。
max_tokens	null	nullこれは、制限なし、またはゼロより大きい整数を意味します	生成するトークンの最大数。
stream	true	ブール値	要求の部分的な結果を許可するために、応答をクライアントにストリームします。 このパラメーターが要求に含まれている場合、応答は Server-sent events 標準を使用して送信されます。
temperature	1.0	[0,2]の浮動小数点数	サンプリングtemperature。0は決定性で、値が大きくなるほどランダム性が高くなります。
top_p	1.0	フロートイン (0,1)	主要部サンプリングに使用される確率のしきい値。
top_k	null	nullこれは、制限なし、またはゼロより大きい整数を意味します	top-kフィルタリングに使用する可能性が最も高いkトークンの数を定義します。出力を決定的にするには、この値を1に設定します。
stop	[]	文字列 または List[文字列]	モデルは、 stop 内のシーケンスのいずれかが検出されると、それ以上のトークンの生成を停止します。
n	1	0 より大きい整数	nが指定されている場合、APIはn個の独立したチャット完了を返します。推論の効率とコスト削減をさらに高めるために、同じ入力で複数の入力候補を生成するワークロードに推奨されます。 プロビジョニングされたスループットエンドポイントでのみ使用できます。
tool_choice	none	文字列または 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	ツールオブジェクト	モデルが呼び出すことができる tools の一覧。 現在、サポートされているtoolタイプは function のみで、最大 32 の関数がサポートされています。
response_format	null	ResponseFormatオブジェクト	モデルが出力する必要がある形式を指定するオブジェクト。 使用できるタイプは、 text、 json_schema 、または json_object { "type": "json_schema", "json_schema": {...} } に設定すると、構造化された出力が有効になり、指定したJSONスキーマにモデルが従うようになります。 { "type": "json_object" }に設定すると、モデルが生成する応答は有効な JSON になりますが、応答が特定のスキーマに従うことは保証されません。
logprobs	false	ブール値	このパラメーターは、トークンがサンプリングされるログ確率を提供するかどうかを示します。
top_logprobs	null	Integer	このパラメーターは、各サンプリング ステップで対数確率を返す可能性が最も高いトークン候補の数を制御します。 0 から 20 まで指定できます。 このフィールドを使用する場合は、logprobstrueする必要があります。

ChatMessage

フィールド	タイプ	説明
role	String	必須です。 メッセージの作成者の役割。 "system"、"user"、"assistant"、または"tool"にすることができます。
content	String	メッセージの内容。 ツール呼び出しを伴わないチャットタスクに必要です。
tool_calls	ToolCall リスト	モデルによって生成された tool_calls の一覧。 "assistant"としてroleし、contentフィールドの指定がない必要があります。
tool_call_id	String	role が "tool"の場合、メッセージが応答しているToolCallに関連付けられた ID。他の role オプションの場合は空にする必要があります。

system ロールは、会話の最初のメッセージとして 1 回だけ使用できます。これは、モデルのデフォルト システム プロンプトをオーバーライドします。

ToolCall

モデルによるツールコールアクションの提案。 「Databricks での関数呼び出し」を参照してください。

フィールド	タイプ	説明
id	String	必須です。 このツール・コールの提案の一意の識別子。
type	String	必須です。 "function"のみがサポートされています。
function	FunctionCallCompletion(関数呼び出し完了)	必須です。 モデルによって提案された関数呼び出し。

FunctionCallCompletion

フィールド	タイプ	説明
name	String	必須。 モデルが推奨する関数の名前。
arguments	オブジェクト	必須。 シリアル化された JSON ディクショナリとしての関数の引数。

ToolChoiceObject

「Databricks での関数呼び出し」を参照してください。

フィールド	タイプ	説明
type	String	必須です。 ツールの種類。 現在、 "function" のみがサポートされています。
function	オブジェクト	必須です。 {"type": "function", "function": {"name": "my_function"}} の形式で呼び出すツールを定義するオブジェクト。ここで、"my_function は tools フィールドの FunctionObject の名前です。

ToolObject

「Databricks での関数呼び出し」を参照してください。

フィールド	タイプ	説明
type	String	必須です。 ツールの種類。 現在、 function のみがサポートされています。
function	関数オブジェクト	必須です。 ツールに関連付けられている関数定義。

FunctionObject

フィールド	タイプ	説明
name	String	必須です。 呼び出される関数の名前。
description	オブジェクト	必須です。 関数の詳細な説明。 モデルは、この説明を使用して、プロンプトに対する関数の関連性を理解し、より高い精度でツール呼び出しを生成します。
parameters	オブジェクト	関数が受け入れるパラメーター (有効な JSON スキーマ オブジェクトとして記述されます)。 ツールが呼び出された場合、ツール呼び出しは指定された JSON スキーマに適合します。 パラメーターを省略すると、パラメーターのない関数が定義されます。 propertiesの数は15キーに制限されています。
strict	ブール値	関数呼び出しの生成時に厳密なスキーマ準拠を有効にするかどうか。 trueに設定すると、モデルは schema フィールドで定義された正確なスキーマに従います。JSON スキーマのサブセットのみがサポートされます (strict が true

ResponseFormatObject

「Databricks の構造化出力」を参照してください。

フィールド	タイプ	説明
type	String	必須です。 定義するレスポンス・フォーマットのタイプ。 非構造化テキストの場合は text 、非構造化 JSON オブジェクトの場合は json_object 、特定のスキーマに準拠する JSON オブジェクトの場合は json_schema のいずれかです。
json_schema	JsonSchemaオブジェクト	必須です。 type が設定されている場合に遵守する JSON スキーマ json_schema

JsonSchemaObject

「Databricks の構造化出力」を参照してください。

フィールド	タイプ	説明
name	String	必須です。 応答形式の名前。
description	String	応答形式での応答方法を決定するためにモデルによって使用される、応答形式の目的の説明。
schema	オブジェクト	必須です。 レスポンス形式のスキーマ (JSON スキーマオブジェクトとして記述)。
strict	ブール値	出力の生成時に厳密なスキーマ準拠を有効にするかどうか。 trueに設定すると、モデルは schema フィールドで定義された正確なスキーマに従います。JSON スキーマのサブセットのみがサポートされます (strict が true

チャット応答

非ストリーミング要求の場合、応答は 1 つのチャット完了オブジェクトです。 ストリーミング要求の場合、応答は text/event-stream であり、各イベントは完了チャンク オブジェクトです。 完了オブジェクトとチャンク オブジェクトの最上位構造はほとんど同じで、 choices つだけ型が異なります。

フィールド	タイプ	説明
id	String	チャット完了の一意の識別子。
choices	List[ChatCompletionChoice] または List[ChatCompletionChunk] (ストリーミング)	チャット完了テキストのリスト。 n パラメーターが指定されている場合は、n選択肢が返されます。
object	String	オブジェクトの種類。 非ストリーミングの場合は "chat.completions" 、ストリーミングの場合は "chat.completion.chunk" のいずれかです。
created	Integer	チャットの完了が生成された時間 (秒単位)。
model	String	応答の生成に使用されたモデルのバージョン。
usage	使用量	トークン使用状況メタデータ。 ストリーミング応答には存在しない可能性があります。

ChatCompletionChoice

フィールド	タイプ	説明
index	Integer	生成された選択肢のリスト内の選択肢のインデックス。
message	チャットメッセージ	モデルによって返されたチャット完了メッセージ。 役割は assistantになります。
finish_reason	String	モデルがトークンの生成を停止した理由。

ChatCompletionChunk

フィールド	タイプ	説明
index	Integer	生成された選択肢のリスト内の選択肢のインデックス。
delta	チャットメッセージ	モデルから生成されたストリーム応答のチャット完了メッセージの一部。 最初のチャンクのみが role が入力されることが保証されます。
finish_reason	String	モデルがトークンの生成を停止した理由。 最後のチャンクにのみこれが入力されます。

完了タスク

テキスト補完タスクは、1 つのプロンプトに対する応答を生成するためのタスクです。 Chatとは異なり、このタスクはバッチ入力をサポートしており、1つのリクエストで複数の独立したプロンプトを送信できます。 エンドポイント パラメーターのクエリについては、 POST /serving-endpoints/{name}/invocations を参照してください。

完了リクエスト

フィールド	デフォルト	タイプ	説明
prompt		文字列 または List[文字列]	必須です。 モデルのプロンプト。
max_tokens	null	nullこれは、制限なし、またはゼロより大きい整数を意味します	生成するトークンの最大数。
stream	true	ブール値	要求の部分的な結果を許可するために、応答をクライアントにストリームします。 このパラメーターが要求に含まれている場合、応答は Server-sent events 標準を使用して送信されます。
temperature	1.0	[0,2]の浮動小数点数	サンプリングtemperature。0は決定性で、値が大きくなるほどランダム性が高くなります。
top_p	1.0	フロートイン (0,1)	主要部サンプリングに使用される確率のしきい値。
top_k	null	nullこれは、制限なし、またはゼロより大きい整数を意味します	top-kフィルタリングに使用する可能性が最も高いkトークンの数を定義します。出力を決定的にするには、この値を1に設定します。
error_behavior	"error"	"truncate" または "error"	タイムアウトおよびコンテキスト長超過エラーの場合。 "truncate" (できるだけ多くのトークンを返す) と "error" (エラーを返す) のいずれかです。このパラメーターは、トークン単位の従量課金エンドポイントでのみ受け入れられます。
n	1	0 より大きい整数	nが指定されている場合、APIはn個の独立したチャット完了を返します。推論の効率とコスト削減をさらに高めるために、同じ入力で複数の入力候補を生成するワークロードに推奨されます。 プロビジョニングされたスループットエンドポイントでのみ使用できます。
stop	[]	文字列 または List[文字列]	モデルは、 stop 内のシーケンスのいずれかが検出されると、それ以上のトークンの生成を停止します。
suffix	""	String	すべての入力候補の末尾に追加される文字列。
echo	false	ブール値	プロンプトと完了を返します。
use_raw_prompt	false	ブール値	trueの場合、変換を行わずにpromptを直接モデルに渡します。

完了レスポンス

フィールド	タイプ	説明
id	String	テキスト補完の一意の識別子。
choices	コンプリートチョイス	テキスト入力候補のリスト。 渡されたプロンプトごとに、nが指定されている場合はn選択肢が生成されます。デフォルトの n は 1 です。
object	String	オブジェクトの種類。 等しい "text_completion"
created	Integer	完了が生成された時間 (秒単位)。
usage	使用量	トークン使用状況メタデータ。

CompletionChoice

フィールド	タイプ	説明
index	Integer	要求のプロンプトのインデックス。
text	String	生成された入力候補。
finish_reason	String	モデルがトークンの生成を停止した理由。

埋め込みタスク

埋め込みタスクは、入力文字列を埋め込みベクトルにマップします。 各要求で多くの入力をまとめてバッチ処理できます。 エンドポイント パラメーターのクエリについては、 POST /serving-endpoints/{name}/invocations を参照してください。

埋め込みリクエスト

フィールド	タイプ	説明
input	文字列 または List[文字列]	必須です。 埋め込む入力テキスト。 文字列または文字列のリストを指定できます。
instruction	String	埋め込みモデルに渡す省略可能な命令。

手順はオプションであり、モデルに大きく依存します。 たとえば、BGEの著者は、チャンクのインデックス作成時に命令を使わず、検索クエリには命令 "Represent this sentence for searching relevant passages:" を使用することを推奨しています。 Instructor-XLなどの他のモデルは、幅広い命令文字列をサポートしています。

埋め込み応答

フィールド	タイプ	説明
id	String	埋め込みの一意の識別子。
object	String	オブジェクトの種類。 "list"と同じです。
model	String	埋め込みの作成に使用された埋め込みモデルの名前。
data	埋め込みオブジェクト	埋め込みオブジェクト。
usage	使用量	トークン使用状況メタデータ。

EmbeddingObject

フィールド	タイプ	説明
object	String	オブジェクトの種類。 "embedding"と同じです。
index	Integer	モデルによって生成された埋め込みの一覧にある埋め込みのインデックス。
embedding	一覧[フロート]	埋め込みベクトル。 各モデルは固定サイズのベクトル (BGE-Large の場合は 1024) を返します

関連リソース

• Databricks 基盤モデルAPI

• 基盤モデルのクエリー

• トークン単位の従量課金がサポートされるモデル