Metabase AI 用量审计（AI Usage Auditing）完整指南：从 Token 统计、来源与 Persona 分析到单会话全文审计

【免费下载链接】metabase The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart: 项目地址: https://gitcode.com/GitHub_Trending/me/metabase

Metabase 的 AI 用量审计（AI Usage Auditing）面向管理员提供一整套"人机对话"的可观测能力：从宏观的 Token 总量与消息量趋势，到逐条展开某一次 Metabot 对话的完整转写、生成的 SQL/MBQL 查询与用户反馈。本文以官方文档 docs/ai/usage-auditing.md 为主线，结合本仓库中的企业版后端实现、实例分析视图迁移 SQL 与 API 路由源码，系统讲解 Monitor（监控）中 AI auditing 的功能边界、数据口径、操作路径以及底层记录机制，读完你将掌握如何监控与审计全部 Metabot 交互，并能在 Usage Analytics 数据模型之上构建自定义审计报表。

说明：AI 用量审计属于付费（Enterprise）能力，文档以 plans-blockquote 标记；代码层面其实现位于 metabase-enterprise，Open Source 版中用量记录与限制检查均为空操作（见下文源码佐证）。

审计范围：哪些"人机交互"会被记录

管理员可以在 Monitor（监控）> AI auditing 下获得整个实例中人类与 Metabot（Metabase 内置 AI Agent）之间交互的全景视图，从 Token 总数这类高层统计，一直下钻到真实对话内容。被纳入统计的交互面包括：

• Metabase 内嵌的 Metabot 聊天侧边栏；
• Documents 中的 AI 内容生成对话；
• Slack 中的 Metabot 对话；
• 原生 SQL 编辑器中的内联 SQL 编辑（inline SQL editing）。

AI auditing 部分由两个子页面构成：

• Usage stats（用量统计）：覆盖所有 Metabot 活动的聚合图表；
• Conversations（对话）：可筛选的全部对话列表，每个对话都有独立的详情视图。

此外，支撑这些报表的底层数据来自 Usage Analytics 视图，因此你完全可以在这些数据模型之上自建 Question/仪表盘来做自定义审计报告。

后端是如何记录用量的：ai_usage_log 与 enterprise 注入点

在写操作路径之前，先理解数据从哪来。用量记录核心位于 src/metabase/metabot/usage.clj，其命名空间注释直接写明了边界：

Logging: log-ai-usage! records each LLM call to the ai_usage_log table (EE only). In OSS, no limits are enforced and no usage is logged.（每次 LLM 调用写入 ai_usage_log 表，仅企业版生效；开源版既不记录用量也不施加上限。）

每次 LLM 调用都会构造一张"用量映射"（usage map），其 Schema 定义了可被持久化的字段（见 usage-map-schema）：

字段	含义
source	来源标识（见下文 Sources）
model	调用的 LLM 模型
prompt-tokens / completion-tokens	输入 / 输出 Token 数
cache-creation-tokens / cache-read-tokens（可选）	缓存写入 / 读取消耗的 Token
user-id（可选）	发起者用户 ID
tenant-id（可选）	租户 ID（多租户启用时）
conversation-id（可选）	所属对话 ID
profile-id（可选）	应答所用的 Agent persona
request-id（可选）	请求追踪 ID
ai-proxied（可选）	是否经由 Metabase 托管代理转发

这些字段通过 defenterprise/defenterprise-schema 声明（src/metabase/metabot/usage.clj），在开源版中 log-ai-usage! 是无副作用的空实现；真正的落库逻辑在企业版命名空间 metabase-enterprise.metabot.usage（enterprise/backend/src/metabase_enterprise/metabot/usage.clj）。企业版实现还维护了两份"白名单"：

• known-sources：metabot_agent、slackbot、slack、oss-sql-gen、sql-gen、document_generate_content、example_question_generation_batch、exploration、contextual_interestingness、unknown、user-intent-classification 等；
• known-profile-ids：internal、embedding_next、explorations、nlq、sql、slackbot、transforms_codegen、document-generate-content。

写入未知的 source 会直接抛异常（Unknown ai_usage_log source ...），未知的 profile-id 则会被 valid-usage-profile-id 过滤为 nil——这保证了审计数据的口径是受控且可枚举的。更重要的是，源码注释指出：这些白名单必须与最新版分析视图 SQL 中的 CASE 分支保持同步，并由测试 metabase-enterprise.metabot.usage-test/known-sources-and-profiles-have-view-case-branches-test 强制校验（见 enterprise/backend/src/metabase_enterprise/metabot/usage.clj）。

