指标监控与分析报表
功能概述
指标监控与分析报表(Metrics & Analytical Reports,控制台入口为 智能体运维 → 指标 及 报表)是 Agentbase(v2.10.0)面向技术负责人、AI 架构师与运维团队提供的生产运营度量与 ROI 决策看板。在大模型应用规模化上线后,团队需要实时掌握系统的吞吐表现与财务健康度,回答三个核心问题:“花了多少 Token 与成本?”、“首字延迟(TTFT)与端到端延迟(P50/P95/P99)快不快?” 以及 “各智能体的回答质量与 Bad Case 归因分布如何?”
在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 **企业智能客服与知识中台**(enterprise-ai-hub-210)中,系统基于已采集的 Trace、Observation 与 Score 实时派生全维指标与三大专题分析报表(/v1/observability/reports/{overview|agents|quality}):
- 零额外采集开销的轨迹派生指标(Metrics):涵盖调用量、Token 消耗(区分 Prompt / Completion / Cached / Reasoning)、TTFT 与端到端延迟分位值(P50 / P95 / P99)、按模型(
qwen-plus、qwen-turbo、text-embedding-v3、qwen-vl-max)拆分的成本估算、错误率监控,并支持 **memoryOnly一键过滤**仅统计 Memory 链路指标; - **三大高阶分析报表(Reports,
v2.10.0):通过 Overview(全局总览)、Agents(智能体排行与 ROI) 与 Quality(质量分档与 Bad Case 归因)** 三个页签,提供近 24 小时 / 7 天 / 30 天及自定义窗口(≤30 天)的快照与上一周期环比(Delta),支持按wasteReason(Token 浪费原因)、cache.status(缓存命中)和badCaseCategory(坏例归因)深度剖析优化空间。
核心概念与架构
Agentbase 的指标与报表引擎直接构建于底层分析型轨迹与评分存储之上,采用服务端 Bundle 合并查询与二阶段 Top-N 时序聚合架构,单页仅需一次 HTTP 请求即可完成多维指标渲染。
flowchart TB
subgraph TelemetrySource["1. 轨迹与评分数据源 (OceanBase / Langfuse)"]
TracesObs["Traces & Observations\n延迟 / TTFT / 模型 Token 用量 / 估算成本 / 状态"]
MetadataTags["写入侧显式元数据打标 (Observation Metadata)\n• wasteReason (5类浪费原因)\n• badCaseCategory (7类坏例归因)\n• cache.status (hit / partial / miss)"]
ScoresData["Scores (自动评估与人工标注)\n归一化分值 normalizedValue (0~1) & 五档质量分布"]
end
subgraph AggregationEngine["2. 服务端派生与 Bundle 聚合引擎"]
MetricsEngine["Metrics 实时派生看板 (/observability/metrics)\n支持时间窗口、模型、环境与 memoryOnly=true 过滤"]
ReportsBundle["Reports 服务端 Bundle 编排器\nPOST /v1/observability/reports/{overview|agents|quality}\n同维度多 Metric 合并 SQL + Top-N 二阶段时序聚合\n等长上一周期环比 (Delta) & 10,000 行有界样本保护"]
end
subgraph Views["3. 控制台消费视图与闭环下钻"]
MetricsUI["指标分析页 (Metrics)\nP50/P95/P99 延迟、TTFT、Token、成本与评分趋势"]
OverviewTab["Report: Overview 页签\n9张核心 KPI 卡 + 流量趋势 + Token 浪费分解 + 诊断结论"]
AgentsTab["Report: Agents (Trace) 页签\nAgent 排行 (≤20) + Prompt/Completion ROI 三档 + 模型成本"]
QualityTab["Report: Quality 页签\nTop-2 评估器趋势 + 五档分布 + Bad Case 归因 + 低分 Trace 下钻"]
end
TracesObs --> MetricsEngine
ScoresData --> MetricsEngine
TracesObs --> ReportsBundle
MetadataTags --> ReportsBundle
ScoresData --> ReportsBundle
MetricsEngine --> MetricsUI
ReportsBundle --> OverviewTab
ReportsBundle --> AgentsTab
ReportsBundle --> QualityTab核心度量指标与计算口径表
| 指标分类 | 指标名称 | 计算口径与统计规则 |
|---|---|---|
| 吞吐与活跃度 | Trace 总量 / Observation 总量 / 活跃用户数 | 选定时间窗口内去重统计的端到端请求数、内部节点数及非空 userId(如 user_zhangwei_001)去重计数。 |
| Token 消耗 | Input (Prompt) / Output (Completion) / Total Tokens | 汇总所有 GENERATION 与 EMBEDDING 节点的真实供应商上报 Token。cached(缓存命中 Token)与 reasoning(思维链 Token)映射为互斥子桶,不重复累加进总计费 Token;缓存直接短路避免的调用记为 avoided call(新增消耗为 0)。 |
| 延迟分位值 | 端到端延迟与 TTFT(P50 / P95 / P99) | - 端到端延迟:Trace 或 Generation 从 startTime 到 endTime 的总耗时在窗口内的第 50、95、99 百分位值;<br>- 首字延迟(TTFT, Time To First Token):流式大模型调用从发起请求到收到首个生成 Token(completionStartTime)的耗时分位值。 |
| 成本估算 | 模型总成本估算 / 单会话成本(Cost per Session) | 基于各 GENERATION 节点匹配的模型单价表(如 qwen-plus、qwen-vl-max)计算的估算金额(仅供研发运营方向性参考,实际财务结算以平台 限额与计量账单 为准)。 |
| 错误率与质量 | 错误率 / 综合质量分 / 评测覆盖率 | - 错误率:状态为 ERROR 的 Trace/Observation 占比(网关层严格区分 5xx 服务端故障、429 限流与普通 4xx 业务拒绝,不将普通 4xx 混入服务故障率);<br>- 综合质量分:窗口内所有可归一化数值评分(normalizedValue)的算术均值(保留两位小数);<br>- 评测覆盖率:已关联至少一条评估 Score 的 Trace 占总 Trace 数的百分比。 |
角色、入口与关联关系
控制台入口与 REST API 权限矩阵
- 指标监控页(Metrics):位于左侧导航栏 智能体运维(Observability / AgentOps) → 指标(Metrics)(路由:
/console/project-{region}-enterprise-ai-hub-210/observability/metrics)。 - 分析报表页(Reports):侧栏报表入口当前默认隐藏,页面与路由完整保留,具备权限的项目成员可通过直达 URL 访问三个页签:
/console/project-{region}-enterprise-ai-hub-210/observability/reports/overview/console/project-{region}-enterprise-ai-hub-210/observability/reports/agents/console/project-{region}-enterprise-ai-hub-210/observability/reports/quality
| 接口 / 页面 | HTTP 方法与路径 | 所需 API Key Scopes(用户会话/JWT 角色默认包含) |
|---|---|---|
| Metrics 指标查询 | /v1/observability/metrics(及控制台聚合查询) | observability.metrics.read |
| Overview 全局总览报表 | POST /v1/observability/reports/overview | observability.metrics.read + observability.traces.read + observability.scores.read |
| Agents 智能体排行报表 | POST /v1/observability/reports/agents | 上述三项 + **observability.users.read + observability.sessions.read** |
| Quality 质量与归因报表 | POST /v1/observability/reports/quality | observability.metrics.read + observability.traces.read + observability.scores.read |
功能详解与操作指南
1. 查看指标监控页(Metrics)与 memoryOnly 专属过滤
- 登录 Agentbase 控制台,进入项目
企业智能客服与知识中台(enterprise-ai-hub-210),单击左侧 智能体运维 → 指标(Metrics)。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
- 关键筛选与分析操作:
- 时间范围与环境筛选:选择统计时间段与目标环境(如
production); - **
memoryOnly专属过滤(仅看 Memory 链路):开启页面上的 仅统计 Memory(memoryOnly: true)** 过滤项,看板将只聚合带有 Memory 链路标识的轨迹数据,帮助架构师单独核算 Memory 事实抽取、画像生成、重排与经验蒸馏所消耗的 Token、P95 延迟及 Memory 专项评估得分; - 按模型拆分用量与成本:在模型明细表中对比
qwen-plus、qwen-turbo、text-embedding-v3、qwen3.7-text-rerank与qwen-vl-max的调用次数、Prompt/Completion Token 占比与估算成本。
- 时间范围与环境筛选:选择统计时间段与目标环境(如
2. 使用三大分析报表(/v1/observability/reports)洞察全局与 ROI
访问报表页面或调用 POST /v1/observability/reports/{overview|agents|quality} 时,三个页签共享统一的时间范围契约:
- **预设时间窗口(
range)**:支持"24h"(近 24 小时)、"7d"(近 7 天,默认)、"30d"(近 30 天); - **自定义时间窗口(
from+to):支持成对传入 ISO-8601 起止时间,最大跨度不得超过 30 个自然日(30 × 24h)**,且必须满足from < to(非法窗口直接返回 400 参数错误,不静默降级为空数据); - 自动等长环比(Delta):系统自动计算紧邻的前一个等长周期(
previousFrom~previousTo)的环比涨跌;跨度≤ 24h时趋势图按小时(hour)聚合,否则按天(day)聚合。
(1)Overview(全局总览页签)
- 顶部 9 张核心 KPI 卡(含环比 Delta):
Traces 总数、活跃用户数、Tokens 总量、成本(估算)、P95 延迟、错误率、综合质量分、评测覆盖率、单会话成本。 - 趋势与分解面板:
- 流量趋势:按调用量排名前五的 Agent 分组展示 Trace 数量时序折线;
- 延迟与质量双轴趋势:左轴展示 P95 延迟(ms),右轴对照展示综合质量分(
0~1); - **Token 浪费分解(按
wasteReason)、Top 5 Agents / Top 5 Models、归一化五档质量分布(Excellent / Good / Average / Poor / Very Poor)**; - 自然语言诊断结论:规则引擎根据阈值自动生成可读诊断提示(如指出本周重试浪费占比或 P95 延迟超标情况)。
(2)Agents(智能体排行与 ROI 页签,Console 页签展示为 Trace)
- Agent 排行表(Top 20):列出调用量最高的 20 个 Agent,展示调用量、P95 延迟、平均质量分、低分占比、健康状态徽标(
正常/预警/异常)及诊断提示(如Prompt 偏重、较慢)。单击 Agent 名称可直接带过滤条件跳转至 Trace 列表。 - Prompt / Completion Token ROI 三档分析:按输入 Prompt Token 与输出 Completion Token 的比值,将 Agent 自动划分为 高效(High ROI)、均衡(Balanced)、低效(Low ROI) 三档,快速识别系统提示词或检索上下文注入过重但有效输出极短的 Agent。
- 步骤(工具调用)与模型成本明细、Top 活跃用户 / 会话 / 最近 Trace 列表(最近 Trace 列表实时附带单条 Trace 的真实
latencyMs与observationCount)。
(3)Quality(质量趋势与 Bad Case 归因页签)
- 质量 KPI 与 Top-2 评估器趋势:展示综合质量分、命中次数最多的前两个评估器(Top 2 Evaluators)的平均分趋势及 P95 延迟。
- **Bad Case 归因面板(按
badCaseCategory)、低分 Trace 列表(落在poor/very-poor档,支持一键下钻详情) 以及 评估器覆盖率对比**。 - 10,000 行有界样本保护机制: 为保障大流量项目下的查询响应速度,Quality 低分列表与 Agents 最近 Trace 列表在同一窗口内最多读取按时间倒序的最新 10,000 行记录。当窗口内候选评分超过 10,000 条时,接口返回
lowScoresLimited: true、insightsLimited: true、facetsLimited: true(Overview 对应返回scoreInsightsLimited: true),控制台会自动显示 “结果为有界样本” 提示并隐藏样本当前均分与全窗口上期均分的跨口径环比,引导用户缩小时间窗口查看完整全量明细。
3. 写入侧显式元数据打标规范(wasteReason、badCaseCategory、cache)
报表中的 Token 浪费分解、缓存命中率 与 Bad Case 归因 面板严格基于写入侧在 Observation.metadata 中显式打标的字段聚合(未打标的正常数据不会混入“未知浪费”桶):
| 元数据字段路径 | 允许的标准枚举值 | 枚举语义与改进方向指导 |
|---|---|---|
metadata.wasteReason | retry、truncation、cache_miss_repeat、context_overflow、user_abort | 分别标识因报错重试、输出长度截断重跑、相同前缀缓存未命中、上下文超限丢弃及用户中途取消导致的无效 Token 消耗。缺失该字段代表正常有效消耗。 |
metadata.badCaseCategory | grounding_missing、hallucination、instruction_violation、tool_failure、query_understanding、safety_refusal、latency_timeout | 七个互斥的坏例归因桶:如 grounding_missing 指向优化知识库召回,tool_failure 指向修复工具 Schema 或下游接口。 |
metadata.cache.status | hit、partial、miss | 三态缓存状态(如匹配 AI 网关语义缓存策略 cp-semantic-cache 或 Prefix Cache):hit(完全命中)、partial(系统 Prompt 命中但用户轮次未命中)、miss(未命中)。缓存命中率按已打标 Observation 的计数占比统计。 |
4. 调用分析报表 Bundle API 示例
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"
# 1. 查询近 7 天 (7d) 的 Overview 全局总览报表
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/reports/overview" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"range": "7d"
}' | jq .
# 2. 使用自定义时间窗口 (from/to, 跨度 <= 30 天) 查询 Quality 质量与 Bad Case 归因报表
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/reports/quality" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"from": "2026-10-01T00:00:00.000Z",
"to": "2026-10-22T23:59:59.999Z"
}' | jq .查询指标
- 在项目侧栏 Observability / AgentOps → Metrics 打开指标页。
- 选择数据视图、指标、聚合方式、分组维度、时间粒度和起止时间,再点击 Apply。默认查询最近 24 小时,时间粒度默认为 Hour;可选粒度为 Minute、Hour、Day、Week。
- 查看汇总值、时间序列图和维度拆分表。选择分组后,可比较不同维度的变化;需要查看某条 Trace 的输入输出或具体阶段时,回到轨迹检查明细。
可选指标和分组取决于数据视图:
| 数据视图 | 指标 | 可选分组 |
|---|---|---|
| Traces | 数量、延迟、Token 用量、成本 | 不分组、Trace 名称、Environment |
| Observations | 数量、延迟、Token 用量、成本 | 不分组、模型、Trace 名称、Environment、阶段、用途、结果、用量完整性 |
| Scores | 数量、评分 | 不分组、评分名称、Trace 名称、Environment |
聚合选项会按所选指标调整:数量使用 Count;延迟支持 Count、Average、P50、P95;Token 用量和成本支持 Sum、Average;评分支持 Count、Average。请先选数据视图和指标,再选择页面提供的聚合选项。
Memory only 仅在 Observations 视图中提供,用于只统计 Memory 链路产生的 Observation;Traces 与 Scores 视图不会显示此过滤项。它不表示评分也已按 Memory 过滤。
没有指标数据时
若图表显示 No metric data,先检查起止时间是否覆盖数据产生时段,再确认数据视图、指标和分组是否匹配;使用 Memory only 时,也确认查询目标是 Observations。更改条件后重新点击 Apply。页面的刷新按钮会重新请求当前指标查询。
若调整条件后仍无数据,核对当前项目是否已写入对应类型的 Trace、Observation 或 Score,并检查 Trace 的时间和用量记录。空结果只代表当前查询未返回数据,不能据此得出“无调用”“零成本”或“质量为零”的结论。
常见问题与排障
1. 为什么在报表(Reports)页面中,总调用量与 Token 都有数据,但“Token 浪费”或“Bad Case 归因”面板显示为空?
- 原因分析:这并非报表查询故障。
Token 浪费、缓存命中与Bad Case 归因依赖写入侧在Observation.metadata中显式写入wasteReason、cache.status和badCaseCategory字段。如果当前项目的上报链路尚未注入这三个元数据标签,系统不会把未打标的正常调用强行归入“未分类浪费”,而是展示空面板并提示尚未建立打标覆盖。 - 解决措施:参考上文“写入侧显式元数据打标规范”,在应用或网关上报
generation-create事件时按规范补充metadata.wasteReason、metadata.cache与metadata.badCaseCategory字段,新写入的数据即可实时进入分解面板。
2. 为什么自定义报表时间范围时点击“应用”报错或被禁用?
- 原因分析:分析报表(Reports)对自定义时间窗口(
from/to)实施三层一致校验(Console 前端、PHP 网关与底层分析引擎):① 自定义时间跨度**严禁超过 30 个自然日(30 × 24h)**;② 开始时间from必须严格早于结束时间to(不允许起止相等或倒序)。 - 解决措施:请将单次查询的自定义起止时间跨度控制在 30 天以内;若需对比更早的历史周期,可分多个 30 天窗口分别拉取快照。
3. Metrics 与 Reports 中显示的模型成本(Cost)与组织账单中的实际扣费完全一致吗?
- 原因分析:Metrics 和 Reports 中的成本数值是基于 Trace 中
GENERATION节点记录的模型名称和 Token 数量乘以参考单价得出的实时估算值,旨在帮助研发团队直观对比不同 Agent 或模型选型的相对成本效率(ROI)。而实际计费还会受到上游供应商阶梯折扣、包月资源包抵扣或未采样 Trace 的影响。 - 解决措施:请将可观测看板中的成本作为工程优化与 ROI 评估参考;财务对账与配额核对请前往项目的 限额、配额与用量计量 页面查看权威计量聚合。