本頁說明如何利用使用追蹤系統表監控 Unity AI Gateway 服務的使用情況。
使用追蹤表會自動擷取模型服務的請求與回應細節，記錄如令牌使用率與延遲等重要指標。 您可以利用此表格中的數據監控用戶、追蹤成本，並深入了解模型服務的效能與使用情況。
使用情況追蹤也會記錄對 Databricks 提供之模型服務的 ai_query 請求。
帳號與工作區管理員可在 Governance Hub 的 AI 頁面 查看 AI 使用的綜合概覽。
Requirements
- 位於Unity AI Gateway 支援區域的 Azure Databricks 工作區。
- 已為您的工作區啟用了 Unity Catalog。 請參閱 為 Unity Catalog 啟用工作區。
Pricing
使用追蹤是計費的 Unity AI Gateway 功能。 Azure Databricks 會根據它記錄到system.ai_gateway.usage資料表的使用量收費。 請參閱 Unity AI Gateway 價格。
查詢使用表
Unity AI 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 AI Gateway 頁面上的獨立 「建立儀表板」、「 檢視儀表板」和 「更新 」按鈕。
建立內建使用儀表板
帳號管理員可以建立內建的 Unity AI Gateway 使用儀表板，以監控使用情況、追蹤成本，並深入了解模型服務的效能與使用量。 在 Unity AI Gateway 頁面中，按一下右上角的 Govern，然後按一下 Create Usage Dashboard。 執行儀表板查詢的倉庫會自動被選中。
注意
只有帳號管理員可以建立儀表板，因為這需要具有 SELECT 資料表的 system.ai_gateway.usage 權限。 儀錶板的數據受限於 usage 數據表的保留原則。 請參閱 哪些系統數據表可供使用？。
當內建使用儀表板有新版本可用時，帳號管理員可以在 Unity AI Gateway 頁面的 Govern 下拉選單中，點選「更新」的版本列。
您可以使用以下儀表板設定選項來管理儀表板：
- 範圍：選擇將儀表板範圍設為帳號或工作區。
- 權限：選擇查詢是依照儀表板擁有者的權限執行，還是依照每位檢視者的權限執行。 請參閱 什麼是共用資料權限？。
- 自動更新：啟用此選項後，當新版本可用且帳號管理員造訪 Unity AI Gateway 頁面時，儀表板會自動更新。
當儀表板更新到版本 0.3 或更高版本時，會自動建立排程，每 6 小時刷新一次。 如有需要，可在 Lakeview 儀表板中停用此排程。 請參閱 建立排程。
檢視使用儀表板
要查看儀表板，請點選 Unity AI Gateway 頁面右上角的 「治理 」，然後點選 「使用後台」。 儀表板會以新分頁開啟。內建儀表板能全面檢視 Unity AI Gateway 模型的服務使用情況、效能與成本。 它包含多頁面追蹤請求、令牌消耗、延遲指標、錯誤率、成本明細、外部 MCP 伺服器流量，以及編碼代理活動。
儀表板預設提供跨工作空間分析。 所有儀表板頁面皆可依日期範圍及工作區 ID 進行篩選。
- 概覽標籤：顯示高層次使用指標，包括每日請求量、代幣使用趨勢、按代幣消費量排名前幾位，以及總獨立用戶數。 使用此分頁快速瀏覽整體 Unity AI Gateway 活動，並識別最活躍的使用者與模型。
- 效能分頁：追蹤關鍵效能指標，包括延遲百分位數（P50、P90、P95、P99）、第一個位元組到達時間、錯誤率及 HTTP 狀態碼分布。 使用此分頁監控模型服務健康狀況，並找出效能瓶頸或可靠性問題。
- 使用量分頁：依模型服務、工作區及請求者詳細顯示用電量分布。 此分頁顯示代幣使用模式、請求分布及快取命中率。
- 成本可觀察性標籤：依模型服務、目標模型、使用者、服務標籤及請求標籤顯示成本分解。 此分頁也包含外部模型的預估成本。 詳見 分析 Unity AI 閘道費用。
- 外部 MCP 伺服器標籤：顯示請求量、錯誤率、使用者與連線，以及外部 MCP 伺服器流量的每日使用趨勢。
- 編碼代理標籤：追蹤整合編碼代理的活動，包括游標、Claude Code、Gemini CLI 及 Codex 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 |
endpoint_id |
STRING | Unity AI Gateway 模型服務的獨特 ID。 | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
endpoint_name |
STRING | Unity AI 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 | 系統產生的推論呼叫元資料。 包含 source，即發起呼叫的服務或路徑。 |
{"source": "EXTERNAL_CLIENT"} |
input_tokens |
LONG | 輸入令牌的數目。 | 100 |
output_tokens |
LONG | 輸出令牌的數目。 | 100 |
total_tokens |
LONG | 總標記數（輸入 + 輸出）。 | 200 |
token_details |
STRUCT | 詳細的代幣分解包括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 |
STRUCT | 備援嘗試的路由細節。 包含attempts一個陣列，分別為 priority、 action、 destinationdestination_idstatus_codeerror_codelatency_msstart_timeend_time，對於請求過程中嘗試的每個模型。 |
{"attempts": [{"priority": "1", ...}]} |
用於使用追蹤的標籤請求
請求標籤是呼叫者附加於個別請求的自訂鍵值對。 使用請求標籤來依專案、團隊、環境、終端使用者或其他與組織相關的維度來歸屬性使用。 請求標籤會被記錄在 system.ai_gateway.usage 表格中，並可用來篩選、彙整及分析使用資料。
要標記個別請求，請將 Databricks-Ai-Gateway-Request-Tags HTTP 標頭與 JSON 物件結合，將字串金鑰映射到字串值。 請求標籤會記錄於使用情況表中的 request_tags 欄，以及 推論表 中。
關於如何使用 REST API、OpenAI SDK 和 Anthropic SDK 設定請求標籤的範例，請參見 Tag requests for usage tracking。
例如，你可以用請求標籤來彙整專案的使用情況：
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 不會追蹤超過 1 MiB 的非串流、非嵌入回應的令牌使用情況。