AgentbaseDocs
文档目录

链路追踪、观测节点、会话与人工标注

功能概述

链路追踪与人工标注(Traces, Observations, Sessions, Users, Scores & Annotation Queues)是 Agentbase 智能体运维(Observability / AgentOps,v2.10.0)的日常排障与人工复核核心工作台。在智能体应用的研发与生产运维中,开发团队不仅需要查看单次请求的端到端执行瀑布图,还需要跨链路检索特定大模型调用(GENERATION)或工具执行(TOOL),按会话(Session)或用户(User)还原多轮对话上下文,并通过结构化评分(Scores)与多人协同标注队列(Annotation Queues)持续沉淀高质量评测标准。

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 **企业智能客服与知识中台**(enterprise-ai-hub-210)中,运维团队通过本模块实现全方位追踪与质检:


核心概念与架构

单次智能体执行在可观测引擎中被解构为“顶层 Trace 容器 + 树状 Observation 节点 + 规范化 ATIF 轨迹 + 多源 Score 评价”的四维关联结构。

flowchart TB
    subgraph ContextGroup["用户与会话聚合层"]
        UserNode["User (终端用户视图)\nuserId: user_zhangwei_001\n聚合 Trace 数 / Token 总量 / 预估总成本"]
        SessionNode["Session (多轮会话视图)\nsessionId: sess_ticket_TK_20261022_001\n按时间序串联多轮对话 Trace"]
        UserNode --> SessionNode
    end

    subgraph TraceDetail["单条 Trace 三大核心视图 (/observability/traces/{traceId})"]
        VirtualRoot["虚拟 Trace 根 (仅 Console 展示层)\n承载本轮端到端规范请求 Input 与最终响应 Output"]
        ATIFView["1. 轨迹视图 (ATIF-v1.8 Trajectory)\n按 system / user / assistant / tool 规范化还原执行序列"]
        ObsTree["2. 观测树与 3. 时间轴瀑布图\nAGENT -> RETRIEVER (graphrag/wiki) -> GENERATION (qwen-plus) -> TOOL"]
        SessionNode --> VirtualRoot
        VirtualRoot --> ATIFView
        VirtualRoot --> ObsTree
    end

    subgraph ScoringAndQueue["评分体系与协同人工标注"]
        ScoreConfig["评分配置 (Score Settings)\nNUMERIC (数值) / CATEGORICAL (分类) / BOOLEAN (布尔)"]
        ScoreRecord["Score 记录 (展示统一保留两位小数)\n原始值 value + 归一化值 normalizedValue (0~1)\n来源: EVAL / ANNOTATION / API"]
        AnnotationQueue["人工标注队列 (Annotation Queues)\n绑定多个 Score Config & 指派成员\nclaimNext (5分钟租约) -> saveScore -> complete"]
        VirtualRoot --> ScoreRecord
        ObsTree --> ScoreRecord
        ScoreConfig --> ScoreRecord
        ScoreConfig --> AnnotationQueue
        AnnotationQueue -->|"携带 queueId 隔离写入"| ScoreRecord
    end

Observation 观测节点类型与技术语义表

观测类型 (type)典型产生组件核心记录字段与排障用途
**AGENT**智能体工作台 (react.run / react.step)记录智能体编排循环、思考步骤与子任务分发,修正并保持 assistant / user / tool 消息角色层级。
**GENERATION**LLM Gateway / Memory / Agent Runtime记录大模型推理调用(如 qwen-plus、qwen-vl-max),包含 model、modelParameters、input、output、精确 Token 用量(input / output / total 及互斥拆分的 cached / reasoning)与估算成本。
**TOOL**Agent 工具执行 (tool.execute)记录 MCP 工具、数据库查询或自定义函数调用的入参、返回结果、执行状态与耗时。
**RETRIEVER**知识库 /search 与 Memory 检索记录向量与混合检索过程。在知识库检索 Trace 中,实际尝试增强检索时还会生成 graphrag 与 wiki 子节点,记录 retrieval.status、retrieval.returned_count 与 stage.duration_ms。
**EMBEDDING**向量化阶段 (embed_query)记录调用 text-embedding-v3 生成查询或文档向量的耗时与 Token 消耗。
**SPAN**通用处理阶段 (context.prepare / HTTP / 队列)记录非模型类的内部阶段耗时(如上下文准备、未请求增强检索时的默认跳过阶段、HTTP 客户端调用与队列投递)。
**EVENT**瞬时关键事件 (memory.ingest.stage_failed)记录无持续时长的瞬时状态跳变或异常事件(如阶段错误码 errorCode、gatewayStatus)。
**EVALUATOR / GUARDRAIL / CHAIN**评估器与安全护栏 (gp-enterprise-safety)记录在线护栏拦截检查、评估器执行或复合调用链步骤。

