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

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

エンドポイント

API は、トークン単位の従量課金エンドポイントとプロビジョニング スループット エンドポイントをサポートします。

事前構成されたエンドポイントは、トークン単位の従量課金サポートモデルごとにワークスペースで使用でき、ユーザーは HTTP POST 要求を使用してこれらのエンドポイントと対話できます。 サポートされているモデルについては、Mosaic AI Model Servingでサポートされている基盤モデルを参照してください。

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

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

使い方

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

フィールド	タイプ	説明
completion_tokens	整数タイプ	生成されたトークンの数。 埋め込み応答には含まれません。
prompt_tokens	整数タイプ	入力プロンプトからのトークンの数。
total_tokens	整数タイプ	トークンの合計数。
reasoning_tokens	整数タイプ	思考トークンの数。推論モデルにのみ適用できます。

databricks-meta-llama-3-3-70b-instruct のようなモデルの場合、ユーザー プロンプトは、モデルに渡される前にプロンプト テンプレートを使用して変換されます。トークン単位の従量課金エンドポイントの場合、システム・プロンプトも追加される場合があります。 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]のFloat	主要部サンプリングに使用される確率のしきい値。
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	整数タイプ	このパラメーターは、各サンプリング ステップで対数確率を返す可能性が最も高いトークン候補の数を制御します。 0 から 20 まで指定できます。 このフィールドを使用する場合は、logprobs``trueする必要があります。
reasoning_effort	"medium"	文字列	応答を生成するときにモデルが適用する推論作業のレベルを制御します。受け入れられる値は、 "low"、 "medium"、または "high"です。推論の努力が高まると、より思慮深く正確な応答が得られる可能性がありますが、レイテンシーとトークンの使用量が増加する可能性があります。このパラメーターは、 databricks-gpt-oss-120b や databricks-gpt-oss-20bなど、限られたモデル セットでのみ受け入れられます。

ChatMessage

フィールド	タイプ	説明
role	文字列	必須です 。 メッセージの作成者の役割。 "system"、"user"、"assistant"、または"tool"にすることができます。
content	文字列またはリスト [ContentItem]	ツール呼び出しを伴わないチャットタスクに 必要です 。コンテンツは、文字列または単一のチャットインタラクション内の一連のマルチモーダル要素を含む配列のいずれかです。これらの要素は、モデルによって入力または出力として処理される順序に従います。この配列入力は、外部モデルプロバイダーを通じてのみアクセス可能な独自のモデルで使用するために特別に設計されています。現在、Claude モデルのみがサポートされています。他の外部モデルプロバイダー、オープンソースモデル(Llama)、または Databricksで顧客によってホストされているモデルには、文字列型のコンテンツを使用します。 list[ContentItem] はOpenAIの仕様と互換性がありません。
tool_calls	ToolCall リスト	モデルによって生成された tool_calls の一覧。 "assistant"としてroleし、contentフィールドの指定がない必要があります。
tool_call_id	文字列	role が "tool"の場合、メッセージが応答しているToolCallに関連付けられた ID。他の role オプションの場合は空にする必要があります。

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

ContentItem

ContentItem は、 TextContent、 ReasoningContent、 DocumentContent、または ImageContent

TextContent

フィールド	タイプ	説明
type	文字列	必須です 。テキストである必要があります。
text	文字列	必須 のテキスト コンテンツ。
citations	List[Citation]	オプションの引用情報。次の表を参照してください。
cache_control	文字列	リクエストのキャッシュを有効にします。この懸念は、 Databricksでホストされる Claude モデルでのみ受け入れられます

引用フィールドは次のとおりです。

フィールド	タイプ	説明
type	文字列	必須です 。char_locationする必要があります。
cited_text	文字列	ドキュメントから引用されたテキスト。
document_index	整数タイプ	引用されたドキュメントのインデックス。
document_title	文字列	引用されたドキュメントのタイトル。
start_char_index	整数タイプ	ドキュメント内の引用テキストの開始インデックス。
end_char_index	整数タイプ	ドキュメント内の引用テキストの終了インデックス。

ImageContent

フィールド	タイプ	説明
type	文字列	必須です 。image_urlである必要があります。
image_url	ImageURL	OpenAI image_url オブジェクトに相当します。
cache_control	文字列	リクエストのキャッシュを有効にします。このパラメーターは、Databricks がホストする Claude モデルでのみ受け入れられます。画像メッセージ コンテンツは、エンコードされたデータをソースとして使用する必要があります。URLは現在サポートされていません。

ImageURL フィールドは次のとおりです。

フィールド	タイプ	説明
url	文字列	Base64 でエンコードされた画像データ。サポートされている画像ファイル形式 (JPEG、PNG、GIF、WebP など) から生成された有効な base64 文字列である必要があります。
detail	文字列	画像の詳細レベルを指定します。

