Unity AI Gatewayサービスのモデル使用状況

備考

ベータ版

この機能はベータ版です。アカウント管理者は、アカウント コンソールの [プレビュー] ページからこの機能へのアクセスを制御できます。 Databricksのプレビューを管理するを参照してください。

このページでは、使用状況追跡システムテーブルを使用して、Unity AI Gateway サービスの使用状況を監視する方法について説明します。

使用状況追跡テーブルは、モデルサービスのリクエストとレスポンスの詳細を自動的にキャプチャし、トークン使用量やレイテンシーなどの重要なメトリクスを記録します。このテーブルのデータを使用して、ユーザーの監視、コストの追跡、モデルサービスのパフォーマンスと消費量に関する知見を得ることができます。

使用状況の追跡は、Databricksが提供するモデルサービスへのai_queryリクエストもキャプチャします。

要件

• お客様のアカウントでUnity AI Gatewayのプレビュー版が有効になりました。Databricksのプレビューを管理するを参照してください。
• Unity AI GatewayでサポートされているリージョンにあるDatabricksワークスペース。
• ワークスペースでUnity Catalog有効化されていること。 Unity Catalog のワークスペースを有効にする方法をご覧ください。

使用状況テーブルを照会する

Unity AI Gateway は、使用状況データを system.ai_gateway.usage システムテーブルにログに記録します。UIでテーブルを表示したり、Databricks SQL またはノートブックからテーブルをクエリしたりできます。

注記

アカウント管理者のみがsystem.ai_gateway.usageテーブルを表示またはクエリするアクセス許可を持っています。

UIでテーブルを表示するには、モデルサービスページの使用状況トラッキングテーブルリンクをクリックして、Catalog Explorerでテーブルを開きます。

Databricks SQLまたはノートブックからテーブルをクエリするには：

SQL

SELECT * FROM system.ai_gateway.usage;

プロンプト

Genie Code (エージェントモード) がこれを実行できます。このプロンプト例をお試しください。

Query the system.ai_gateway.usage table to analyze AI Gateway usage showing request count and total tokens, grouped by endpoint name for the last 7 days.

組み込み使用状況ダッシュボード

組み込みの使用状況ダッシュボードを作成

アカウント管理者は、AI Gateway ページで [ダッシュボードの作成] をクリックすることで、組み込みのUnity AI Gateway 使用状況ダッシュボードを作成し、使用状況を監視し、コストを追跡し、モデルサービスパフォーマンスと消費に関する知見を得ることができます。アカウント管理者は、ダッシュボードクエリの実行に使用されるウェアハウスを更新することもでき、その変更はすべての後続クエリに適用されます。

注記

ダッシュボードの作成は、system.ai_gateway.usage テーブルに対する SELECT 権限が必要なため、アカウント管理者に制限されています。ダッシュボードのデータは、usage テーブルの保持ポリシーの対象となります。「利用可能なシステムテーブル」を参照してください。

組み込みの使用状況ダッシュボードの新しいバージョンが利用可能な場合、アカウント管理者はAI Gatewayページでダッシュボードアクションメニューから 「更新」 をクリックできます。

ダッシュボードを管理するには、以下のダッシュボード構成オプションを使用できます。

• スコープ : ダッシュボードをアカウントにスコープするか、ワークスペースにスコープするかを選択します。
• 権限 : クエリをダッシュボード所有者の権限で実行するか、各閲覧者の権限で実行するかを選択します。共有データ権限とは何ですか？を参照してください。
• 自動更新 ：このオプションを有効にすると、新しいバージョンが利用可能になり、アカウント管理者がAI Gatewayページにアクセスするたびに、ダッシュボードが自動的に更新されます。

ダッシュボードがバージョン0.3以降に更新されると、6時間ごとにダッシュボードを更新するスケジュールが自動的に作成されます。必要に応じて、このスケジュールはLakeviewダッシュボードで無効にできます。スケジュールを作成するを参照してください。

使用状況ダッシュボードを表示

