エンドポイントを提供するモデルで AI ゲートウェイを設定します

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

要件

• モデルの提供がサポートされているリージョンの Databricks ワークスペース。 リージョンの 可用性に対応するモデルを参照してください。
• エンドポイントを提供するモデル。 ワークスペースで 事前構成済みのトークンごとの支払いエンドポイント のいずれかを使用するか、次の操作を行うことができます。
  • 外部モデルのエンドポイントを作成するには、「外部 モデルサービス エンドポイントを作成する」の手順 1 と 2 を実行します。
  • プロビジョニング済みスループットのエンドポイントを作成するには、「プロビジョニング済みスループット基盤モデル API を参照してください。
  • カスタム モデルのエンドポイントを作成するには、「エンドポイントの 作成」を参照してください。

UI を使用して AI ゲートウェイを構成する

エンドポイント作成ページの [AI Gateway ] セクションでは、AI Gateway の機能を個別に構成できます。 エンドポイントとプロビジョニングされたスループット エンドポイントを提供する外部モデルで使用できる機能については、「 サポートされている機能 」を参照してください。

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

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

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

UI で AI Guardrails を構成する

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

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

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

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

system.serving.served_entities 利用状況追跡システムテーブルのスキーマは以下の通りです：

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

system.serving.endpoint_usage 利用状況追跡システムテーブルのスキーマは以下の通りです：

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 クライアントを使用している場合は、usage_context パラメーターに含めることで、extra_bodyを指定できます。

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 を追加できます。

エンドポイントの使用状況を監視する

エンドポイントの使用状況を監視するには、エンドポイントのシステム テーブルと推論テーブルを結合します。

システム テーブルの結合

この例は、外部モデルとプロビジョニングされたスループット エンドポイントにのみ適用されます。 served_entities システム テーブルは、トークンごとの支払いエンドポイントではサポートされていませんが、推論テーブルと使用状況テーブルを結合して同様の詳細を取得できます。

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 ゲートウェイ機能を更新

AIゲートウェイの機能は、以前に有効になっていたエンドポイントおよび有効になっていなかったエンドポイントを提供するモデルで更新できます。 AI Gateway 構成の更新プログラムの適用には約 20 ~ 40 秒かかりますが、レート制限の更新には最大で 60 秒かかることがあります。

サービス UI を使用して、エンドポイントを提供するモデルの AI ゲートウェイ機能を更新する方法を次に示します。

エンドポイント ページの [ゲートウェイ ] セクションで、有効になっている機能を確認できます。 これらの機能を更新するには、[ AI ゲートウェイの編集] をクリックします。

ノートブックの例

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

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

ノートブックを取得する

その他のリソース

• モザイク AI ゲートウェイの概要。
• AI ゲートウェイ対応の推論テーブルを使用して、提供されたモデルを監視します。