角色、入口与关联关系

控制台入口与 REST API 映射

在项目 enterprise-ai-hub-210 的 智能体运维(Observability / AgentOps) 侧栏中,相关页面与底层 API 对应关系如下:

页面名称控制台路径后缀核心 REST API 端点所需权限 Scope
链路列表与详情(Traces)/observability/traces · /traces/{traceId}GET /v1/observability/traces、GET /v1/observability/traces/{traceId}observability.traces.read
调用观测列表(Observations)/observability/observationsGET /v1/observability/observationsobservability.traces.read
会话视图(Sessions)/observability/sessions · /sessions/{sessionId}GET /v1/observability/sessions、GET /v1/observability/sessions/{sessionId}observability.sessions.read
用户视图(Users)/observability/users · /users/{userId}GET /v1/observability/users、GET /v1/observability/users/{userId}observability.users.read
评分与评分设置(Scores)/observability/scores · /score-settingsGET/POST /v1/observability/scores、GET/POST /v1/observability/score-configsobservability.scores.read / write
人工标注队列(Annotations)/observability/annotations/v1/observability/annotation-queues 及 /assignments、/items、/items/next、/scores、/completeobservability.annotations.read / write / submit

作用域标签过滤(APPBASE_TRACE_TAGS)与跨系统跳转

为了帮助运维人员快速区分平台托管能力产生的 Trace 与外部业务上报的 Trace,Traces 列表顶部提供了基于权威遥测标签的作用域筛选器:


功能详解与操作指南

1. 查询链路(Traces)与剖析三大详情视图

2. 跨链路筛选调用观测(GET /v1/observability/observations)

当需要直接排查“过去 24 小时所有返回 ERROR 级别的 TOOL 调用”或“所有耗时最长的 qwen-plus GENERATION 节点”时,使用 观测(Observations) 列表页或调用 GET /v1/observability/observations:

查询参数类型必填取值约束与分页契约
namestring否观测节点名称精确匹配(如 "qwen-plus-diagnosis")。
typestring否逗号分隔的一个或多个合法观测类型,如 "GENERATION,TOOL"(禁止包含空项或未知类型,否则返回 400)。
levelstring否日志级别过滤:DEFAULT、DEBUG、WARNING、ERROR。
traceId / environmentstring否按所属 traceId 或运行环境(如 "production")精确过滤。
from / tostring否ISO-8601 起止时间范围(若 from > to 返回 400)。
limitinteger否单页条数,取值 **1 ~ 100**,默认 25。
offsetinteger否分页偏移量,**必须是 limit 的整数倍**(如 limit=25 时,offset 仅允许 0, 25, 50...,否则返回 400 general_argument_invalid)。
# 查询 enterprise-ai-hub-210 项目中所有 GENERATION 与 TOOL 类型的观测节点(第 1 页,每页 25 条)
curl -fsS --get "https://appbuild.oceanbase.com/v1/observability/observations" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  --data-urlencode "type=GENERATION,TOOL" \
  --data-urlencode "environment=production" \
  --data-urlencode "limit=25" \
  --data-urlencode "offset=0" | jq .

3. 追踪多轮会话(Sessions)与终端用户(Users)

4. 管理评分体系(Scores)与五档归一化分布