ダッシュボードを表示するには、AI Gatewayページから View Dashboard をクリックします。組み込みダッシュボードは、Unity AI Gatewayモデルサービスの利用状況、パフォーマンス、およびコストに関する包括的な可視性を提供します。これには、リクエスト、トークン消費量、レイテンシーメトリクス、エラー率、コスト内訳、外部MCPサーバートラフィック、およびコーディングエージェントのアクティビティを追跡する複数のページが含まれています。

このダッシュボードは、デフォルトでクロスワークスペースのアナリティクスを提供します。すべてのダッシュボードページは、日付範囲およびワークスペース ID でフィルタリングできます。

• 概要タブ ：1日のリクエスト量、時間経過に伴うトークン使用量の傾向、トークン消費量上位のユーザー、および一意のユーザー総数など、上位の使用状況メトリクスを表示します。このタブを使用して、Unity AIゲートウェイ全体のアクティビティのスナップショットを把握し、最もアクティブなユーザーとモデルを特定できます。
• **パフォーマンス タブ**: レイテンシーパーセンタイル（P50、P90、P95、P99）、ファーストバイトまでの時間、エラー率、HTTPステータスコードの分布など、主要なパフォーマンスメトリクスを追跡します。このタブを使用して、モデルサービスの正常性を監視し、パフォーマンスのボトルネックや信頼性の問題を特定します。
• 使用状況タブ ：モデルサービス、ワークスペース、およびリクエスターごとの詳細な消費内訳が表示されます。このタブには、トークンの使用パターン、リクエストの分布、およびキャッシュヒット率が表示されます。
• コスト可視化タブ : モデルサービス、ターゲットモデル、ユーザー、サービスタグ、リクエストタグごとのコストの内訳を示します。このタブには、外部モデルの推定コストも含まれます。Unity AI Gatewayのコストを監視するを参照してください。
• 外部 MCP サーバータブ : 外部 MCP サーバーのトラフィックに関するリクエスト量、エラー率、ユーザーと接続、日次使用傾向を表示します。
• コーディングエージェント タブ ：Cursor、Claude Code、Gemini CLI、Codex CLI などの統合されたコーディングエージェントからのアクティビティを追跡します。このタブには、開発者ツールの使用状況を監視するため、アクティブな日数、コーディングセッション、コミット、追加または削除されたコード行数といったメトリクスが表示されます。詳細については、コーディングエージェントダッシュボードを参照してください。

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

system.ai_gateway.usageテーブルは次のスキーマを持っています:

