AgentbaseDocs
文档目录

指标监控与分析报表

功能概述

指标监控与分析报表(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 请求即可完成多维指标渲染。

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 权限矩阵

接口 / 页面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 专属过滤

截图未公开:原图可能包含账号或资源标识。

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

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 .

查询指标

可选指标和分组取决于数据视图:

数据视图指标可选分组
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)与组织账单中的实际扣费完全一致吗?


相关文档