Agentbase 支持三种数据类型的评分配置(Score Settings):

评分数据类型 (dataType)取值与配置方式归一化值 (normalizedValue) 计算规则与控制台展示
**NUMERIC(数值型)**定义最小值 minValue 与最大值 maxValue(如 0 ~ 1 或 1 ~ 5)系统严格依据该 Score 绑定的 configId(包含已归档配置)将原始分数线性归一化至 [0, 1] 区间,并划分为 五档质量分布(Excellent / Good / Average / Poor / Very Poor)。控制台所有数值评分统一保留 两位小数(如 0.92)。
**CATEGORICAL(分类型)**定义枚举类别集合(如 ["准确", "部分遗漏", "严重幻觉"])记录命中的类别字符串 stringValue,支持在评分列表中按分面统计各分类占比。
**BOOLEAN(布尔型)**二值判断(true / false,对应数值 1 / 0)适合“是否遵循 SOP”、“是否触发安全红线”等二元合规检查。

5. 使用人工标注队列(Annotation Queues)协同复核

当需要组织多名领域专家对一批线上低分或疑难 Trace/Observation/Session 进行标准化盲评或复核时,使用 智能体运维 → 人工标注(Annotations):

# 示例:通过 REST API 创建人工标注队列并将一条疑难工单 Trace 加入队列
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"

# 1. 创建人工标注队列 (绑定数值型与布尔型评分配置)
QUEUE_RESP="$(curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/annotation-queues" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "企业客服SOP合规与技术准确性复核队列",
    "description": "针对 P0 工单链路进行人工专家复核",
    "scoreConfigIds": ["sc_sop_compliance_bool", "sc_tech_accuracy_num"]
  }')"

QUEUE_ID="$(echo "${QUEUE_RESP}" | jq -er '.id')"

# 2. 将工单 Trace 幂等加入该标注队列
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/annotation-queues/${QUEUE_ID}/items" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "objectId": "tr_support_ticket_20261022_001",
        "objectType": "TRACE"
      }
    ]
  }' | jq .

查找一条轨迹

名称/ID 搜索、类别和时间范围会共同影响结果。没有找到记录时,先扩大时间范围、恢复轨迹范围并清除搜索条件;仍无结果时,再核对 Trace ID 是否属于当前项目,以及写入侧是否向该项目发送了 Trace。

分析轨迹详情

详情顶部显示轨迹状态、Error Observation 数、Session、总耗时、最慢 Observation 和 Token 用量。若部分生成记录缺少 Token 用量,页面会将汇总标为“已知用量”,不要把不完整统计理解为完整总量。有关联 Session ID 时,可从详情跳转到对应会话。

在轨迹工作区按数据情况查看 Observation 树、时间线或可展示的 Agent trajectory。选择某条 Observation 后,右侧详情可检查输入、输出、metadata 与关联评分;Observation 还可能包含用量和成本信息。时间线适合定位耗时较长或带 Error 级别的阶段,树视图则便于沿父子 Observation 检查调用结构。

详情状态是基于观测证据生成的信号:存在 ERROR 级别的 Observation 时显示 Error;没有此类 Observation、但存在 Observation 或延迟证据时显示 Success;缺少这些证据时显示 Unknown。该状态不代替应用自身的业务响应校验;Unknown 或空 Observation 也不能据此判定调用成功或失败。

Memory 页面中的 Traces 入口会打开轨迹列表并筛选 Memory 轨迹,可用于检查记忆链路。需要按时间段比较调用数量、延迟、Token 或评分时,继续查看指标分析;数据集运行记录见数据集。

常见问题与排障

1. 为什么打开某条 Trace 详情时,“轨迹(Trajectory)”按钮是置灰不可点击的,直接显示了“观测树”?

2. 调用 GET /v1/observability/observations 分页查询时,为什么返回 400 general_argument_invalid?

3. 为什么项目管理员或普通成员在人工标注队列(Annotation Queues)里无法点击“领取下一项”或提交评分?


相关文档