モデルの使用状況を追跡する

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

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

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

アカウント管理者とワークスペース管理者は、ガバナンスハブのAI ページで、AI 使用状況の統合された概要を確認できます。

要件

• Unity Gatewayがサポートされているリージョン内のDatabricksワークスペース。
• ワークスペースでUnity Catalog有効化されていること。 Unity Catalog のワークスペースを有効にする方法をご覧ください。

価格

使用状況の追跡は、Unity AIゲートウェイの有料機能です。Databricks は、system.ai_gateway.usage テーブルにログが記録された使用状況に対して課金します。Unity AIゲートウェイの価格を参照してください。

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

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

注記

system.ai_gateway.usage テーブルをdefaultで表示またはクエリーするには、アカウント管理者ロールとメタストア管理者ロールの両方が必要です。管理者は システムテーブルへのアクセスを管理して、ユーザー、グループ、および Service Principal の権限を制御できます。

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.

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

注記

一部のワークスペースでは、 ガバナンス ドロップダウンがまだ表示されません。それらのワークスペースでは、代わりに Unity Gateway ページのスタンドアロンの ダッシュボードを作成 、 ダッシュボードを表示 、および 更新 ボタンを使用してください。

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

アカウント管理者は、組み込みのUnity AIゲートウェイ使用状況ダッシュボードを作成して、使用状況の監視、コストの追跡、モデルサービスのパフォーマンスと消費に関する知見を得ることができます。Unity AIゲートウェイページで、右上にある ガバナンス をクリックし、 使用状況ダッシュボードの作成 をクリックします。ダッシュボードのクエリーを実行するwarehouseは自動的に選択されます。

注記

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

組み込みの使用状況ダッシュボードの新しいバージョンが利用可能な場合、アカウント管理者は Unity Gateway ページの Govern ドロップダウンにあるダッシュボードバージョンの行で 更新 をクリックできます。

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

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

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

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

ダッシュボードを表示するには、Unity Gatewayページの右上にある [Govern] をクリックし、 [Usage Dashboard] をクリックします。ダッシュボードが新しいtabで開きます。組み込みダッシュボードでは、Unity Gatewayモデルサービスの使用状況、パフォーマンス、コストを包括的に可視化できます。これには、リクエスト、トークン消費量、レイテンシメトリクス、エラー率、コストの内訳、外部MCPサーバーのトラフィック、コーディングエージェントのアクティビティを追跡する複数のページが含まれます。

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

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

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

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ゲートウェイモデルサービスの一意のID。	43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name	STRING	Unity Gatewayモデルサービスの名前。	system.ai.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	宛先モデルまたはプロバイダーの名前。	system.ai.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", ...}]}

列名	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ゲートウェイモデルサービスの一意のID。	43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name	STRING	Unity Gatewayモデルサービスの名前。	system.ai.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	宛先モデルまたはプロバイダーの名前。	system.ai.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 Gateway は、1 MiB を超える非ストリーミング、非埋め込みのレスポンスに対するトークン使用量を追跡しません。

その他のリソース

• Unity GatewayによるAIガバナンス
• モデル API（モデルサービス）の作成と管理
• モデル API（モデルサービス）のクエリー
• コーディングエージェントの統合
• リクエストと応答を推論テーブルにLogsする
• モデルサービスおよびMCPサービスにレート制限を適用する