Foundation Model REST API リファレンス
[アーティクル] 06/19/2024
2 人の共同作成者
フィードバック
この記事の内容
この記事では、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 回だけ使用できます。 これによりモデルの既定のシステム プロンプトがオーバーライドされます。
モデルによるツール呼び出しアクションの提案。 「Azure Databricks での関数呼び出し 」を参照してください。
フィールド
タイプ
説明
id
String
必須 。 このツール呼び出し候補の一意識別子。
type
String
必須 。 サポートされるのは "function"
のみです。
function
FunctionCallCompletion
必須 。 モデルによって提案された関数呼び出し。
FunctionCallCompletion
フィールド
タイプ
説明
name
String
必須。 モデルが推奨した関数の名前。
arguments
Object
必須。 シリアル化された JSON ディクショナリとしての関数の引数。
「Azure Databricks での関数呼び出し 」を参照してください。
フィールド
タイプ
説明
type
String
必須 。 ツールの型。 現在、"function"
のみがサポートされています。
function
Object
必須 。 {"type": "function", "function": {"name": "my_function"}}
の形式での、どのツールを呼び出すかを定義するオブジェクト。"my_function
は tools
フィールドの FunctionObject の名前です。
「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) が返されます
その他のリソース