底层数据表方面，对话、消息、反馈与 LLM 调用分别落在 metabot_conversation、metabot_message、metabot_feedback 与 ai_usage_log 四类表/模型中；审计 API 与查询实现见 enterprise/backend/src/metabase_enterprise/metabot_analytics/db.clj（每个端点都先执行 api/check-superuser，即仅超级管理员可访问）。对 ai_usage_log 还有配套的后台裁剪任务 ai-usage-trimmer（enterprise/backend/src/metabase_enterprise/metabot/task/ai_usage_trimmer.clj），它按设置 ai-usage-max-retention-days 每天删除过期行；当该保留天数未配置（0，即无限）时任务直接跳过清理。

Usage stats：聚合指标与图表

进入 Monitor > Usage stats 页面，可以看到所选时间范围内（默认最近 30 天）Metabot 活动的聚合情况。

筛选器（Filters）

筛选	说明
Date range（日期范围）	图表覆盖的时间窗口
User（用户）	只看某个用户（或 All users 全部用户）
Group（分组）	只看某个用户组（或 All groups 全部分组）
Tenant（租户）	只看某个租户；仅在启用多租户时才出现

指标（Metrics）

选择要计数的对象：

• Conversations（对话）：每个独立 Metabot 对话计一行，覆盖上文列出的全部入口（聊天侧边栏、Documents、Slack、内联 SQL）。注意：MCP 对话不计入。
• Tokens（令牌）：LLM 调用消耗的总 Token（输入 + 输出）。
• Messages（消息）：交换的每一条消息，既包括人类消息也包括 Metabot 消息。

每个指标下的一组图表

对上述每个指标，都会渲染同一组图表：

图表	含义
By time（按时间）	时间序列图；按所选日期范围自动以小时或天为桶，默认按天
By source（按来源）	请求来自 Metabase 的哪个位置（见下文 Sources）
By profile（按 persona）	由哪个 Metabot persona 应答（见下文 Profiles）
Users/Groups/IP addresses with most ...	按用户、分组、IP 地址取消耗最高的 Top-N 排名
Tenants with most ...	按租户的 Top-N，仅在启用租户时显示

其中 By day、Groups with most ...、Users with most ...、Tenants with most ... 支持点击下钻（drill through），会自动跳转到带对应筛选条件的 Conversations 列表。而 By source、By profile、IP addresses with most ... 图表是纯展示性的，不支持下钻。

Sources 与 Profiles：两套正交的维度

• Source（来源） 表示请求来自 Metabase 的哪个位置；
• Profile（persona） 表示哪个 Agent persona 应答了它。

两者常常对齐（例如 Slack 里开始的对话由 Slackbot profile 处理），但并不必然一致：一个从聊天侧边栏发起的对话，根据用户问的内容可能由 Internal、NLQ 或 SQL persona 处理。Conversations 管理页只显示 Profile；Source 出现在 Usage stats 图表与自定义报表所用的 Usage Analytics 模型中。

Sources（来源）

每个对话都会被打上一个来源标签。Usage stats 的 By source 图按人类可读的 source_name 分组；而 AI Usage Log 模型同时暴露 source_name 与原始 source ID（例如 metabot_agent、oss-sql-gen、document_generate_content）供自定义报表使用。无法被归类（没有 source 标签）的对话在图上显示为 (empty)。

来源名	来自哪里
Metabot	Metabase 内的 Metabot 聊天侧边栏
Documents	Documents 内部的内容生成
Suggested Prompts	后台的建议提示词生成
Slackbot	在 Slack 中开始的对话
SQL	原生编辑器中的内联 SQL 编辑
Unknown	无法被 Metabase 归类为特定入口的对话（区别于"没有 source"的对话，后者在图上显示为 (empty)）

源码佐证：source 原始 ID → 可读名称的映射真实存在于分析视图 SQL 中。以 H2/MySQL/PostgreSQL 三方言同步的 resources/migrations/instance_analytics_views/ai_usage_log/v5/postgres-ai_usage_log.sql 为例，其中 v_ai_usage_log 视图通过 CASE a.source 分支完成转换：metabot_agent/agent → Metabot、slack/slackbot → Slackbot、oss-sql-gen/sql-gen → SQL、document_generate_content → Documents、example_question_generation_batch → Suggested Prompts、unknown → Unknown；此外探索/研究类来源（exploration、contextual_interestingness）还会被归入一个额外的 Research 桶。由此可见文档中的来源表并非封闭集合，新增来源需要同步发布新版本的分析视图。

