Docs
文档目录

指标监控与分析报表

功能概述

指标监控与分析报表(Metrics & Analytical Reports,控制台入口包括 智能体运维 → 指标;报表入口是否显示取决于部署配置)是 Agentbase 面向技术负责人、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):入口和页面取决于部署的可见性配置。若报表被隐藏,直达链接也会重定向;需要使用时请确认部署配置和权限。

接口 / 页面HTTP 方法与路径所需 API Key Scopes(用户会话/JWT 角色默认包含)
Metrics 指标查询/v1/observability/metrics(及控制台聚合查询)observability.metrics.read
Overview 全局总览报表POST /v1/observability/reports/overviewobservability.metrics.read
Agents 智能体排行报表POST /v1/observability/reports/agentsobservability.metrics.read + observability.traces.read + 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)。

指标页面

图:2.12.0 测试项目中的指标页面;具体内容因项目而异。

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

    • 时间范围与环境筛选:选择统计时间段与目标环境(如 production);

    • memoryOnly 过滤:在 Observations 视图开启该选项,控制台查询会增加 service=memory 过滤条件,用于分析符合条件的观测数据。Traces 和 Scores 视图不提供此筛选,不能据此认为评分也已按 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调用方上报的缓存状态;字段是否存在及其含义取决于具体数据来源。

4. 调用分析报表 Bundle API 示例

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY for the target environment}"

  # 1. 查询近 7 天 (7d) 的 Overview 全局总览报表
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/observability/reports/overview" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "Content-Type: application/json" \
    --data '{
      "range": "7d"
    }' | jq .

  # 2. 使用自定义时间窗口 (from/to, 跨度 <= 30 天) 查询 Quality 质量与 Bad Case 归因报表
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/observability/reports/quality" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -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. 选择数据视图、指标、聚合方式、分组维度、时间粒度和起止时间,再点击 应用。默认查询最近 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 过滤。

没有指标数据时

若图表显示 暂无指标数据,先检查起止时间是否覆盖数据产生时段,再确认数据视图、指标和分组是否匹配;使用 Memory only 时,也确认查询目标是 Observations。更改条件后重新点击 应用。页面的刷新按钮会重新请求当前指标查询。

若调整条件后仍无数据,核对当前项目是否已写入对应类型的 Trace、Observation 或 Score,并检查 Trace 的时间和用量记录。空结果只代表当前查询未返回数据,不能据此得出“无调用”“零成本”或“质量为零”的结论。

常见问题与排障

1. 为什么在报表(Reports)页面中,总调用量与 Token 都有数据,但“Token 浪费”或“Bad Case 归因”面板显示为空?

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

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


相关文档