本頁說明如何利用使用追蹤系統表監控 Unity Gateway 服務的使用情況。
使用追蹤表記錄模型服務、模型提供者服務及 MCP 服務的請求與回應細節。 對於模型請求，它會記錄如代幣使用率和延遲等指標。 對於 MCP 請求，它會記錄通話與服務的元資料。 利用表格監控使用者、追蹤成本，並分析服務使用與效能。
使用情況追蹤也會記錄對 Databricks 提供之模型服務的 ai_query 請求。
帳號與工作區管理員可在 Governance Hub 的 AI 頁面 查看 AI 使用的綜合概覽。
Requirements
- 一個位於 Unity Gateway 支援區域的 Azure Databricks workspace。
- 已為您的工作區啟用了 Unity Catalog。 請參閱 為 Unity Catalog 啟用工作區。
Pricing
使用追蹤是 Unity Gateway 的需收費功能。 Azure Databricks 會根據它記錄到system.ai_gateway.usage資料表的使用量收費。 請參閱 Unity Gateway 的定價。
查詢使用表
Unity Gateway 會將使用資料記錄到 system.ai_gateway.usage 系統資料表。 你可以在介面中查看表格，或從 Databricks SQL 或筆記本查詢表格。
注意
依預設，必須同時具備帳戶管理員和中繼存放區管理員角色，才能檢視或查詢 system.ai_gateway.usage 資料表。 管理員可以 管理系統資料表的存取 ，以控制使用者、群組及服務主體的權限。
若要在使用者介面中查看該表格，請點擊模型服務頁面上的使用追蹤表連結，在目錄檔案總管中開啟該表格。
要從 Databricks SQL 或筆記本查詢資料表：
SELECT * FROM system.ai_gateway.usage;
Tip
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.
內建使用儀表板
注意
有些工作區尚未顯示 Govern 下拉選單。 在這些工作區中，請使用Unity Gateway 頁面上的獨立 「建立儀表板」、「 檢視儀表板」和 「更新 」按鈕。
建立內建使用儀表板
帳號管理員可以建立內建的 Unity Gateway 使用儀表板，以監控使用情況、追蹤成本，並深入了解模型服務的效能與使用量。 從 Unity Gateway 頁面，點選右上角的 Govern ，然後點 選建立使用儀表板。 執行儀表板查詢的倉庫會自動被選中。
注意
只有帳號管理員可以建立儀表板，因為這需要具有 SELECT 資料表的 system.ai_gateway.usage 權限。 儀錶板的數據受限於 usage 數據表的保留原則。 請參閱 哪些系統數據表可供使用？。
當內建使用儀表板有新版本可用時，帳號管理員可以在 Unity Gateway 頁面的 Govern 下拉選單中，點選儀表板版本列的「更新」。
您可以使用以下儀表板設定選項來管理儀表板：
- 範圍：選擇將儀表板範圍設為帳號或工作區。
- 權限：選擇查詢是依照儀表板擁有者的權限執行，還是依照每位檢視者的權限執行。 請參閱 什麼是共用資料權限？。
- 自動更新：啟用此選項後，當新版本可用且帳號管理員造訪 Unity Gateway 頁面時，儀表板會自動更新。
當儀表板更新到版本 0.3 或更高版本時，會自動建立排程，每 6 小時刷新一次。 如有需要，可在 Lakeview 儀表板中停用此排程。 請參閱 建立排程。
檢視使用儀表板
要查看儀表板，請點選 Unity Gateway 頁面右上角的 Govern ，然後點選 Usage Dashboard。 儀表板會在一個新分頁中開啟。內建儀表板能全面檢視 Unity Gateway 模式的服務使用情況、效能與成本。 它包含多頁面追蹤請求、令牌消耗、延遲指標、錯誤率、成本明細、外部 MCP 伺服器流量，以及編碼代理活動。
儀表板預設提供跨工作空間分析。 所有儀表板頁面皆可依日期範圍及工作區 ID 進行篩選。
- 概覽標籤：顯示高層次使用指標，包括每日請求量、代幣使用趨勢、按代幣消費量排名前幾位，以及總獨立用戶數。 使用此分頁快速查看整體 Unity Gateway 活動快照，並識別最活躍的使用者與模型。
- 效能分頁：追蹤關鍵效能指標，包括延遲百分位數（P50、P90、P95、P99）、第一個位元組到達時間、錯誤率及 HTTP 狀態碼分布。 使用此分頁監控模型服務健康狀況，並找出效能瓶頸或可靠性問題。
- 使用量分頁：依模型服務、工作區及請求者詳細顯示用電量分布。 此分頁顯示代幣使用模式、請求分布及快取命中率。
- 成本可觀察性標籤：依模型服務、目標模型、使用者、服務標籤及請求標籤顯示成本分解。 此分頁也包含外部模型的預估成本。 詳見 分析 Unity Gateway 成本。
- 外部 MCP 伺服器標籤：顯示請求量、錯誤率、使用者與連線，以及外部 MCP 伺服器流量的每日使用趨勢。
- 編碼代理標籤：追蹤整合編碼代理的活動，包括 Claude Code、Codex CLI、Cursor 及 Gemini CLI。 此分頁顯示活動天數、編碼工作階段、提交次數，以及新增或移除的程式碼行數，以監控開發者工具的使用情況。 更多細節請參閱 Coding agent 儀表板 。
使用表綱要
表格 system.ai_gateway.usage 的架構如下：
| 欄位名稱 | 類型 | Description | Example |
|---|---|---|---|
account_id |
STRING | 帳號ID。 | 11d77e21-5e05-4196-af72-423257f74974 |
workspace_id |
STRING | 工作區識別碼。 | 1653573648247579 |
request_id |
STRING | 要求的唯一識別碼。 | b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00 |
invocation_id |
STRING | 每次個別推論呼叫的唯一識別碼。 多個呼叫可以共享相同 request_id內容，例如護欄檢查或多回合代理通話。 用 invocation_id 來區分它們。 |
c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60 |
schema_version |
整數 | 使用紀錄的結構描述版本。 | 1 |
service_type |
STRING | 產生使用紀錄的服務類型。 數值為 MODEL_SERVICE、 MCP_SERVICE、 MODEL_PROVIDER_SERVICE和 。 |
MODEL_SERVICE |
service_id |
STRING | 模型服務、MCP 服務或模型提供者服務的識別碼。 | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
service_name |
STRING | Unity 目錄中已完全限定該服務名稱。 | main.default.github_tools |
service_tags |
MAP | 套用到 Unity 目錄的資源標籤可在建立或更新時保護。 它們適用於所有對服務的請求，並有助於依團隊、成本中心或專案分類使用情況。 | {"team": "engineering"} |
endpoint_id |
STRING | Unity Gateway 模型服務的唯一 ID。 | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
endpoint_name |
STRING | Unity Gateway 模型服務的名稱。 | system.ai.gpt-5-2 |
endpoint_tags |
MAP | 標籤在模型服務建立或更新時設定。 它們適用於所有對模型服務的請求，並有助於依團隊、成本中心或專案分類服務。 | {"team": "engineering"} |
endpoint_metadata |
STRUCT | 模型服務中繼資料，包括 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 | API 呼叫的類型（例如聊天、完成或嵌入）。 | mlflow/v1/chat/completions |
request_tags |
MAP | 使用者提供的標籤，透過 HTTP 標頭隨個別請求 Databricks-Ai-Gateway-Request-Tags 一同傳送。 使用請求標籤將使用歸因於特定專案、團隊、環境或終端使用者。 請參閱 為用量追蹤標記請求 和 請求標記。 |
{"project": "chatbot", "team": "ml-platform"} |
invocation_metadata |
STRUCT | 請求來源、模型提供者報告的服務層級，以及請求是否使用Claude訂閱的資訊。 | {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false} |
input_tokens |
LONG | 輸入令牌的數目。 | 100 |
output_tokens |
LONG | 輸出令牌的數目。 | 100 |
total_tokens |
LONG | 總標記數（輸入 + 輸出）。 | 200 |
token_details |
STRUCT | 詳細的 token 與工具使用明細，包括 cache_read_input_tokens、cache_creation_input_tokens、output_reasoning_tokens、file_search_count、cache_creation_5m_input_tokens、cache_creation_1h_input_tokens 和 num_web_search_queries。 |
{"cache_read_input_tokens": 100, ...} |
response_content_type |
STRING | 回應的內容類型。 | application/json |
status_code |
INT | 回應的 HTTP 狀態碼。 | 200 |
routing_information |
STRUCT | 備援嘗試的路由細節。 包含attempts一個陣列，分別為 priority、 action、 destinationdestination_idstatus_codeerror_codelatency_msstart_timeend_time，對於請求過程中嘗試的每個模型。 |
{"attempts": [{"priority": "1", ...}]} |
mcp_metadata |
STRUCT | 請求 MCP 服務的詳細資訊，包括呼叫的工具、伺服器類型及 JSON-RPC 操作。 已填入 MCP_SERVICE 列。 |
{"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"} |
session_metadata |
STRUCT | 會話與客戶背景，包括會話與子代理 ID、編碼代理名稱與版本、客戶介面、推理工作量，以及智慧路由配方。 利用這些欄位將相關請求分組，並分析各代理或會話的使用情況。 | {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...} |
auth_mode |
STRING | 用於驗證請求的 Databricks 憑證類型：個人存取權杖（PAT）或 OAuth 權杖（OAUTH）。 |
OAUTH |
巢狀欄位結構
以下表格描述巢狀 STRUCT 欄位中的欄位。 現場可用性取決於用於請求的服務、型號及用戶端。
呼叫與標記元資料
| 欄位路徑 | 類型 | Description |
|---|---|---|
invocation_metadata.source |
STRING | 發起請求的應用程式、服務或 API。 使用此欄位將使用歸因於其來源。 值包括 AI_PLAYGROUND、 EXTERNAL_CLIENT、 AI_QUERYGUARDRAILMANAGED_AGENT、 和 。 |
invocation_metadata.service_tier |
STRING | 模型提供者在推論回應中回報的服務層級，例如 default 或 priority。 使用此欄位比較不同供應商定價層級的使用情況。 |
invocation_metadata.relayed |
布林 | 是否透過來電者的 Claude 訂閱，將請求轉達給 Anthropic。 |
token_details.cache_read_input_tokens |
LONG | 從提示快取讀取的標記數量。 |
token_details.cache_creation_input_tokens |
LONG | 寫入提示詞快取的詞元數量。 |
token_details.output_reasoning_tokens |
LONG | 輸出中推理標記的數量。 |
token_details.cache_creation_5m_input_tokens |
LONG | 寫入提示快取的輸入標記數量，壽命為 5 分鐘。 |
token_details.cache_creation_1h_input_tokens |
LONG | 寫入提示快取的輸入標記數量，壽命為1小時。 |
token_details.file_search_count |
LONG | 請求時所呼叫的檔案搜尋工具數量。 |
token_details.num_web_search_queries |
LONG | 作為請求的一部分，所提出的可計費網路搜尋查詢數量。 |
MCP 服務元資料
這些欄位會在 mcp_metadata 中填入，適用於 MCP_SERVICE 資料列。
| 欄位路徑 | 類型 | Description |
|---|---|---|
mcp_metadata.tool_name |
STRING | MCP tools/call 請求所呼叫的工具名稱。 使用此欄位分析伺服器上個別工具的使用情況。 |
mcp_metadata.server_type |
STRING | 處理請求的 MCP 伺服器類別，例如 EXTERNAL 或 SYSTEM。 |
mcp_metadata.json_rpc_method |
STRING | 客戶端請求的 JSON-RPC 操作，例如 tools/call 呼叫工具、 tools/list 發現工具或 initialize 啟動會話。 |
會話中繼資料
這些 session_metadata 欄位有助於關聯會話中的請求，並區分編碼代理、用戶端介面及請求設定。 每個欄位在用戶端或請求提供相應資訊時才會填入。
| 欄位路徑 | 類型 | Description |
|---|---|---|
session_metadata.client_session_id |
STRING | 客戶端提供的會話 ID。 用它將同一對話或程式碼代理工作階段中發出的請求歸為同一組。 |
session_metadata.client_subagent_id |
STRING | 客戶提供的分代理 ID。 將它與 client_session_id 搭配使用，以區分父工作階段內來自子代理的請求。 |
session_metadata.coding_agent |
STRING | 發送請求的編碼代理的正規化名稱，例如 claude-code 或 codex。 |
session_metadata.agent_version |
STRING | 編碼代理報告的版本。 搭配 coding_agent 使用它，以比較各個代理程式版本的使用情況。 |
session_metadata.surface |
STRING | 程式代理從此發送請求的用戶端介面，例如命令列介面、IDE 或桌面應用程式。 |
session_metadata.reasoning_effort |
STRING | 請求中指定的推理努力，例如 low、 medium或 high。 可用的數值取決於模型與 API。 |
session_metadata.smart_router_name |
STRING | 客戶端選擇的智慧路由配方名稱。 使用它可依路由配方將使用量分組。 |
用於使用追蹤的標籤請求
請求標籤是呼叫者附加於個別請求的自訂鍵值對。 使用請求標籤來依專案、團隊、環境、終端使用者或其他與組織相關的維度來歸屬性使用。 請求標籤會被記錄在 system.ai_gateway.usage 表格中，並可用來篩選、彙整及分析使用資料。
要標記個別請求，請將 Databricks-Ai-Gateway-Request-Tags HTTP 標頭與 JSON 物件結合，將字串金鑰映射到字串值。 請求標籤會記錄於使用情況表中的 request_tags 欄，以及 推論表 中。
關於如何使用 REST API、OpenAI SDK 和 Anthropic SDK 設定請求標籤的範例，請參見請求標籤。
例如，你可以用請求標籤來彙整專案的使用情況：
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 的非串流、非嵌入回應的令牌使用情況。