メインコンテンツまでスキップ

モデルサービングエンドポイントでの AI Gateway の構成

この記事では、モデルサービングエンドポイントで Mosaic AI Gateway を設定する方法について説明します。

必要条件​

UI を使用した AI Gateway の構成​

エンドポイント作成ページの AI Gateway セクションでは、AI Gateway の機能を個別に構成できます。 外部モデルサービングエンドポイントとプロビジョン済みスループットエンドポイントで利用可能なサポート機能をご覧ください。

AI Gateway の機能を構成する

次の表は、エンドポイントの作成時に Serving UI を使用して AI Gateway を構成する方法をまとめたものです。これをプログラムで行う場合は、 ノートブックの例を参照してください。

機能

有効にする方法

詳細

使用状況の追跡

使用状況の追跡を有効にする を選択して、データ使用量メトリクスの追跡と監視を有効にします。 この機能は、 トークン単位の従量課金 エンドポイントのデフォルトによって有効になります。

  • Unity Catalog が有効になっている必要があります。 - アカウント 管理者は、エンドポイントへの各リクエストのトークン数をキャプチャする SystemTable: system.serving.endpoint_usageと、各基盤モデルのメタデータを格納する system.serving.served_entitiesを使用する前に、Servingシステムテーブルスキーマを有効にする必要があります。 - 使用状況追跡テーブルのスキーマを参照してください。 - エンドポイントを管理するユーザーが使用状況の追跡を有効にする必要がある場合でも、 served_entities テーブルまたは endpoint_usage テーブルを表示またはクエリするアクセス許可を持っているのはアカウント管理者のみです。 システムテーブルへのアクセス権限の付与を参照してください。 - 入力トークン数と出力トークン数は、モデルによってトークン数が返されない場合、(text_length+1)/4 として推定されます。 - system.serving.served_entities システムテーブルは 、現在、 トークン単位の従量課金エンドポイントではサポートされていません。

ペイロードのロギング

[ 推論テーブルを有効にする ] を選択すると、エンドポイントからの要求と応答が Unity Catalog によって管理される Delta テーブルに自動的に記録されます。

  • Unity Catalog が有効になっていて、指定したカタログスキーマでアクセスCREATE_TABLE必要があります。 - AI Gateway によって有効化された推論テーブル は、カスタムモデルを提供するエンドポイントでのみサポートされている 従来の推論テーブル とは異なるスキーマを持ちます。AI Gateway 対応推論テーブル スキーマをご覧ください。 - ペイロードのログデータは、エンドポイントをクエリしてから 1 時間以内にこれらのテーブルに入力されます。 - 1 MB を超えるペイロードはログに記録されません。 - 応答ペイロードは、返されたすべてのチャンクの応答を集約します。 - ストリーミングがサポートされています。 ストリーミング シナリオでは、応答ペイロードは返されたチャンクの応答を集計します。

AIガードレール

UI での AI ガードレールの設定を参照してください。

  • ガードレールは、モデルの入力および出力で検出された安全でない有害なコンテンツとモデルが相互作用するのを防ぎます。 - 出力ガードレールは、埋め込みモデルやストリーミングではサポートされていません。

レート制限

レート制限 を選択して、エンドポイントのトラフィックをユーザーごとおよびエンドポイントごとに管理する要求 レート制限 を適用します。

  • レート制限は、1 分あたりのクエリ数 (QPM) で定義されます。 - デフォルトは、ユーザーごとエンドポイントごとに 制限なし です。

トラフィック分割

サーブされるエンティティ セクションで、特定のモデルにルーティングする トラフィックの割合 を指定します。 エンドポイントのトラフィック分割をプログラムで設定するには、エンドポイントに複数の外部モデルを提供するを参照してください。

  • すべてのトラフィックを特定のモデルにルーティングするには、100% に設定します。 - フォールバックのみのモデルを指定する場合は、そのモデルをエンドポイントに追加し、トラフィックの割合を 0% に設定します。 - モデル間でトラフィックを負荷分散し、フォールバックを設定するには、次の動作が想定されます。 - リクエストは、割り当てられたトラフィックの割合に基づいてエンティティ間でランダムに分割されます。 - 要求が最初のエンティティにヒットして失敗した場合、エンドポイントの作成時または最新のエンドポイント更新時に提供されたエンティティがリストされた順序で、次のエンティティにフォールバックします。 - トラフィックの分割は、フォールバックの試行順序に影響を与えません。

フォールバック

