Foundation Model REST API リファレンス

この記事では、Databricks Foundation Model API に関する一般的な API の情報と、それらでサポートされているモデルについて説明します。 Foundation Model API は、既存のプロジェクトを移行しやすくするために、OpenAI の REST API に似た設計になっています。 トークン単位の支払いエンドポイントとプロビジョニングされたスループット エンドポイントはどちらも、同じ形式の REST API 要求を受け入れます。

エンドポイント

トークン単位の支払いモデルごとに 1 つのエンドポイントがあり、ユーザーは HTTP POST 要求を使ってこれらのエンドポイントと対話できます。 プロビジョニングされたスループット エンドポイントは、API または Serving UI を使って作成できます。 これらのエンドポイントでは、A/B テスト用のエンドポイントごとに複数のモデルもサポートされます。ただし、提供される両方のモデルが同じ API 形式を公開している場合 (たとえば、両方のモデルがチャット モデルの場合) に限られます。

要求と応答では JSON が使用され、正確な JSON 構造体はエンドポイントのタスクの種類によって異なります。 チャットと入力候補エンドポイントでは、ストリーミング応答がサポートされます。

トークン単位の支払いワークロードでは、特定のモデルがサポートされています。それらのモデルと受け入れられる API 形式については、「トークン単位の支払いでサポートされているモデル」をご覧ください。

使用方法

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

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

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

チャット タスク

チャット タスクは、モデルを使用したマルチターン会話用に最適化されています。 各要求によってこれまでの会話が記述されます。ここで、messages フィールドは、user と assistant のロールの間で交互に切り替わる必要があり、最後に user メッセージが表示されます。 モデル応答により、会話内の次の assistant メッセージが提供されます。

チャット要求

フィールド	既定値	Type	説明
messages		ChatMessage リスト	必須。 現在の会話を表すメッセージの一覧。
max_tokens	nil	0 より大きい整数または無限大を表す nil	生成するトークンの最大数。
stream	true	Boolean	要求に対する部分的な結果を許可するため、応答をクライアントにストリーミングして戻します。 このパラメーターが要求に含まれている場合、応答はサーバー送信イベント標準を使って送信されます。
temperature	1.0	Float in [0,2]	サンプリング温度。 0 は決定論的であり、値が大きいほどランダム性が高くなります。
top_p	1.0	Float in (0,1]	核サンプリングに使われる確率しきい値。
top_k	nil	0 より大きい整数または無限大を表す nil	上位 k フィルター処理に使用する、可能性が最も高い k 個のトークンの数を定義します。 出力を決定論的にするには、この値を 1 に設定します。
stop	[]	String または List[String]	stop 内のシーケンスのいずれかが検出されると、モデルはそれ以上のトークン生成を停止します。
n	1	0 より大きい整数	この API は、n が指定された場合に、n 個の独立したチャット入力候補を返します。 推論の効率を高め、コストを削減するために、同じ入力で複数の入力候補を生成するワークロードにお勧めします。 プロビジョニングされたスループット エンドポイントでのみ使用できます。
tool_choice	nil	文字列または ToolChoiceObject	必ず tools フィールドと共に使用します。 tool_choice では、auto、required、none など、さまざまなキーワード文字列がサポートされます。 auto は、使用に適切なツール (ある場合) をモデルに決定させることを意味します。 auto では、tools のツールがどれも適切でないとモデルが判断した場合、モデルでは、ツール呼び出しの代わりに標準アシスタント メッセージを生成します。 required は、モデルが tools 内で最も適切なツールを選択し、ツール呼び出しを生成する必要があることを意味します。 none は、モデルがツール呼び出しを生成せず、代わりに標準のアシスタント メッセージを生成する必要があることを意味します。 tools で定義されている特定のツールを使用してツール呼び出しを強制するには、ToolChoiceObject を使用します。 既定では、tools フィールドに tool_choice = "auto" が設定されます。 それ以外の場合、tools フィールドは既定で tool_choice = "none" に設定されます
tools	nil	ToolObject	モデルで呼び出すことができる tools の一覧。 現在、function はサポートされている唯一の tool 型であり、最大 32 個の関数がサポートされています。

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 ロールは、会話の最初のメッセージとして 1 回だけ使用できます。 これによりモデルの既定のシステム プロンプトがオーバーライドされます。

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 個のキーに制限されています。

チャットの応答

ストリーミング以外の要求の場合、応答は 1 つのチャット入力候補オブジェクトです。 ストリーミング要求の場合、応答は 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

フィールド	タイプ	Description
index	整数	生成された選択肢の一覧内の選択肢のインデックス。
message	ChatMessage	モデルによって返されるチャット入力候補メッセージ。 ロールは assistant になります。
finish_reason	String	モデルがトークンの生成を停止した理由。

ChatCompletionChunk

フィールド	タイプ	Description
index	整数	生成された選択肢の一覧内の選択肢のインデックス。
delta	ChatMessage	モデルから生成されたストリーミングされる応答のチャット入力候補メッセージの部分。 最初のチャンクのみ、role が設定されていることが保証されます。
finish_reason	String	モデルがトークンの生成を停止した理由。 最後のチャンクにのみ、これが設定されます。

入力候補タスク

テキスト入力候補タスクは、1 つのプロンプトに対する応答を生成することを目的としています。 チャットとは異なり、このタスクはバッチ入力をサポートしており、複数の独立したプロンプトを 1 つの要求で送信できます。

入力候補要求

フィールド	既定値	Type	説明
prompt		String または List[String]	必須。 モデルのプロンプト。
max_tokens	nil	0 より大きい整数または無限大を表す nil	生成するトークンの最大数。
stream	true	Boolean	要求に対する部分的な結果を許可するため、応答をクライアントにストリーミングして戻します。 このパラメーターが要求に含まれている場合、応答はサーバー送信イベント標準を使って送信されます。
temperature	1.0	Float in [0,2]	サンプリング温度。 0 は決定論的であり、値が大きいほどランダム性が高くなります。
top_p	1.0	Float in (0,1]	核サンプリングに使われる確率しきい値。
top_k	nil	0 より大きい整数または無限大を表す nil	上位 k フィルター処理に使用する、可能性が最も高い k 個のトークンの数を定義します。 出力を決定論的にするには、この値を 1 に設定します。
error_behavior	"error"	"truncate" または "error"	タイムアウトとコンテキスト長超過エラーの場合。 "truncate" (できるだけ多くのトークンを返す) または "error" (エラーを返す) のいずれか。 このパラメーターを受け入れるのは、トークン単位の支払いエンドポイントのみです。
n	1	0 より大きい整数	この API は、n が指定された場合に、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

フィールド	タイプ	Description
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) が返されます

その他のリソース

• Databricks Foundation Model API
• 基盤モデルと外部モデルのクエリを実行する
• トークン単位の支払いでサポートされているモデル