モデルサービングエンドポイントでの AI Gateway の構成
この記事では、モデルサービングエンドポイントで Mosaic AI Gateway を設定する方法について説明します。
必要条件
- モデルサービングがサポートされているリージョン内の Databricks ワークスペース。 モデルサービング 地域別の在庫状況をご覧ください。
- A モデルサービング エンドポイント. ワークスペースで 事前設定されたトークン単位の従量課金エンドポイント のいずれかを使用するか、次の操作を実行できます。
- 外部モデルのエンドポイントを作成するには、 外部モデルサービングエンドポイントの作成のステップ 1 と 2 を実行します。
- プロビジョニング スループットのエンドポイントを作成するには、プロビジョニング スループット 基盤モデル APIを参照してください。
- カスタムモデルのエンドポイントを作成するには、「 エンドポイントの作成」を参照してください。
UI を使用した AI Gateway の構成
エンドポイント作成ページの AI Gateway セクションでは、AI Gateway の機能を個別に構成できます。 外部モデルサービングエンドポイントとプロビジョン済みスループットエンドポイントで利用可能なサポート機能をご覧ください。
次の表は、エンドポイントの作成時に Serving UI を使用して AI Gateway を構成する方法をまとめたものです。これをプログラムで行う場合は、 ノートブックの例を参照してください。
機能 | 有効にする方法 | 詳細 |
|---|---|---|
使用状況の追跡 | 使用状況の追跡を有効にする を選択して、データ使用量メトリクスの追跡と監視を有効にします。 |
|
ペイロードのロギング | [ 推論テーブルを有効にする ] を選択すると、エンドポイントからの要求と応答が Unity Catalog によって管理される Delta テーブルに自動的に記録されます。 |
|
UI での AI ガードレールの設定を参照してください。 |
| |
レート制限 | [レート制限] を選択して、エンドポイントがサポートできる毎分のクエリ数 (QPM) または毎分トークン数 (TPM) を管理および指定します。
|
|
トラフィック分割 | サーブされるエンティティ セクションで、特定のモデルにルーティングする トラフィックの割合 を指定します。 エンドポイントのトラフィック分割をプログラムで設定するには、エンドポイントに複数の外部モデルを提供するを参照してください。 |
|
フォールバック | [AI Gateway] セクションで [ フォールバックの有効化 ] を選択して、エンドポイント上の他の提供モデルにフォールバックとしてリクエストを送信します。 |
|
次の図は、フォールバックの例を示しています。
- 3 つのサーブされたエンティティは、モデル サービング エンドポイントで提供されます。
- 要求は最初に サーブされるエンティティ 3 にルーティングされます。
- リクエストが 200 レスポンスを返した場合、リクエストは サーブされるエンティティ 3 で成功し、リクエストとそのレスポンスはエンドポイントの使用状況追跡テーブルとペイロードロギングテーブルに記録されます。
- 要求が サーブされる エンティティ 3 で 429 または 5xx エラーを返した場合、要求はエンドポイントで次に提供されるエンティティである サーブされる エンティティ 1 にフォールバックします。
- リクエストが サーブされる エンティティ 1 で 429 または 5xx エラーを返した場合、リクエストはエンドポイントで次に提供されたエンティティである サーブされる エンティティ 2 にフォールバックします。
- 要求が サーブされる エンティティ 2 で 429 または 5xx エラーを返した場合、これがフォールバック エンティティの最大数であるため、要求は失敗します。失敗したリクエストとレスポンスエラーは、使用状況追跡テーブルとペイロードロギングテーブルに記録されます。
UI での AI ガードレールの構成
プレビュー
この機能は パブリック プレビュー段階です。
次の表は、 サポートされているガードレールを構成する方法を示しています。
2025 年 5 月 30 日以降、トピック モデレーションとキーワード フィルタリング AI ガードレールはサポートされなくなりました。これらの機能がワークフローに必要な場合は、Databricks アカウント チームに連絡して、カスタム ガードレールのプライベート プレビューに参加してください。
ガードレール | 有効にする方法 |
|---|---|
安全性 | [ 安全性 ] を選択すると、モデルが安全でない有害なコンテンツと相互作用するのを防ぐための保護機能が有効になります。 |
個人を特定できる情報 (PII) の検出 | 名前、住所、クレジット カード番号などの PII データがエンドポイントの要求と応答で検出された場合に、 それらをブロック または マスク することを選択します。 それ以外の場合は、[ なし ] を選択して PII 検出が発生しないようにします。 |
使用状況追跡テーブルのスキーマ
次のセクションでは、 system.serving.served_entities および system.serving.endpoint_usage システムテーブルの使用状況追跡テーブル スキーマをまとめます。
system.serving.served_entities 使用状況追跡テーブル スキーマ
system.serving.served_entities usage tracking システムテーブルは、現在、トークン単位の従量課金エンドポイントではサポートされていません。
system.serving.served_entities使用状況追跡システムテーブルには、次のスキーマがあります。
列名 | 説明 | タイプ |
|---|---|---|
| 提供されたエンティティの一意の ID。 | 文字列 |
| Delta Sharingの顧客 アカウント ID。 | 文字列 |
| サービスエンドポイントの顧客ワークスペース ID。 | 文字列 |
| 作成者の ID。 | 文字列 |
| サービングエンドポイントの名前。 | 文字列 |
| サービングエンドポイントの一意の ID。 | 文字列 |
| 提供されるエンティティの名前。 | 文字列 |
| 提供されるエンティティのタイプ。 | 文字列 |
| エンティティの基になる名前。 ユーザーが指定した名前である | 文字列 |
| 提供されたエンティティのバージョン。 | 文字列 |
| エンドポイント設定のバージョン。 | INT |
| タスクの種類。 | 文字列 |
| 外部モデルの構成。 例えば | 構造体 |
| 基盤モデルの構成。 例えば | 構造体 |
| カスタムモデルの設定。 例えば | 構造体 |
| 機能仕様の構成。 例えば | 構造体 |
| 提供されたエンティティの変更のタイムスタンプ。 | TIMESTAMP |
| エンティティ削除のタイムスタンプ。 エンドポイントは、提供されるエンティティのコンテナです。 エンドポイントが削除されると、提供されたエンティティも削除されます。 | TIMESTAMP |
system.serving.endpoint_usage 使用状況追跡テーブル スキーマ
system.serving.endpoint_usage使用状況追跡システムテーブルには、次のスキーマがあります。
列名 | 説明 | タイプ |
|---|---|---|
| 顧客アカウント ID。 | 文字列 |
| サービスエンドポイントの顧客ワークスペース ID。 | 文字列 |
| モデルサービング要求本文で指定できるユーザー指定の要求識別子。 カスタムモデルエンドポイントの場合、これは 4MiB を超えるリクエストではサポートされていません。 | 文字列 |
| すべてのモデルサービング要求にアタッチされた Databricks 生成要求識別子。 | 文字列 |
| サービスエンドポイントの呼び出しリクエストにアクセス許可が使用されるユーザーまたはサービスプリンシパルの ID。 | 文字列 |
| モデルから返された HTTP 状態コード。 | Integer |
| 要求が受信されたタイムスタンプ。 | TIMESTAMP |
| 入力のトークン数。カスタム モデル要求の場合は 0 になります。 | ロング |
| 出力のトークン数。カスタム モデル要求の場合は 0 になります。 | ロング |
| 入力文字列またはプロンプトの文字数。カスタム モデル要求の場合は 0 になります。 | ロング |
| 応答の出力文字列の文字数。カスタム モデル要求の場合は 0 になります。 | ロング |
| ユーザーは、エンドポイントへの呼び出しを行うエンド ユーザーまたは顧客アプリケーションの識別子を含むマップを提供しました。 | マップ |
| 要求がストリーム・モードであるかどうか。 | ブール値 |
| エンドポイントと提供されるエンティティに関する情報を検索するために | 文字列 |
使用法をさらに定義する usage_context
使用状況の追跡が有効になっている外部モデルに対してクエリを実行する場合は、 usage_context パラメーターに Map[String, String]型を指定できます。 使用状況コンテキスト マッピングは、使用状況追跡テーブルの usage_context 列に表示されます。 usage_contextマップサイズは 10 KiB を超えることはできません。
{
"messages": [
{
"role": "user",
"content": "What is Databricks?"
}
],
"max_tokens": 128,
"usage_context":
{
"use_case": "external",
"project": "project1",
"priority": "high",
"end_user_to_charge": "abcde12345",
"a_b_test_group": "group_a"
}
}
OpenAI Python クライアントを使用している場合は、extra_body パラメーターに usage_context を含めることで指定できます。
from openai import OpenAI
client = OpenAI(
api_key="dapi-your-databricks-token",
base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)
response = client.chat.completions.create(
model="databricks-claude-3-7-sonnet",
messages=[{"role": "user", "content": "What is Databricks?"}],
temperature=0,
extra_body={"usage_context": {"project": "project1"}},
)
answer = response.choices[0].message.content
print("Answer:", answer)
アカウント 管理者は、使用状況のコンテキストに基づいて異なる行を集計して知見を得ることができ、この情報をペイロードログテーブルの情報と結合することができます。 たとえば、エンドユーザーのコスト属性を追跡するための end_user_to_charge を usage_context に追加できます。
エンドポイントの使用状況を監視する
エンドポイントの使用状況をモニタリングするために、エンドポイントのシステムテーブルと推論テーブルを結合できます。
Join システムテーブル
この例は、外部モデルとプロビジョニングされたスループットエンドポイントにのみ適用されます。served_entities システムテーブルは、トークン単位の従量課金エンドポイントではサポートされていませんが、Join 推論テーブルと使用量テーブルを使用して同様の詳細を取得できます。
endpoint_usage システムテーブルと served_entities システムテーブルを結合するには、次の SQL を使用します。
SELECT * FROM system.serving.endpoint_usage as eu
JOIN system.serving.served_entities as se
ON eu.served_entity_id = se.served_entity_id
WHERE created_by = "\<user_email\>";
ジョイン推論テーブルと使用テーブル
次の例では、 endpoint_usage システムテーブルとトークン単位の従量課金エンドポイントの推論テーブルを結合します。 推論テーブルと使用状況の追跡は、これらのテーブルを結合するためにエンドポイントで有効にする必要があります。
SELECT * FROM system.serving.endpoint_usage AS endpoint_usage
JOIN
(SELECT DISTINCT(served_entity_id) AS fmapi_served_entity_id
FROM <inference table name>) fmapi_id
ON fmapi_id.fmapi_served_entity_id = endpoint_usage.served_entity_id;
エンドポイントの AI Gateway 機能を更新する
AI Gateway の機能は、以前に有効になっていたモデルサービングエンドポイントと有効にしていなかったエンドポイントで更新できます。AI Gateway 構成の更新が適用されるまでに約 20 秒から 40 秒かかりますが、レート制限の更新には最大 60 秒かかる場合があります。
以下は、Serving UIを使用してモデルサービングエンドポイントの AI Gateway機能を更新する方法を示しています。
エンドポイント ページの ゲートウェイ セクションでは、有効になっている機能を確認できます。 これらの機能を更新するには、 AI Gateway の編集 をクリックします。
ノートブックの例
次のノートブックは、Databricks Mosaic AI Gateway 機能をプログラムで有効にして使用し、プロバイダーからのモデルを管理および制御する方法を示しています。PUT /api/2.0/serving-endpoints/{name}/AI-gateway を参照してください。 REST API の詳細については、こちらをご覧ください。