列名	Type	説明	例
account_id	STRING	アカウントID。	11d77e21-5e05-4196-af72-423257f74974
workspace_id	STRING	ワークスペースID。	1653573648247579
request_id	STRING	リクエストの一意の識別子。	b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
invocation_id	STRING	個々の推論呼び出しのための一意の識別子。ガードレールチェックやマルチターンのエージェント呼び出しのように、複数の呼び出しで同じrequest_idを共有できます。それらを区別するためにinvocation_idを使用します。	c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version	Integer	使用状況レコードのスキーマバージョンです。	1
endpoint_id	STRING	Unity AI Gateway モデルサービスの一意の ID。	43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name	STRING	Unity AI Gateway モデルサービスの名前。	databricks-gpt-5-2
endpoint_tags	マップ	作成または更新時にモデルサービスで設定されたタグ。これらはモデルサービスへのすべてのリクエストに適用され、チーム、コストセンター、またはプロジェクトごとにサービスを分類するのに役立ちます。	{"team": "engineering"}
endpoint_metadata	構造体	モデルサービスのメタデータには、creator、creation_time、last_updated_time、destinations、inference_table、およびfallbacksが含まれます。	{"creator": "user.name@email.com", "creation_time": "2026-01-06T12:00:00.000Z", ...}
event_time	TIMESTAMP	リクエストが受信されたタイムスタンプ。	2026-01-20T19:48:08.000+00:00
latency_ms	LONG	合計レイテンシー（ミリ秒単位）。	300
time_to_first_byte_ms	LONG	最初のバイトまでの時間 (ミリ秒単位)。	300
destination_type	STRING	宛先の種類（例えば、外部モデルまたは基盤モデル）。	PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name	STRING	宛先モデルまたはプロバイダーの名前。	databricks-gpt-5-2
destination_id	STRING	送信先の一意のIDです。	507e7456151b3cc89e05ff48161efb87
destination_model	STRING	要求に使用された特定のモデル。	GPT-5.2
requester	STRING	リクエストを行ったユーザーまたはサービスプリンシパルのID。	user.name@email.com
requester_type	STRING	リクエスターの種類（ユーザー、サービスプリンシパル、またはユーザーグループ）。	USER
ip_address	STRING	要求元のIPアドレスです。	1.2.3.4
url	STRING	リクエストのURLです。	https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent	STRING	要求元のユーザーエージェント。	OpenAI/Python 2.13.0
api_type	STRING	The type of API call (for example, chat, completions, or embeddings).	mlflow/v1/chat/completions
request_tags	マップ	ユーザーが指定したタグは、Databricks-Ai-Gateway-Request-Tags HTTPヘッダーを使用して個々のリクエストと共に送信されます。リクエスト タグを使用して、使用状況を特定のプロジェクト、チーム、環境、またはエンドユーザーに帰属させます。使用状況追跡のためのタグリクエストと使用状況追跡のためのタグリクエストを参照してください。	{"project": "chatbot", "team": "ml-platform"}
invocation_metadata	構造体	推論呼び出しに関するシステム生成のメタデータ。source（呼び出しを開始したサービスまたはパス）が含まれます。	{"source": "EXTERNAL_CLIENT"}
input_tokens	LONG	入力トークンの数。	100
output_tokens	LONG	出力トークン数。	100
total_tokens	LONG	合計トークン数（入力 + 出力）。	200
token_details	構造体	cache_read_input_tokens、cache_creation_input_tokens、およびoutput_reasoning_tokensを含む、トークンの詳細な内訳。	{"cache_read_input_tokens": 100, ...}
response_content_type	STRING	応答のコンテンツタイプ。	application/json
status_code	INT	応答のHTTPステータスコードです。	200
routing_information	構造体	フォールバックの試行に関するルーティングの詳細。リクエスト中に試行された各モデルに対して、priority、action、destination、destination_id、status_code、error_code、latency_ms、start_time、およびend_timeを含むattempts配列が含まれています。	{"attempts": [{"priority": "1", ...}]}

使用状況の追跡に関するタグリクエスト

リクエストタグは、呼び出し元が個々のリクエストにアタッチするカスタムのキーと値のペアです。リクエストタグを使用して、プロジェクト、チーム、環境、エンドユーザー、または組織に関連するその他のあらゆる側面ごとに使用状況をアトリビュートします。リクエストタグはsystem.ai_gateway.usageテーブルにログ記録され、使用状況データをフィルタリング、集計、分析するために使用できます。

個々のリクエストにタグを付けるには、Databricks-Ai-Gateway-Request-Tags HTTPヘッダーに、文字列キーを文字列値にマッピングするJSONオブジェクトを含めます。リクエストタグは使用状況テーブルのrequest_tags列にログ記録され、および推論テーブルにログ記録されます。

REST API、OpenAI SDK、Anthropic SDK を使用してリクエストタグを設定する方法の例については、使用状況追跡のリクエストのタグ付けを参照してください。

たとえば、リクエストタグを使用してプロジェクト別に利用状況を集計できます：

SQL

SELECT
  request_tags['project'] AS project,
  COUNT(*) AS request_count,
  SUM(total_tokens) AS total_tokens
FROM system.ai_gateway.usage
WHERE request_tags['project'] IS NOT NULL
GROUP BY request_tags['project']
ORDER BY total_tokens DESC;

その他のリソース

• Unity AI Gateway による AI ガバナンス
• Unity AI Gateway エンドポイントを構成します
• モデルサービスをクエリーします。
• コーディングエージェントの統合
• 推論テーブルを使用したモデルサービスの監視
• Unity AI Gatewayを使用してAIサービスのレート制限を構成します。