Docs
文档目录

指标监控与分析报表

功能概述

指标监控与分析报表(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}):


核心概念与架构

Agentbase 的指标与报表引擎直接构建于底层分析型轨迹与评分存储之上,采用服务端 Bundle 合并查询与二阶段 Top-N 时序聚合架构,单页仅需一次 HTTP 请求即可完成多维指标渲染。

指标监控与分析报表:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心度量指标与计算口径表

指标分类指标名称计算口径与统计规则
吞吐与活跃度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 百分位值;
- 首字延迟(TTFT, Time To First Token):流式大模型调用从发起请求到收到首个生成 Token(completionStartTime)的耗时分位值。
成本估算模型总成本估算 / 单会话成本(Cost per Session)基于各 GENERATION 节点匹配的模型单价表(如 qwen-plus、qwen-vl-max)计算的估算金额(仅供研发运营方向性参考,实际财务结算以平台 限额与计量账单 为准)。
错误率与质量错误率 / 综合质量分 / 评测覆盖率- 错误率:状态为 ERROR 的 Trace/Observation 占比(网关层严格区分 5xx 服务端故障、429 限流与普通 4xx 业务拒绝,不将普通 4xx 混入服务故障率);
- 综合质量分:窗口内所有可归一化数值评分(normalizedValue)的算术均值(保留两位小数);
- 评测覆盖率:已关联至少一条评估 Score 的 Trace 占总 Trace 数的百分比。

角色、入口与关联关系

控制台入口与 REST API 权限矩阵

  1. 指标监控页(Metrics):位于左侧导航栏 智能体运维(Observability / AgentOps) → 指标(Metrics)(路由:/console/project-{region}-enterprise-ai-hub-210/observability/metrics)。

  2. 分析报表页(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/overviewobservability.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/qualityobservability.metrics.read + observability.traces.read + observability.scores.read

功能详解与操作指南

1. 查看指标监控页(Metrics)与 memoryOnly 专属过滤

  1. 登录 Agentbase 控制台,进入项目 企业智能客服与知识中台(enterprise-ai-hub-210),单击左侧 智能体运维 → 指标(Metrics)。

指标详情页(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

  1. 关键筛选与分析操作:

    • 时间范围与环境筛选:选择统计时间段与目标环境(如 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} 时,三个页签共享统一的时间范围契约:

(1)Overview(全局总览页签)

(2)Agents(智能体排行与 ROI 页签,Console 页签展示为 Trace)

(3)Quality(质量趋势与 Bad Case 归因页签)

3. 写入侧显式元数据打标规范(wasteReason、badCaseCategory、cache)

报表中的 Token 浪费分解、缓存命中率 与 Bad Case 归因 面板严格基于写入侧在 Observation.metadata 中显式打标的字段聚合(未打标的正常数据不会混入“未知浪费”桶):

元数据字段路径允许的标准枚举值枚举语义与改进方向指导
metadata.wasteReasonretry、truncation、cache_miss_repeat、context_overflow、user_abort分别标识因报错重试、输出长度截断重跑、相同前缀缓存未命中、上下文超限丢弃及用户中途取消导致的无效 Token 消耗。缺失该字段代表正常有效消耗。
metadata.badCaseCategorygrounding_missing、hallucination、instruction_violation、tool_failure、query_understanding、safety_refusal、latency_timeout七个互斥的坏例归因桶:如 grounding_missing 指向优化知识库召回,tool_failure 指向修复工具 Schema 或下游接口。
metadata.cache.statushit、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 .

查询指标

  1. 在项目侧栏 Observability / AgentOps → Metrics 打开指标页。

  2. 选择数据视图、指标、聚合方式、分组维度、时间粒度和起止时间,再点击 Apply。默认查询最近 24 小时,时间粒度默认为 Hour;可选粒度为 Minute、Hour、Day、Week。

  3. 查看汇总值、时间序列图和维度拆分表。选择分组后,可比较不同维度的变化;需要查看某条 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 归因”面板显示为空?

2. 为什么自定义报表时间范围时点击“应用”报错或被禁用?

3. Metrics 与 Reports 中显示的模型成本(Cost)与组织账单中的实际扣费完全一致吗?


相关文档