[AI Gateway] セクションで [ フォールバックの有効化 ] を選択して、エンドポイント上の他の提供モデルにフォールバックとしてリクエストを送信します。

  • 特定のエンティティにルーティングされた最初のリクエストが 429 エラーまたは 5XX エラーを返した場合、リクエストはエンドポイントにリストされている次のエンティティにフォールバックします。 - 要求がフォールバックで提供されるエンティティにリダイレクトされる順序は、エンドポイントの作成時または最新のエンドポイント更新時にモデルが一覧表示された順序に基づいています。トラフィックの割合は、サービス対象のエンティティに送信されるフォールバック試行の順序には影響しません。 - フォールバックは、外部モデルでのみサポートされています。 - 外部モデルへのフォールバックを有効にする前に、エンドポイントで提供される他のモデルにトラフィックの割合を割り当てる必要があります。 - トラフィックが 0% に割り当てられた外部モデルは、フォールバックモデルとしてのみ機能します。 - 最大で 2 つのフォールバックを設定できます。 - 各エンティティは、要求が成功するまで順番に 1 回試行されます。リストされたすべてのエンティティが試行され、成功しなかった場合、リクエストは失敗します。 - 最初に成功した要求と応答、または最後に失敗した要求の試行と応答は、使用状況追跡テーブルとペイロード ログ テーブルの両方に記録されます。

次の図は、次の例を示しています。

  • 3 つのサーブされたエンティティは、モデル サービング エンドポイントで提供されます。
  • 要求は最初に サーブされるエンティティ 3 にルーティングされます。
  • リクエストが 200 レスポンスを返した場合、リクエストは サーブされるエンティティ 3 で成功し、リクエストとそのレスポンスはエンドポイントの使用状況追跡テーブルとペイロードロギングテーブルに記録されます。
  • 要求が サーブされる エンティティ 3 で 429 または 5xx エラーを返した場合、要求はエンドポイントで次に提供されるエンティティである サーブされる エンティティ 1 にフォールバックします。
    • リクエストが サーブされる エンティティ 1 で 429 または 5xx エラーを返した場合、リクエストはエンドポイントで次に提供されたエンティティである サーブされる エンティティ 2 にフォールバックします。
    • 要求が サーブされる エンティティ 2 で 429 または 5xx エラーを返した場合、これがフォールバック エンティティの最大数であるため、要求は失敗します。失敗したリクエストとレスポンスエラーは、使用状況追跡テーブルとペイロードロギングテーブルに記録されます。

フォールバック図の例

UI での AI ガードレールの構成​

次の表は、 サポートされているガードレールを構成する方法を示しています。

注記

トピックのモデレーションとキーワードのフィルタリングは非推奨です。2025 年 5 月 30 日以降、これらの機能はサポートまたは使用できなくなります。これらの関数がワークフローに必要な場合は、Databricks アカウント チームに連絡して、カスタム ガードレールのプライベート プレビューに参加してください。

ガードレール

有効にする方法

詳細

安全性

[ 安全性 ] を選択すると、モデルが安全でない有害なコンテンツと相互作用するのを防ぐための保護機能が有効になります。

個人を特定できる情報 (PII) の検出

名前、住所、クレジット カード番号などの PII データがエンドポイントの要求と応答で検出された場合に、 それらをブロック または マスク することを選択します。 それ以外の場合は、[ なし ] を選択して PII 検出が発生しないようにします。

有効なトピック (非推奨)

このフィールドにトピックを直接入力できます。 複数のエントリがある場合は、各トピックの後に必ず Enter キーを押してください。 または、 .csv ファイルまたは .txt ファイルをアップロードすることもできます。

最大 50 個の有効なトピックを指定できます。 各トピックは 100 文字を超えることはできません

無効なキーワード (非推奨)

このフィールドにトピックを直接入力できます。 複数のエントリがある場合は、各トピックの後に必ず Enter キーを押してください。 または、 .csv ファイルまたは .txt ファイルをアップロードすることもできます。

無効なキーワードは最大 50 個まで指定できます。 各キーワードは 100 文字を超えることはできません。

AI Guardrail 機能の構成

使用状況追跡テーブルのスキーマ​

次のセクションでは、 system.serving.served_entities および system.serving.endpoint_usage システムテーブルの使用状況追跡テーブル スキーマをまとめます。

system.serving.served_entities 使用状況追跡テーブル スキーマ​

注記

system.serving.served_entities usage tracking システムテーブルは、現在、トークン単位の従量課金エンドポイントではサポートされていません。

system.serving.served_entities使用状況追跡システムテーブルには、次のスキーマがあります。

列名

説明

タイプ

served_entity_id

提供されたエンティティの一意の ID。

文字列

