查Token统计
什么时候用
你需要深入分析Token使用情况、了解用量趋势、做成本优化时，查Token统计。Token统计页面提供多维度分析：
- 按时间看Token消耗趋势
- 按用户看用量排行
- 按模型看消耗分布
- 分析用户画像和调用习惯
- 识别异常高消耗会话
注意：Token统计功能依赖「Token Counter」插件。如果插件未启用，页面仍可访问，但不会有数据。
你需要准备
- 管理员账号（查看用户排行、用户画像需要）
- 已启用「Token Counter」插件（必备，否则无数据）
- 已产生过调用数据（否则图表为空）
操作步骤
第 1 步：进入Token统计
左侧菜单 -> 日志和统计 -> Token统计。
第 2 步：选择时间范围
页面顶部有一个日期范围选择器，你可以：
- 手动选择开始和结束日期
- 点击快捷选项：最近7天、最近30天、最近90天、本月
选择后页面会自动刷新数据。
第 3 步：查看概览卡片
顶部一排卡片展示核心指标：
| 指标 | 说明 |
|---|---|
| 总Token | 时间范围内消耗的Token总数 |
| Prompt Token | 输入部分消耗的Token |
| Completion Token | 输出部分消耗的Token |
| 人均Token | 按活跃用户平均的Token消耗 |
| 每请求Token | 平均每次API调用消耗的Token |
这些数字帮你快速把握整体用量。
第 4 步：查看Token使用趋势（默认展开）
「Token使用趋势」图表默认展开，展示三条线：
- 总Token（实线）
- Prompt Token（虚线）
- Completion Token（点线）
你可以直观地看到用量随时间的变化，识别峰谷和突增。
第 5 步：查看用户Token排行（仅管理员可见，默认展开）
作为管理员，你能看到用户用量排行。如果用户数较多，图表会自动切换为横向柱状图，否则是纵向。
排行帮你识别高消耗用户，做针对性优化或沟通。
第 6 步：查看用户画像分析（仅管理员可见，默认展开）
「用户画像分析」是一个散点图，横轴是Prompt Token，纵轴是Completion Token，点的大小代表调用次数。
这个图表帮你发现：
- 哪些用户主要在做长输入（如文档分析）
- 哪些用户主要在做长输出（如文案生成）
- 哪些用户调用频率很高但单次用量小
第 7 步：展开更多分析模块
以下模块默认收起，点击标题可以展开：
模型消耗分析
包含两个图表：
- 饼图：各模型的Token消耗占比
- 趋势图：各模型的Token消耗随时间的变化
如果模型数量很多，占比较小的会自动合并为「其他」。
时段热力分布
热力图展示一周内每小时的调用活跃情况。颜色越深代表该时段消耗越多Token。
这个图表帮你：
- 了解用户使用习惯
- 合理规划模型配额和扩容
- 排查高峰时段的性能问题
效率分析
展示三个指标：
- 平均Token / 会话
- 平均Token / 消息
- 长会话Top 10列表
长会话列表会展示异常高消耗的会话，你可以重点关注这些会话是否合理，是否存在提示词优化空间。
怎么验证成功了
- 页面能正常访问，即使没有数据也会显示「暂无数据」提示
- 选择不同的时间范围，数据会相应刷新
- 作为管理员，你能看到「用户Token排行」和「用户画像分析」模块
- 作为普通用户，你看不到上述两个管理员专属模块
- 展开收起模块时，动画流畅，内容正确显示
常见问题
1. 为什么页面所有图表都是「暂无数据」？
有两种可能：
- 你没有启用「Token Counter」插件，请先去插件管理中启用
- 你启用了插件，但所选时间范围内没有产生过调用
2. 「Token Counter」插件在哪里启用？
左侧菜单 -> 系统设置 -> 插件管理。找到「Token Counter」，点击启用。
3. 为什么我看不到用户排行和用户画像？
你不是管理员。这两个模块只有管理员角色的用户才能看到。
4. 模型饼图里的「其他」是什么？
当模型数量较多时，占比较小的模型会自动合并为「其他」，避免图表太拥挤。
5. 我能导出这些统计数据吗？
当前版本不支持直接导出。你可以截图保存，或者通过 API 获取原始数据，详见 API 集成指南。
深入
核心概念：会话、消息、调用记录的关系
一次调用通常会产生三类记录：
- ChatSession（会话）：代表一个连续对话，按租户、用户、客户端会话 ID 做唯一约束
- ChatMessage（消息）：保存用户输入、模型输出、工具消息，以及脱敏/哈希字段
- ai_api_call（调用记录）：每次 API 调用的主记录，包含状态、错误类型、Token、成本、延迟等
审计模式影响展示
消息内容展示受租户审计模式控制：
- no_mask：不脱敏，按原文展示
- mask_on_display：存储原文，展示时脱敏
- mask_on_save：写入时即保存脱敏内容
在日志页面看到的内容可能是脱敏后内容，不一定是原始内容。
安全事件
安全事件记录租户内的敏感操作和内容安全事件，例如：
- 命中敏感内容检测
- 命中禁用内容策略
- 用户角色变更
- API Key 创建/删除
- Agent 克隆
- 技能创建/更新
- 平台管理员查看其他用户数据
- 技能跨租户代部署
权限边界
| 操作 | 谁可以 |
|---|---|
| 查看本租户会话列表 | 租户 admin |
| 查看本租户会话消息 | 租户 admin |
| 查看调用统计 | 租户 admin |
| 查看安全事件 | 租户 admin |
| 查看其他租户日志 | 不允许，平台管理员能力按具体接口控制 |
| 查看 MCP 调用日志 | 租户 admin（仅本租户） |
常见坑
看到的是脱敏内容，不一定是原文 日志页面展示的内容受审计模式影响。如果设置为 mask_on_display 或 mask_on_save，管理员看到的可能是脱敏后的内容。
调用失败不一定有 assistant 消息 请求在安全检查、模型鉴权或限流阶段被拒绝时，可能只会有调用记录，没有完整 assistant 回复。
会话去重依赖客户端会话 ID 同一个（租户 ID、用户 ID、来源客户端、来源会话 ID）会复用同一个会话。如果客户端没有传稳定的来源会话 ID，会话列表可能看起来很分散。
Token 趋势只统计成功调用 统计页面通常基于调用记录聚合。被拒绝的请求可能没有 Token 用量，因此不会显著影响 Token 图表，但会出现在调用状态和安全事件中。
MCP 工具失败不要只看聊天消息 MCP 调用失败需要同时看调用日志，聊天消息中可能只有工具失败摘要。
排错速查
| 症状 | 可能原因 | 排查路径 |
|---|---|---|
| 用户说调用失败 | 模型鉴权、限流、上游错误 | 看调用记录状态和错误类型 |
| 返回内容策略违规 | 命中禁用模式 | 看安全事件类型=policy_violation |
| 内容被脱敏 | 租户审计模式开启 | 检查审计模式、脱敏规则 |
| 客户端被白名单拦截 | 允许的 API 客户端不包含当前客户端 | 看客户端访问日志的 user_agent 和白名单快照 |
| MCP 工具失败 | 工具被拒、上游超时或限流 | 看 MCP 调用日志状态、拒绝原因 |
| 统计数和预期不一致 | 时间范围、失败调用、模型组路由 | 调整参数，查看路由轨迹 |