Profiles（persona 配置）

一个 profile 就是 Metabot 为一个对话所用的整套配置：用哪套系统提示词、允许调用哪些工具、能做什么事。Conversations 管理页、Usage stats 的 By profile 图以及 Metabot Conversations 模型均显示可读的 profile 名称；而 AI Usage Log 模型暴露的是原始 profile_id（如 internal、transforms_codegen、embedding_next）。

Profile	作用
Internal	聊天侧边栏的默认 Metabot：既能构建 query-builder 问题，也能写 SQL
NLQ	仅做自然语言查询，始终返回查询构建器结果，绝不返回 SQL
SQL	仅写 SQL，供内联 SQL 编辑及类似入口使用
Slackbot	Metabot in Slack 背后的 persona
Embedding	嵌入版 Metabase 内使用的 Metabot persona
Transforms codegen	生成 transform、SQL 或 Python
Documents	在 Documents 内生成内容

企业版源码中的 known-profile-ids 白名单（enterprise/backend/src/metabase_enterprise/metabot/usage.clj）与上表大体对应，还包含 explorations、document-generate-content 等额外标识，分别对应探索研究类与文档生成类场景的底层 profile_id。

Conversations：对话列表

进入 Monitor > Conversations，页面按从新到旧列出 Metabase 记录在案的每一个 Metabot 对话。

筛选器

Date range（日期范围）、User（用户）、Group（分组）、Tenant（租户） 与 Usage stats 的筛选器一致。

列

每一行展示：

列	含义
User	谁发起了这次对话
Profile	哪个 Metabot persona 应答
Date	对话开始时间
Messages	消息总数（双向都算）
Tokens	LLM 消耗的 Token 总数
Queries	对话期间 Metabot 生成的查询数（SQL 或 query-builder）
Searches	Metabot 发起的搜索工具调用次数
IP	请求来源的 IP 地址

可以按 Date、Messages、Tokens 排序，点击任意一行进入对话详情。

源码佐证：列表 API 位于 enterprise/backend/src/metabase_enterprise/metabot_analytics/db.clj。conversation-list-select 把 metabot_conversation 与 metabot_message、core_user 做左连接，实时聚合 message_count、total_tokens 等统计。有两个值得注意的实现细节：

• Token 口径：metabot_message 表只存 prompt + completion Token，因此列表中的 total_tokens 直接对消息求和；而 cache read Token 只记录在 ai_usage_log（每次 LLM 调用一行）中，所以列表用相关子查询（correlated subquery）单独对 ai_usage_log.cache_read_tokens 求和，避免一对多连接放大其他聚合值。
• 排序白名单：后端把排序键做成了 allow-list，支持 created_at、title、message_count、total_tokens、cache_read_tokens、user、profile_id、ip_address（其中 user 排序实际按 first_name + last_name 展开为多条 ORDER BY），前端 UI 暴露的主要是 Date/Messages/Tokens。

Conversation detail：单次对话的完整审计视图

点击某一行进入详情页，这里是对单次对话的完整审计：

• Header（头部）：开始日期、与 Metabot 对话的人、Metabot 所用的 profile、此人所在的用户组（含是否管理员）、以及适用的租户。头像旁的 ... 菜单可以跳到该用户的所有对话，或直接打开其账号详情。
• Stat tiles（统计块）：Messages（消息数）、Total tokens（总 Token）、Queries run（运行查询数）、Searches（搜索次数）。
• Feedback（反馈）（如果有）：点踩/点赞及评论，触发该反馈的 Agent 回复会一同展示。
• Conversation transcript（对话转写）：逐条消息的完整往返记录，工具调用（搜索、构造查询等）以行内方式呈现，点 View 可以打开模态框查看详情。
• Queries generated（生成的查询）：Metabot 在对话中写出的每一条 SQL 或 query builder（MBQL）查询，下方列出其引用的表。点 Visit 可在新标签页打开并亲自运行。Transform 代码生成类的查询以只读方式展示，不能从该处重新运行。

/inspect 快捷方式

如果你是管理员且在聊天中与 Metabot 对话，直接在聊天框输入 /inspect 即可从当前对话一键跳到它在 Usage auditing 中的详情页——这是从"聊天现场"到"审计记录"的最短路径，非常适合对话结束后立即核查。

