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 null null は、制限なし、または 0 より大きい整数を意味します。 生成するトークンの最大数。
stream true Boolean 要求に対する部分的な結果を許可するため、応答をクライアントにストリーミングして戻します。 このパラメーターが要求に含まれている場合、応答はサーバー送信イベント標準を使って送信されます。
temperature 1.0 Float in [0,2] サンプリング温度。 0 は決定論的であり、値が大きいほどランダム性が高くなります。
top_p 1.0 Float in (0,1] 核サンプリングに使われる確率しきい値。
top_k null null は、制限なし、または 0 より大きい整数を意味します。 上位 k フィルター処理に使用する、可能性が最も高い k 個のトークンの数を定義します。 出力を決定論的にするには、この値を 1 に設定します。
stop [] String または List[String] stop 内のシーケンスのいずれかが検出されると、モデルはそれ以上のトークン生成を停止します。
n 1 0 より大きい整数 この API は、n が指定された場合に、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 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 Boolean このパラメーターは、サンプリングされるトークンのログ確率を指定するかどうかを示します。
top_logprobs null Integer このパラメーターは、サンプリング ステップごとにログ確率を返す可能性が最も高いトークン候補の数を制御します。 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 ロールは、会話の最初のメッセージとして 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 個のキーに制限されています。
strict Boolean 関数呼び出しの生成時に厳格なスキーマの準拠を有効にするかどうか。 trueに設定すると、モデルはスキーマ フィールドで定義されている正確なスキーマに従います。 厳密な場合は、JSON スキーマのサブセットのみがサポートされます true

ResponseFormatObject

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

フィールド タイプ 説明
type String 必須。 定義されている応答形式の型。 非構造化テキストの text 、非構造化 JSON オブジェクトの json_object 、または特定のスキーマに準拠する JSON オブジェクトの json_schema 。
json_schema JsonSchemaObject 必須。 typeが に設定されている場合に準拠する JSON スキーマjson_schema

JsonSchemaObject

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

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

チャットの応答

ストリーミング以外の要求の場合、応答は 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 null null は、制限なし、または 0 より大きい整数を意味します。 生成するトークンの最大数。
stream true Boolean 要求に対する部分的な結果を許可するため、応答をクライアントにストリーミングして戻します。 このパラメーターが要求に含まれている場合、応答はサーバー送信イベント標準を使って送信されます。
temperature 1.0 Float in [0,2] サンプリング温度。 0 は決定論的であり、値が大きいほどランダム性が高くなります。
top_p 1.0 Float in (0,1] 核サンプリングに使われる確率しきい値。
top_k null null は、制限なし、または 0 より大きい整数を意味します。 上位 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) が返されます

その他のリソース