ReasoningContent

フィールド	タイプ	説明
type	文字列	必須です 。reasoningである必要があります。
summary	List[Summary]	推論テキストの内容。サマリーは、 TextSummary または EncryptedTextSummary
cache_control	文字列	リクエストのキャッシュを有効にします。このパラメーターは、 Databricks がホストする Claude モデルでのみ受け入れられます。

TextSummary

フィールド	タイプ	説明
type	文字列	必須です 。summary_textである必要があります。
text	文字列	応答を生成するときにモデルによって使用される推論の簡単な要約。
signature	文字列	データの信頼性を検証するためのオプションの暗号化トークン。

EncryptedTextSummary

フィールド	タイプ	説明
type	文字列	必須です 。summary_encrypted_textである必要があります。
data	文字列	安全上の理由から人間が読めない暗号化されたテキストコンテンツ。

DocumentContent

DocumentContent はリクエスト専用です。

フィールド	タイプ	説明
type	文字列	必須です 。documentする必要があります。
title	文字列	ドキュメントのタイトル。
context	文字列	ドキュメントの説明。
source	ソース	必須です 。形式や内容など、ドキュメントに関する詳細情報を指定します。
citations	Map[string, bool]	ドキュメントの引用を有効にするかどうかを示すブールにマップする単一のフィールドが "enabled" のマップ。

Source

フィールド	タイプ	説明
type	文字列	必須です 。base64 (PDF)、text、contentまたは url (URLPDFSource) のいずれかである必要があります。
media_type	文字列	PDFおよびテキストタイプに 必要です 。 - PDFの場合は application または pdf である必要があります。 - テキストは text または plain である必要があります。
data	文字列	PDFとテキストに 必要です 。ドキュメントソースを含むデータ。
content	文字列 or List[TextContent] または List[ImageContent]	contentタイプに 必要です 。ドキュメントの内容。
url	文字列	URLPDFSource タイプに 必要です 。PDF ドキュメントの URL。

FileContent

フィールド	タイプ	説明
type	文字列	必須 です。ファイルである必要があります。
file	ファイル	必須 ファイルの内容。

ファイルフィールドは以下のとおりです。

フィールド	タイプ	説明
filename	文字列	ファイルの名前。
file_data	文字列	必須 OpenAI互換のbase64でエンコードされたファイルデータ。これは、base64でエンコードされたデータが続くファイル形式から始まります。たとえば、PDF ファイルの形式は data:application/pdf;base64,<base64 data>

ToolCall

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

フィールド	タイプ	説明
id	文字列	必須です 。 このツール・コールの提案の一意の識別子。
type	文字列	必須です 。 "function"のみがサポートされています。
function	FunctionCallCompletion	必須です 。 モデルによって提案された関数呼び出し。
cache_control	文字列	リクエストのキャッシュを有効にします。この懸念は、 Databricksでホストされる Claude モデルでのみ受け入れられます

FunctionCallCompletion

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

ToolChoiceObject

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

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

ToolObject

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

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

FunctionObject

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

ResponseFormatObject

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

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

JsonSchemaObject

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

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

チャット応答

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

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

ChatCompletionChoice

フィールド	タイプ	説明
index	整数タイプ	生成された選択肢のリスト内の選択肢のインデックス。
message	ChatMessage	モデルによって返されたチャット完了メッセージ。 役割は assistantになります。
finish_reason	文字列	モデルがトークンの生成を停止した理由。
extra_fields	文字列	外部モデル プロバイダーの独自のモデルを使用する場合、プロバイダーの APIの 応答に追加のメタデータが含まれる場合があります。 Databricks はこれらの応答をフィルター処理し、プロバイダーの元のフィールドのサブセットのみを返します。safetyRatingは、現時点でサポートされている唯一の追加フィールドであり、詳細についてはGeminiのドキュメントを参照してください。

ChatCompletionChunk

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

完了タスク

テキスト補完タスクは、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]のFloat	主要部サンプリングに使用される確率のしきい値。
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	""	文字列	すべての入力候補の末尾に追加される文字列。
echo	false	ブール値	プロンプトと完了を返します。
use_raw_prompt	false	ブール値	trueの場合、変換を行わずにpromptを直接モデルに渡します。

完了レスポンス

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

CompletionChoice

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

埋め込みタスク

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

埋め込みリクエスト

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

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

埋め込み応答

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

EmbeddingObject

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

追加のリソース

• Databricks 基盤モデルAPI

• 基盤モデルを使用する

• 基盤モデルAPIで利用できるDatabricksがホストする基盤モデル