透過 system.ai_gateway.usage 系統表監控 Unity Gateway 服務的使用情況。 它能擷取來自多種來源的模型服務、模型提供者服務及 MCP 服務的請求,包括 AI 查詢、編碼代理、Databricks 應用程式、AI Playground 及其他應用程式。
使用紀錄包括請求者與服務細節、回應狀態、模型 Token 使用與延遲、MCP 呼叫中繼資料,以及編碼代理工作階段中繼資料。 查詢表格進行自訂分析,或使用 內建的使用情況儀表板 監控使用、支出、採用率及績效。
帳號與工作區管理員也可在 Governance Hub 的 AI 頁面 查看 AI 使用情況的綜合概覽。
Requirements
- 一個位於 Unity Gateway 支援區域的 Azure Databricks workspace。
- 已為您的工作區啟用了 Unity Catalog。 請參閱 為 Unity Catalog 啟用工作區。
- 依預設,必須同時具備帳戶管理員和中繼存放區管理員角色,才能檢視或查詢
system.ai_gateway.usage資料表。 管理員可以 管理系統資料表的存取 ,以控制使用者、群組及服務主體的權限。
查詢使用表
Unity Gateway 會將使用資料記錄到 system.ai_gateway.usage 系統資料表。 你可以在介面中查看表格,或從 Databricks SQL 或筆記本查詢表格。
注意
紀錄通常一小時內可取得。 新工作空間的資料傳輸可能比這更久。
若要在使用者介面中查看該表格,請點擊模型服務頁面上的使用追蹤表連結,在目錄檔案總管中開啟該表格。
要從 Databricks SQL 或筆記本查詢資料表:
SELECT * FROM system.ai_gateway.usage;
Tip
Genie Code 可以幫你做到這點。 請嘗試以下範例提示:
Query the system.ai_gateway.usage table to analyze Unity Gateway usage showing request count and total tokens, grouped by endpoint name for the last 7 days.
Pricing
使用追蹤是 Unity Gateway 的需收費功能。 Azure Databricks 會根據它記錄到system.ai_gateway.usage資料表的使用量收費。 請參閱 Unity Gateway 的定價。
內建使用儀表板
內建的 Unity Gateway 使用儀表板提供跨模型、MCP 服務、編碼代理及技能的使用、支出、採用率與效能整合視圖。
建立儀表板
帳號管理員可以從 Unity Gateway 頁面建立儀表板:
- 點擊 「治理 > 建立使用量儀表板」。
- 選擇「 帳戶使用」 以分析跨工作區的使用情況,或選擇「 工作區使用」 以限制分析至目前的工作區。
- 設定 資料權限:
- 分享資料權限:檢視者會利用你的資料權限執行儀表板查詢。
- 個別資料權限:每位檢視者使用自己的資料權限執行儀表板查詢。
- 選擇是否啟用 自動更新 與 排程資料刷新。
- 點擊 設定並發佈。
預設的 SQL 倉儲會自動被選擇。 執行儀表板查詢的身分識別需要存取底層系統資料表。 請參見「授權系統資料表」與「儀表板資料權限」。
注意
在沒有 Govern 下拉式選單的工作區中,請使用 Unity Gateway 頁面上的獨立 建立儀表板、檢視儀表板 和 更新 按鈕。
探索儀表板
點選「 管理 > 使用量儀表板 」,在新分頁中開啟儀表板。
| Tab | 分析 |
|---|---|
| Overview | 檢視使用情況、權杖、活躍用戶及程式設計代理工作階段。 依花費、支出趨勢,以及每個代幣或每次請求的支出來比較模型和用戶。 |
| 支出 | 依模型與使用者分析支出,比較代幣消耗與快取,並透過服務與請求標籤將支出歸屬。 |
| 程式碼代理 | 比較代理採用率、harness 使用情況、會話、代幣消耗量及子代理。 調查依預估花費排名的個別工作階段。 |
| 智慧路由 | 追蹤 智慧路由、會話與使用者採用率、會話退出率,以及智慧路由與非智慧路由請求的模型組合預估節省。 |
| MCPs | 追蹤工具呼叫與活躍使用者,識別常用服務與工具,並比較使用來源。 |
| 技能 | 追蹤 Skill 的下載與載入,比較 Skill 採用情況,並檢視各使用者的活動。 |
| 績效 | 比較模型與 MCP 延遲、串流到第一個位元組的時間、輸出標記數/秒、快取命中率、錯誤及速率限制呼叫。 |
| 讀我檔案 | 檢視儀表板功能、近期變更及底層資料來源連結。 |
選擇一個日期範圍來聚焦分析,或選擇 服務標籤金鑰 及一個或多個 服務標籤值 項目,將使用量與支出縮小至特定團隊或專案。 以帳戶範圍為基礎的儀表板也包含 Workspace ID 篩選器。 服務標籤篩選器不適用於技能索引標籤。
更新儀表板
當有較新版本的儀表板可用時,帳號管理員可以在 Govern 下拉選單的儀表板版本列點選 更新。 啟用 自動更新 後,當帳號管理員造訪 Unity Gateway 頁面時,會套用更新的範本。
更新會將儀表板內容替換為最新範本,並可能覆蓋自訂設定。 如果你想保留修改,記得先在更新前保存一份副本。
重新整理儀表板資料
排程資料更新 每六小時刷新一次查詢結果。
在儀表板中管理重新整理排程。 請參閱 建立排程。
使用表綱要
表格 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_QUERY、 DATABRICKS_APPS、 GUARDRAIL、 WEB_SEARCH、 MANAGED_AGENT、 ROUTER和 SAFEGUARD_CLASSIFIER。 |
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 欄位有助於關聯會話中的請求,並區分編碼代理、用戶端介面及請求設定。 每個欄位在用戶端或請求提供相應資訊時才會填入。 用戶端會透過其請求標頭回報 coding_agent、agent_version 和 surface,而 Unity Gateway 不會驗證這些標頭。
| 欄位路徑 | 類型 | 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。 當該標頭有值時,Unity Gateway 會從 Databricks-Custom-Coding-Agent 請求標頭讀取它。 否則,它會從 User-Agent 標頭推斷名稱。 |
session_metadata.agent_version |
STRING | 從 User-Agent 標頭推斷出的編碼代理回報版本。 搭配 coding_agent 使用它,以比較各個代理程式版本的使用情況。 當 Databricks-Custom-Coding-Agent 標頭設定 coding_agent時,未被填入。 |
session_metadata.surface |
STRING | 程式代理從此發送請求的用戶端介面,例如命令列介面、IDE 或桌面應用程式。 多個介面之間以空格分隔。 以逗號分隔 Databricks-Custom-Client-Surfaces 的請求標頭列出的介面排在前面,接著是從 User-Agent 標 originator 頭推斷出來的介面。 對於 MCP_SERVICE 列,介面僅來自 User-Agent 標頭。 |
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 的非串流、非嵌入回應的令牌使用情況。
-
任務專屬的 AI 功能使用量,例如
ai_parse_document和ai_extract,會計入 Unity Gateway 預算,但不會記錄在system.ai_gateway.usage表格中。 欲查看計費使用情況,請參閱 檢視 AI 功能工作負載的成本。