链路追踪、观测节点、会话与人工标注
功能概述
链路追踪与人工标注(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)中,运维团队通过本模块实现全方位追踪与质检:
- 实时追踪 VIP 架构师
user_zhangwei_001与工程师user_lina_002提交的工单处理链路(如TK-20261022-001),在同一详情页中自由切换 **ATIF-v1.8规范化智能体轨迹、层级观测树(Observation Tree) 与 时间轴瀑布图(Timeline)**; - 跨链路排查
qwen-plus、text-embedding-v3、qwen3.7-text-rerank及知识库kb_enterprise_support(含graphrag与wiki增强检索子节点)的耗时与 Token 消耗; - 通过 人工标注队列(Annotation Queues) 将疑难工单链路指派给领域专家,使用
5 分钟租约(Lease)机制完成NUMERIC、CATEGORICAL与BOOLEAN多维评分复核。
核心概念与架构
单次智能体执行在可观测引擎中被解构为“顶层 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
endObservation 观测节点类型与技术语义表
观测类型 (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/observations | GET /v1/observability/observations | observability.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-settings | GET/POST /v1/observability/scores、GET/POST /v1/observability/score-configs | observability.scores.read / write |
| 人工标注队列(Annotations) | /observability/annotations | /v1/observability/annotation-queues 及 /assignments、/items、/items/next、/scores、/complete | observability.annotations.read / write / submit |
作用域标签过滤(APPBASE_TRACE_TAGS)与跨系统跳转
为了帮助运维人员快速区分平台托管能力产生的 Trace 与外部业务上报的 Trace,Traces 列表顶部提供了基于权威遥测标签的作用域筛选器:
- **
capability:agent**(托管智能体链路):来自 Agent Runtime 工作台的链路; - **
capability:rag**(托管知识库链路):来自知识库kb_enterprise_support的文档摄取、GraphRAG/RAPTOR/Wiki 构建及混合检索链路; - **
capability:memory(托管记忆链路):来自 Memory 服务的写入、检索、画像与蒸馏链路(在 Memory 页面点击 Trace** 页签即自动携带?tag=capability%3Amemory跳转至此); - **
agentbase-external**(外部上报链路):业务应用通过 SDK 或 OTLP 自主上报的链路。
功能详解与操作指南
1. 查询链路(Traces)与剖析三大详情视图
- 进入项目
enterprise-ai-hub-210的 智能体运维 → 链路(Traces) 页面。 - 支持按 作用域标签、**用户 ID(
userId,如user_zhangwei_001)、链路名称(name)、起止时间 或在搜索框输入完整 Trace ID**(在九州云图部署环境下,还支持直接输入SOFA-TraceId检索匹配的metadata.cloudAtlasTraceId)进行精确查找。 - 单击任意一条 Trace 进入详情页,页面顶部提供 轨迹(Trajectory)、观测树(Observation Tree) 和 时间轴(Timeline) 三个视图切换按钮:
- 默认视图与智能回退规则:
- 当服务端已生成有效、非空的持久化
ATIF-v1.8轨迹且 URL 未指定特定observation参数时,页面默认打开“轨迹”视图,按system/user/assistant/tool规范化节点展示多模态内容(含文本、图片、音频结构化字段)与工具调用过程; - 当 URL 带有有效
?observation=<observationId>参数时,页面自动打开 观测树 并高亮选中该节点,方便团队成员通过复制 URL 分享精准定位; - 若当前 Trace 为纯检索链路或 ATIF 轨迹尚未生成/为空,页面安全回退至 观测树 并禁用轨迹按钮,绝不展示空白面板。
- 当服务端已生成有效、非空的持久化
- 虚拟 Trace 根说明: 观测树与时间轴最外层显示一个虚拟 Trace 根节点,用于展示本轮端到端规范请求(Input)与最终回答(Output)。该虚拟根仅存在于前端展示层,不会重复计入 Observation 总数、Token 消耗或最慢节点统计。
2. 跨链路筛选调用观测(GET /v1/observability/observations)
当需要直接排查“过去 24 小时所有返回 ERROR 级别的 TOOL 调用”或“所有耗时最长的 qwen-plus GENERATION 节点”时,使用 观测(Observations) 列表页或调用 GET /v1/observability/observations:
| 查询参数 | 类型 | 必填 | 取值约束与分页契约 |
|---|---|---|---|
name | string | 否 | 观测节点名称精确匹配(如 "qwen-plus-diagnosis")。 |
type | string | 否 | 逗号分隔的一个或多个合法观测类型,如 "GENERATION,TOOL"(禁止包含空项或未知类型,否则返回 400)。 |
level | string | 否 | 日志级别过滤:DEFAULT、DEBUG、WARNING、ERROR。 |
traceId / environment | string | 否 | 按所属 traceId 或运行环境(如 "production")精确过滤。 |
from / to | string | 否 | ISO-8601 起止时间范围(若 from > to 返回 400)。 |
limit | integer | 否 | 单页条数,取值 **1 ~ 100**,默认 25。 |
offset | integer | 否 | 分页偏移量,**必须是 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)
- 会话视图(Sessions): 进入 智能体运维 → 会话(Sessions),按
sessionId(如sess_ticket_TK_20261022_001)查看同一客户在一次工单处理过程中的全部多轮问答 Trace,方便评估多轮意图跟随与上下文连贯性。 - 用户视图(Users): 进入 智能体运维 → 用户(Users),查看按
userId(如user_zhangwei_001、user_lina_002)聚合的活跃时间窗口、累计 Trace 数量、Observation 数量、总 Token 消耗与预估总成本,单击用户名即可下钻查看该用户发起的所有历史 Trace。
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”、“是否触发安全红线”等二元合规检查。 |
- 查看与筛选评分:在 智能体运维 → 评分(Scores) 页,支持按时间、评估任务、五档质量档位、评估器、来源(
EVAL/ANNOTATION/API)和数据类型多选筛选;展开顶部 洞察区 可查看总数据量、归一化五档条数分布与时间趋势。 - 直接人工评分与批量删除:已登录项目成员可在 Trace、Observation 或 Session 详情页直接添加、修改或删除
ANNOTATION人工评分;在评分列表页还支持勾选当前页最多 100 条ANNOTATION人工评分,经不可撤销确认后执行异步批量删除(EVAL与API产生的评分不可通过人工批量删除移除)。
5. 使用人工标注队列(Annotation Queues)协同复核
当需要组织多名领域专家对一批线上低分或疑难 Trace/Observation/Session 进行标准化盲评或复核时,使用 智能体运维 → 人工标注(Annotations):
- 创建标注队列并绑定配置与成员:
- 单击 创建标注队列(
POST /v1/observability/annotation-queues),填写队列名称(如"VIP工单回答质量专家复核队列"),绑定一个或多个评分配置(scoreConfigIds); - 通过成员分配设置(
PUT /v1/observability/annotation-queues/{queueId}/assignments)指派允许参与该队列标注的项目成员。
- 单击 创建标注队列(
- 将待复核对象加入队列:
- 在 Trace 列表、Trace 详情或 Session 页面勾选目标项,单击 加入标注队列(
POST /v1/observability/annotation-queues/{queueId}/items),支持幂等入队并查看目标所属的全部队列及PENDING/COMPLETED状态。
- 在 Trace 列表、Trace 详情或 Session 页面勾选目标项,单击 加入标注队列(
- 5 分钟租约领取、打分与完成闭环:
- 仅被指派的项目成员可在队列详情页单击 开始标注 / 领取下一项(
POST .../items/next); - 系统为该成员签发 5 分钟独占租约(Lease),防止多人同时标注同一条记录产生冲突(若中途退出可调用
POST .../items/{itemId}/release释放租约); - 标注员对照左侧 Trace/Observation/Session 原文,按右侧绑定的所有评分配置逐项录入分数与评语(
POST .../items/{itemId}/scores,队列评分带有专属queueId隔离标记,不可通过普通直接评分接口篡改); - 完成全部必填评分项后,单击 完成本项(
POST .../items/{itemId}/complete),该队列项状态变为COMPLETED并自动推进队列完成进度。
- 仅被指派的项目成员可在队列详情页单击 开始标注 / 领取下一项(
# 示例:通过 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 .查找一条轨迹
- 选择时间范围、轨迹范围,并输入 Trace 名称或 ID;点击 Apply。范围选项包括 Agent、RAG、Memory、外部轨迹、Agent Runtime 和 Knowledge Base;PowerContext 仅在实例提供该能力时出现。
- 在结果中核对名称、时间、延迟、Observation 数量、Environment、User ID 和 Session ID。列表上方还显示结果总数,以及当前页的 P50/P95 延迟、平均 Observation 数和 Environment 数;翻页后当前页统计会随之变化。
- 点击列表中的轨迹,或在 Open trace 中输入当前项目的 Trace ID 直接打开详情。若打开的列表带有 Name 或 User 筛选标签,可点标签旁的 × 移除该条件后继续查看。
名称/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)”按钮是置灰不可点击的,直接显示了“观测树”?
- 原因分析:
轨迹视图专用于展示由智能体运行时生成并完整持久化的ATIF-v1.8规范轨迹。如果该条 Trace 是一次单纯的知识库检索(/search)、单次 Memory 写入,或者智能体运行尚在分批上报过程中、必需的 Generation/Tool 证据未完结,服务端尚未生成ready状态的 ATIF 轨迹,前端会按安全回退规则自动展示 观测树 并禁用轨迹按钮。 - 解决措施:对于仍在运行或刚结束的 Agent Run,等待数秒后刷新页面即可;对于非 Agent 编排类的普通检索或网关调用,直接在 观测树 与 时间轴 中查看各节点详情。
2. 调用 GET /v1/observability/observations 分页查询时,为什么返回 400 general_argument_invalid?
- 原因分析:Observations 列表接口采用严格的页对齐稳定分页契约:
limit必须在1 ~ 100之间,且 **offset必须是limit的整数倍**(例如当limit=20时,offset传10会被拒绝);此外,若type参数中包含了末尾多余逗号(如"GENERATION,")或未知观测类型,或from时间晚于to时间,也会返回 400。 - 解决措施:按页码
pageIndex(从 0 开始)计算offset = pageIndex * limit,并确保type参数仅包含合法的大写观测类型枚举。
3. 为什么项目管理员或普通成员在人工标注队列(Annotation Queues)里无法点击“领取下一项”或提交评分?
- 原因分析:人工标注队列遵循严格的指派成员检查:即使拥有项目的查看权限,如果当前登录用户未被显式添加到该队列的 指派成员列表(Assignments) 中,服务端也会拒绝其领取租约(
claimNext)或提交队列评分。此外,若某一条目正被另一位被指派成员持有且 5 分钟租约尚未到期,其他成员也无法重复领取该条。 - 解决措施:由队列管理员在队列设置中将目标成员加入指派列表;若前序标注员临时离开,可点击释放租约或等待 5 分钟租约自动过期后重新领取。