account_id

Delta Sharingの顧客 アカウント ID。

文字列

workspace_id

サービスエンドポイントの顧客ワークスペース ID。

文字列

created_by

作成者の ID。

文字列

endpoint_name

サービングエンドポイントの名前。

文字列

endpoint_id

サービングエンドポイントの一意の ID。

文字列

served_entity_name

提供されるエンティティの名前。

文字列

entity_type

提供されるエンティティのタイプ。 FEATURE_SPEC、 EXTERNAL_MODEL、 FOUNDATION_MODEL、または CUSTOM_MODEL

文字列

entity_name

エンティティの基になる名前。 ユーザーが指定した名前である served_entity_name とは異なります。 たとえば、 entity_name は Unity Catalog モデルの名前です。

文字列

entity_version

提供されたエンティティのバージョン。

文字列

endpoint_config_version

エンドポイント設定のバージョン。

INT

task

タスクの種類。 llm/v1/chat、 llm/v1/completions、または llm/v1/embeddingsを指定できます。

文字列

external_model_config

外部モデルの構成。 例えば {Provider: OpenAI}

構造体

foundation_model_config

基盤モデルの構成。 例えば{min_provisioned_throughput: 2200, max_provisioned_throughput: 4400}

構造体

custom_model_config

カスタムモデルの設定。 例えば{ min_concurrency: 0, max_concurrency: 4, compute_type: CPU }

構造体

feature_spec_config

機能仕様の構成。 例えば { min_concurrency: 0, max_concurrency: 4, compute_type: CPU }

構造体

change_time

提供されたエンティティの変更のタイムスタンプ。

TIMESTAMP

endpoint_delete_time

エンティティ削除のタイムスタンプ。 エンドポイントは、提供されるエンティティのコンテナです。 エンドポイントが削除されると、提供されたエンティティも削除されます。

TIMESTAMP

system.serving.endpoint_usage 使用状況追跡テーブル スキーマ​

system.serving.endpoint_usage使用状況追跡システムテーブルには、次のスキーマがあります。

列名

説明

タイプ

account_id

顧客アカウント ID。

文字列

workspace_id

サービスエンドポイントの顧客ワークスペース ID。

文字列

client_request_id

モデルサービング要求本文で指定できるユーザー指定の要求識別子。

文字列

databricks_request_id

すべてのモデルサービング要求にアタッチされた Databricks 生成要求識別子。

文字列

requester

サービスエンドポイントの呼び出しリクエストにアクセス許可が使用されるユーザーまたはサービスプリンシパルの ID。

文字列

status_code

モデルから返された HTTP 状態コード。

Integer

request_time

要求が受信されたタイムスタンプ。

TIMESTAMP

input_token_count

入力のトークン数。

ロング

output_token_count

出力のトークン数。

ロング

input_character_count

入力文字列またはプロンプトの文字数。

ロング

output_character_count

応答の出力文字列の文字数。

ロング

usage_context

ユーザーは、エンドポイントへの呼び出しを行うエンド ユーザーまたは顧客アプリケーションの識別子を含むマップを提供しました。 usage_contextを使用した使用法の詳細な定義を参照してください。

マップ

request_streaming

要求がストリーム・モードであるかどうか。

ブール値

served_entity_id

エンドポイントと提供されるエンティティに関する情報を検索するために system.serving.served_entities ディメンション テーブルと結合するために使用される一意の ID。

文字列

使用法をさらに定義する usage_context​

使用状況の追跡が有効になっている外部モデルに対してクエリを実行する場合は、 usage_context パラメーターに Map[String, String]型を指定できます。 使用状況コンテキスト マッピングは、使用状況追跡テーブルの usage_context 列に表示されます。 usage_contextマップサイズは 10 KiB を超えることはできません。

Bash
{
  "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 を含めることで指定できます。

Python
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 を使用します。

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 システムテーブルとトークン単位の従量課金エンドポイントの推論テーブルを結合します。 推論テーブルと使用状況の追跡は、これらのテーブルを結合するためにエンドポイントで有効にする必要があります。

SQL
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 の編集 をクリックします。

AI Gateway の機能を更新する

ノートブックの例​

次のノートブックは、Databricks Mosaic AI Gateway 機能をプログラムで有効にして使用し、プロバイダーからのモデルを管理および制御する方法を示しています。PUT /api/2.0/serving-endpoints/{name}/AI-gateway を参照してください。 REST API の詳細については、こちらをご覧ください。

Databricks Mosaic AI Gateway 機能を有効にするノートブック

Open notebook in new tab

追加のリソース​

に最終更新