本页介绍如何使用使用情况跟踪系统表监视 Unity AI 网关 服务的使用情况。
使用情况跟踪表会自动捕获模型服务的请求和响应详细信息，记录令牌使用情况和延迟等基本指标。 可以使用此表中的数据来监视用户、跟踪成本，并深入了解模型服务性能和使用情况。
使用情况跟踪还会记录 ai_query 对 Databricks 提供的模型服务的请求。
帐户和工作区管理员可以在治理中心的 AI 页面上查看 AI 使用情况的合并概述。
Requirements
- Unity AI 网关支持的区域中的Azure Databricks工作区。
- 你的工作区已启用 Unity Catalog。 请参阅为工作区启用 Unity Catalog。
Pricing
使用跟踪是 Unity AI Gateway 的计费功能。 Azure Databricks 会根据它记录到system.ai_gateway.usage桌面的使用量收费。 参见 Unity AI Gateway定价。
查询使用情况表
Unity AI 网关将使用情况数据记录到 system.ai_gateway.usage 系统表。 可以在 UI 中查看表，也可以从 Databricks SQL 或笔记本查询表。
注意
默认情况下，需要同时具有帐户管理员和元存储管理员角色才能查看或查询 system.ai_gateway.usage 表。 管理员可以 管理系统表的访问权限 ，以控制用户、组和服务主体的权限。
若要查看 UI 中的表，请单击模型服务页上的使用情况跟踪表链接，在目录资源管理器中打开该表。
要从 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 网关页上的独立 “创建仪表板”、“ 查看仪表板”和 “更新 ”按钮。
创建内置使用仪表盘
帐户管理员可以创建内置的 Unity AI 网关使用情况仪表板，以监视使用情况、跟踪成本，并深入了解模型服务性能和使用情况。 在 Unity AI Gateway 页面中，点击右上角的治理，然后点击创建使用情况仪表板。 将自动选择运行仪表板查询的仓库。
注意
仪表板创建仅限于帐户管理员，因为它需要 SELECT 对 system.ai_gateway.usage 表拥有权限。 仪表板的数据受 usage 表的保留策略约束。 请参阅可以使用哪些系统表？。
当内置使用情况仪表板的较新版本可用时，帐户管理员可以单击 Unity AI 网关页上“治理”下拉列表中的仪表板版本行上的“更新”。
可以使用以下仪表板配置选项来管理仪表板：
- 范围：选择是将仪表板限定为帐户还是工作区。
- 权限：选择查询是使用仪表板所有者的权限还是每个查看器的权限运行。 请参阅什么是共享数据权限？
- 自动更新：启用此选项时，只要有较新版本可用，仪表板就会自动更新，帐户管理员访问 Unity AI 网关页面。
当仪表板更新到版本 0.3 或更高版本时，系统会自动创建一个计划，以每隔 6 小时刷新仪表板。 如果需要，可以在 Lakeview 仪表板中禁用此计划。 请参阅 “创建计划”。
查看使用情况仪表板
若要查看仪表板，请单击 Unity AI 网关页面右上角的 “治理 ”，然后单击“ 使用情况仪表板”。 仪表板将在新选项卡中打开。内置仪表板可全面了解 Unity AI 网关模型服务使用情况、性能和成本。 它包括多个页面跟踪请求、令牌消耗、延迟指标、错误率、成本细分、外部 MCP 服务器流量和编码代理活动。
默认情况下，仪表板提供跨工作区分析。 所有仪表板页面都可以按日期范围和工作区 ID 进行筛选。
- “概述”选项卡：显示高级使用情况指标，包括每日请求量、随时间推移的令牌使用趋势、按令牌消耗量排名靠前的用户数和唯一用户总数。 使用此选项卡获取整体 Unity AI 网关活动的快速快照，并确定最活跃的用户和模型。
- 性能选项卡：跟踪关键性能指标，包括延迟百分位数（P50、P90、P95、P99）、第一字节、错误率和 HTTP 状态代码分发的时间。 使用此选项卡监视模型服务运行状况并确定性能瓶颈或可靠性问题。
- 使用情况选项卡：按模型服务、工作区和请求者显示详细的消耗细分。 此选项卡显示令牌使用模式、请求分发和缓存命中率。
- “成本可观测性”选项卡：按模型服务、目标模型、用户、服务标记和请求标记显示成本细分。 此选项卡还包括外部模型的估计成本。 参见 分析Unity人工智能网关费用。
- 外部 MCP 服务器选项卡：显示外部 MCP 服务器流量的请求量、错误率、用户和连接以及每日使用趋势。
- 编码代理选项卡：跟踪集成编码代理的活动，包括 Cursor、Claude Code、Gemini CLI 和 Codex CLI。 此选项卡显示用于监视开发人员工具使用情况的指标，例如活动天数、编码会话、提交和代码行。 有关更多详细信息，请参阅 编码代理仪表板 。
使用情况表架构
该 system.ai_gateway.usage 表具有以下架构：
| 列名称 | 类型 | 说明 | 示例 |
|---|---|---|---|
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 AI 网关模型服务的名称。 | databricks-gpt-5-2 |
endpoint_tags |
MAP | 创建或更新时在模型服务上配置的标记。 它们适用于模型服务的所有请求，并且可用于按团队、成本中心或项目对服务进行分类。 | {"team": "engineering"} |
endpoint_metadata |
STRUCT | 模型服务元数据，包括creator、creation_time、last_updated_timedestinations和inference_tablefallbacks。 |
{"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 | API 调用的类型（例如聊天、完成或嵌入）。 | mlflow/v1/chat/completions |
request_tags |
MAP | 使用 Databricks-Ai-Gateway-Request-Tags HTTP 标头随单个请求一起发送的用户提供的标记。 使用请求标记将使用情况归因于特定项目、团队、环境或最终用户。 请参阅 有关使用情况跟踪的标记请求 和 用于跟踪使用情况的标记请求。 |
{"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、destination、destination_id、status_code、error_code、latency_ms、start_time和end_time。 |
{"attempts": [{"priority": "1", ...}]} |
为请求添加标签以进行使用情况跟踪
请求标记是调用方附加到单个请求的自定义键值对。 使用请求标记按项目、团队、环境、最终用户或任何其他与组织相关的维度来属性使用。 请求标记记录到 system.ai_gateway.usage 表中，可用于筛选、聚合和分析使用情况数据。
要标记单个请求，请包含 Databricks-Ai-Gateway-Request-Tags HTTP 标头，其中包含一个将字符串键映射到字符串值的 JSON 对象。 请求标记会记录到使用情况表和request_tags中的 列。
有关如何使用 REST API、OpenAI SDK 和 Anthropic SDK 设置请求标记的示例，请参阅 Tag 请求以跟踪使用情况。
例如，可以使用请求标记按项目聚合使用情况：
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 网关不会跟踪大小超过 1 MiB 的非流式、非嵌入响应的令牌使用情况。