自建自定义报表：背后支撑的三个 Usage Analytics 模型

AI auditing 页面由三个 Usage Analytics 数据模型支撑（参考 Usage analytics 参考文档）。它们属于 Usage analytics 集合，默认仅管理员可见，访问类型只有 View 与 No access 两种（详见 usage-analytics.md）：

AI Usage Log

每个 LLM 往返（round-trip）一行，含单次调用的 Token、来源、模型、profile 等。对应实例分析视图 v_ai_usage_log（迁移 SQL 见 resources/migrations/instance_analytics_views/ai_usage_log）。

主要列：Usage Log ID、Created At、Source、Source Name、Model、Profile ID、Prompt Tokens、Completion Tokens、Total Tokens、Conversation ID、User ID、User Qualified ID、User Display Name、Group Name、IP Address、Tenant ID、Request ID、Cache Creation Tokens、Cache Read Tokens。

Metabot Conversations

每个 Metabot 对话一行，含消息计数、Token 总计、所属用户/分组、来源与租户。对应视图 v_metabot_conversations。

主要列：Conversation ID、Created At、User ID、Title、User Display Name、Message Count、User Message Count、Assistant Message Count、Total Tokens、Prompt Tokens、Completion Tokens、Last Message At、Profile ID、Profile Name、Group Name、Source、Source Name、IP Address、Tenant ID、Tenant Name、Model。

Metabot Messages

每条（未删除的）Metabot 消息一行，含角色、profile、Token、用户及其所属对话。对应视图 v_metabot_messages。

主要列：Message ID、Conversation ID、Created At、Role、Profile ID、Total Tokens、User ID、Slack Msg ID、Channel ID。

口径细节：Conversations 管理页里的对话列表把 fork（复制）进来的消息也计入 message_count，描述的是"读者眼中所见到的完整线程"；而 v_metabot_conversations.new_message_count 作为用量指标口径，会排除从原对话拷贝过来的消息（该差异在 enterprise/backend/src/metabase_enterprise/metabot_analytics/db.clj 的注释中有明确说明）。

建议：把你自建的自定义 Question 保存在 Usage analytics 集合下的 Custom reports 子集合中，这样报表会自动继承父集合的权限（该子集合只读属性较宽松，管理员默认拥有 curate 权限）。注意 Custom reports 集合的元数据（名称、描述、徽章）会在 Metabase 重启时重置，但其中存放的 Question、模型、仪表盘会被保留。

什么不会被审计：MCP 调用

MCP 活动不包含在 AI auditing 中。MCP 请求不经过 Metabot 的对话管线，因此不会生成对话或 Token 记录。这一边界在代码中同样成立——MCP 模块有自己独立的用量记录与裁剪实现（见 src/metabase/mcp/usage.clj 与 metabase-enterprise/mcp/task/mcp_usage_trimmer.clj），与 Metabot 的 ai_usage_log 是两个互不相通的体系。

实用建议小结

• 先用宏观、再查微观：在 Usage stats 上按用户/分组/租户过滤并观察 Tokens、Messages、Conversations 的趋势图与 Top-N，快速定位异常消耗；需要确证时再用 By day / Users with most ... 下钻到具体对话。
• 善用 /inspect：管理后台巡检或处理用户投诉时，直接在聊天里敲 /inspect 拿到当前对话的完整审计页，包含转写、工具调用、生成查询与用户反馈，无需手动搜索。
• 区分 Source 与 Profile：做报表时若关心"入口渠道"，按 Source/Source Name 分组；若关心"Metabot 的行为模式"，按 Profile/Profile ID 分组。
• 用原始模型自建报表：Usage analytics 集合只读，但复制到 Custom reports 子集合后可自由修改；三张模型（AI Usage Log / Metabot Conversations / Metabot Messages）从不同粒度覆盖同一批数据，根据"每次调用 / 每个对话 / 每条消息"选择合适粒度即可。
• 注意保留与裁剪：审计明细在库中长期累积，企业版通过 ai-usage-trimmer 后台任务按 ai-usage-max-retention-days 每日裁剪，未配置时无限保留；请在合规要求与存储成本之间为该设置选择合适的值。

延伸阅读

• AI usage controls（AI 用量限制与开关）
• AI settings（AI 设置）
• Metabot（产品内 AI Agent 总览）
• Metabot in Slack
• Usage analytics（用量分析集合）
• 权限概览

【免费下载链接】metabase The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart: 项目地址: https://gitcode.com/GitHub_Trending/me/metabase