可观测性总览(智能体运维 / AgentOps)
功能概述
AI 可观测性(AI Observability,控制台左侧导航分区名称为 智能体运维 / AgentOps)是 Agentbase(v2.10.0)面向企业级大模型与智能体应用打造的全链路追踪、质量评估、标注复核与成本度量平台。在复杂的智能体生产系统中,单次用户请求往往跨越智能体工作台(Agent Runtime)、AI 网关(AI Gateway)、知识库检索(Knowledge Base RAG)与长期记忆(Memory)等多个子系统,涉及多次大模型推理(Generation)与工具调用(Tool Execution)。传统的 APM 监控只能看到 HTTP 状态码与接口耗时,无法洞察 Prompt 质量、检索相关性、幻觉风险与 Token 成本归属。
在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210)中,智能体运维(AgentOps)提供了从采集、观测到评测治理的完整闭环:
双通道统一遥测采集:同时支持标准 OpenTelemetry OTLP 协议上报与
/v1/observability/ingestion批量事件接入,自动汇聚平台托管能力(capability:agent、capability:rag、capability:memory)与外部自定义 SDK 上报(agentbase-external);全维度领域模型:围绕 Trace(端到端链路)、Observation(细粒度节点:Span / Generation / Event / Agent / Tool)、Session(多轮会话)、User(终端用户)、Prompt(提示词版本)、Score(多维评分)、Dataset(评测基准集) 与 Metrics / Reports(指标与分析报表) 构建统一视图;
企业级数据治理:提供项目级 数据保留设置(
/v1/observability/settings/data-retention)、敏感凭据自动脱敏([REDACTED])与细粒度 RBAC 权限控制。
核心概念与架构
Agentbase Observability 采用“Agentbase 统一鉴权与控制面 + 高性能轨迹存储与异步评估引擎”的分层架构。浏览器与客户端 SDK 仅通过 /v1/observability/* 公开网关交互,由平台强校验项目归属与 Scope 权限。
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
核心数据模型定义表
| 领域实体 | 关键标识与层级关系 | 核心属性与技术语义 |
|---|---|---|
| Trace(调用链路) | traceId(顶层根容器) | 代表一次端到端业务请求(如智能客服处理工单 TK-20261022-001 的单轮完整问答)。挂载 userId、sessionId、name、input、output、tags、metadata 及持久化 ATIF-v1.8 规范轨迹。 |
| Observation(观测节点) | observationId(通过 parentObservationId 组成树) | Trace 内部的具体执行步骤。支持 10 种标准类型:GENERATION(大模型调用,含模型名、Token 明细与成本)、TOOL(工具调用)、AGENT(智能体编排步)、SPAN(通用耗时跨度)、EVENT(瞬时事件)、RETRIEVER(知识/记忆检索)、EMBEDDING、CHAIN、EVALUATOR、GUARDRAIL。 |
| Session(多轮会话) | sessionId(聚合多条 Trace) | 按时间序串联同一对话窗口内的多轮 Trace,汇总整场会话的总耗时、总 Token 用量与用户满意度评分。 |
| User(终端用户) | userId(如 user_zhangwei_001) | 按业务用户维度聚合其历史发起的全部 Trace、Observation 数量、累计 Token 消耗、预估成本与评分分布。 |
| Score(质量评分) | scoreId(绑定 traceId 及可选 observationId / sessionId) | 度量单次生成或整条链路的质量。支持 NUMERIC(数值型,自动根据配置计算 0~1 归一化值 normalizedValue)、CATEGORICAL(分类型)、BOOLEAN(布尔型);来源分为 EVAL(自动评估)、ANNOTATION(人工标注)与 API(外部上报)。 |
| Prompt(提示词资产) | promptId / name + version / label | 集中管理版本化 Prompt 模板(含 production 等标签),支持通过 GET /v1/observability/prompts/resolve 在推理或评估时确定性解析。 |
角色、入口与关联关系
控制台页面结构与四大导航分区
在项目 enterprise-ai-hub-210 左侧导航栏展开 智能体运维(Observability / AgentOps),系统按四大业务分区组织全部子页面:
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
| 分区名称 | 页面名称 | 控制台路由后缀 | 核心功能说明 | 所需权限 Scope |
|---|---|---|---|---|
| Observation(观测) | Traces(链路) | /observability/traces | 默认落地页。按作用域标签、用户、名称过滤链路,查看 ATIF 轨迹、观测树与瀑布图。 | observability.traces.read |
| Observation(观测) | Observations(调用观测) | /observability/observations | 跨 Trace 平铺检索全项目所有 Observation 节点,支持按多类型、级别、环境与时间窗口稳定分页。 | observability.traces.read |
| Observation(观测) | Sessions / Users | /observability/sessions · /users | 按会话聚合多条关联链路,或按终端用户(如 user_zhangwei_001)下钻行为与成本。 | observability.sessions.read / observability.users.read |
| Observation(观测) | Metrics(指标监控) | /observability/metrics | 基于轨迹派生的延迟分位值(P50/P95/P99)、Token 用量、模型成本与评分趋势看板。 | observability.metrics.read |
| Observation(观测) | 数据设置(Data Settings) | /observability(数据设置入口) | 配置项目级观测数据保留天数(3~36,500 天或无限期保留)。 | observability.settings.read / write |
| Prompts(提示词) | Prompts | /observability/prompts | 版本化管理 Prompt 模板、在线 Playground 试验与确定性 /resolve 解析。 | observability.prompts.read / write |
| Evaluations(评估) | Evals & Evaluation Skills | /observability/evals · /evaluation-skills | 内置与自定义评估模板、通用/Memory/知识库解析与索引质量评估任务、只读评估技能包管理。 | observability.evals.read / write |
| Evaluations(评估) | Scores & Score Settings | /observability/scores · /score-settings | 查看自动与人工评分、五档归一化分布、低分根因分析(RCA)及维护评分配置。 | observability.scores.read / write |
| Evaluations(评估) | Annotations(人工标注) | /observability/annotations | 创建人工标注队列、指派项目成员领取租约并对 Trace/Observation/Session 复核打分。 | observability.annotations.read / write / submit |
| Assets / Data(数据资产) | Datasets(数据集) | /observability/datasets | 管理黄金评测数据集(如 enterprise-support-golden-v1)、导入 CSV 并触发基准对比运行。 | observability.datasets.read / write |
| Assets / Data(数据资产) | Reports(分析报表) | /observability/reports/overview(及 /agents、/quality) | 固定窗口(24h/7d/30d 或自定义 ≤30d)的用量、成本、ROI 与 Bad Case 归因看板(侧栏入口默认隐藏,通过直达 URL 访问)。 | observability.metrics.read + traces.read + scores.read |
与平台四大 AI 能力的深度联动
与智能体工作台(Agent Runtime)联动: 当平台启用
agentops.runtimeExportEnabled时,Agent Runtime 自动将每次 ReAct 运行导出为带capability:agent标签的 Trace,并异步整合成符合ATIF-v1.8规范的标准化执行轨迹;数据集评测还可直接将 Agent Runtime 作为评测目标触发批量回放。与知识库(Knowledge Base
kb_enterprise_support)联动:摄取与构建追踪:当平台开启
agentops.ingestionTracingEnabled且知识库开启tracingEnabled时,文档解析、分块以及 GraphRAG / RAPTOR / LLM Wiki 索引构建均生成独立 Trace,并直接支撑 知识库解析与索引质量评估;增强检索追踪:每次调用
/v1/knowledge-base/{kbId}/search时,除了基础的embed_query、search、rerank节点外,系统还在同一 Trace 下记录graphrag与wiki子节点的retrieval.status(not_requested/not_ready/succeeded/degraded/failed)、返回条数与阶段耗时。
与长期记忆(Memory)联动: Memory 的每次写入、检索、画像提取与经验蒸馏自动打上
capability:memory标签并返回X-AppBase-Trace-Id响应头;在 Memory 控制台点击 Trace 页签即可一键带过滤条件跳入链路追踪页,且 Metrics 看板支持一键开启memoryOnly专属过滤。
功能详解与操作指南
1. 双通道接入:OpenTelemetry OTLP 与 /v1/observability/ingestion
除平台托管组件自动上报外,业务应用可通过以下两种标准通道将自定义智能体或后端微服务的调用链路上报至项目 enterprise-ai-hub-210:
通道一:使用 /v1/observability/ingestion 批量事件摄取接口
适合通过 REST API 或 agentbase-node-sdk@2.10.0 直接上报结构化的 trace-create、generation-create、span-create 与 score-create 事件批次:
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"
# 批量上报一条客服工单处理 Trace 及其内部的 qwen-plus Generation 节点
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/ingestion" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"batch": [
{
"id": "evt_trace_20261022_001",
"type": "trace-create",
"timestamp": "2026-10-22T10:15:00.000Z",
"body": {
"id": "tr_support_ticket_20261022_001",
"name": "enterprise-ticket-triage",
"userId": "user_zhangwei_001",
"sessionId": "sess_ticket_TK_20261022_001",
"input": "工单 TK-20261022-001:核心账务集群 HNSW 向量索引重建报 -4013 内存不足",
"output": "已定位为 ob_vector_memory_limit_percentage 配额不足,建议调升至 30%",
"tags": ["capability:agent", "sla:P0-VIP"],
"environment": "production",
"metadata": {
"ticketId": "TK-20261022-001",
"gatewayId": "gw_7194685489feb1e169548619"
}
}
},
{
"id": "evt_gen_20261022_001",
"type": "generation-create",
"timestamp": "2026-10-22T10:15:00.120Z",
"body": {
"id": "obs_gen_qwen_plus_001",
"traceId": "tr_support_ticket_20261022_001",
"name": "qwen-plus-diagnosis",
"startTime": "2026-10-22T10:15:00.120Z",
"endTime": "2026-10-22T10:15:01.480Z",
"model": "qwen-plus",
"input": [{"role": "user", "content": "排查 OB -4013 向量内存错误"}],
"output": {"role": "assistant", "content": "请检查 GV$OB_VECTOR_MEMORY_INFO 并调高 ob_vector_memory_limit_percentage。"},
"usage": {
"input": 420,
"output": 185,
"total": 605,
"unit": "TOKENS"
},
"metadata": {
"cache": {"status": "miss"}
}
}
}
]
}' | jq .通道二:使用 OpenTelemetry OTLP 标准协议接入
对于已集成 OpenTelemetry SDK(Node.js / Python / Go / Java)的应用,可直接配置 OTLP HTTP Exporter 指向项目的 OTLP 接收端点,携带项目头 X-Appwrite-Project: enterprise-ai-hub-210 与具备 observability.traces.write 权限的 API Key,平台会自动将 OpenTelemetry GenAI 语义约定属性(gen_ai.system、gen_ai.request.model、gen_ai.usage.*)映射为标准 GENERATION 与 TOOL 观测节点。
2. 跨链路调用观测列表(Observations)与指标看板(Metrics)
在左侧导航栏单击 智能体运维 → 观测(Observations),进入跨链路观测记录列表页。该页面支持跳过顶层 Trace,直接按观测名称(
name)、观测类型(GENERATION、TOOL、AGENT、RETRIEVER等多选)、日志级别(DEFAULT、DEBUG、WARNING、ERROR)、traceId、environment与起止时间过滤所有细粒度执行节点。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
在左侧导航栏单击 智能体运维 → 指标(Metrics),查看由轨迹实时派生的调用量、P50/P95/P99 延迟、Token 消耗、模型成本估算与质量评分分布。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
3. 配置项目级观测数据保留策略(Data Retention)
企业可根据合规审计要求与存储成本预算,在 智能体运维 → 观测 → 数据设置 中配置当前项目可观测数据的保留周期(对应控制面接口 GET/PATCH /v1/observability/settings/data-retention):
| 参数字段 | 类型 | 取值范围与默认值 | 治理规则与安全边界 |
|---|---|---|---|
retentionDays | integer | null | 默认 null(无限期保留);有限保留支持 3 ~ 36500 的整数天数(传入 0 或 null 均归一化为无限期) | 覆盖当前项目的 Trace、Observation、Score 以及关联的分析制品和媒体。保存仅更新保留策略,由后台定时任务按日清理超期数据,不会在保存瞬间同步阻塞删除。 |
expectedRevision | string | 最近一次 GET 响应返回的 revision 字符串 | 乐观锁并发保护。每次保存有限保留天数时,控制台会弹出不可恢复清理风险确认框;已清理的历史数据无法通过后续调大天数或改回无限期恢复。 |
# 查询并更新 enterprise-ai-hub-210 项目的观测数据保留策略为 180 天
RET_DATA="$(curl -fsS "${APPBASE_ENDPOINT}/observability/settings/data-retention" \
-H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Mode: admin")"
REV="$(echo "${RET_DATA}" | jq -er '.revision')"
curl -fsS -X PATCH "${APPBASE_ENDPOINT}/observability/settings/data-retention" \
-H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Mode: admin" \
-H "Content-Type: application/json" \
--data "{
\"retentionDays\": 180,
\"expectedRevision\": \"${REV}\"
}" | jq .4. 平台全局可观测开关说明(实例管理员参考)
在平台管理后台(/_internal/admin 的 智能体运维 页签)中,实例管理员通过 4 个全局动态配置键控制全平台能力边界(修改后约 5 分 30 秒内同步至全部 PHP Worker、Memory 与 Agent Runtime 进程):
| 平台配置键 | 环境默认值变量 | 作用说明 |
|---|---|---|
agentops.enabled | _APP_LANGFUSE_ENABLED | 平台可观测总开关,控制模块入口、/v1/observability/* API 及内部服务 Trace 导出。 |
agentops.ingestionTracingEnabled | _APP_KNOWLEDGE_BASE_INGESTION_TRACING_ENABLED(默认 enabled) | 全局允许知识库摄取与索引构建追踪(仍需知识库自身 tracingEnabled=true)。 |
agentops.runtimeExportEnabled | AGENTOPS_LANGFUSE_ENABLED | 控制智能体工作台(Agent Runtime)Trace 导出与数据集运行关联。 |
agentops.memoryCaptureContentEnabled | MEMORY_OBSERVABILITY_CAPTURE_CONTENT_ENABLED(默认 true) | 全局允许 Memory 捕获正文内容(仍需项目级 policy.observability.captureContent=true)。 |
选择 Prompt 版本并查看使用说明
在 Observability / AgentOps → Prompts 打开目标 Prompt,在详情中切到使用说明(Usage)。当前项目需要已有可读取的 Prompt;对业务应用提供读取凭据时,只授予所需的 Prompt 读取权限,不把密钥写进 Prompt 内容或示例变量。
先选择标签或固定版本,再选择 curl、Python 或 TypeScript 示例。
检查页面显示的版本和变量。切换版本时等待内容加载完成;加载失败时先排查当前项目、权限及版本是否存在,不复制旧版本示例代替。
按页面说明替换 endpoint 和凭据占位符,确认项目 ID 正确。变量名来自所选版本,示例变量值需要换成业务输入。
运行后核对返回的 Prompt 名称、版本、正文与变量,再接入业务调用或评估。
| 选择方式 | 适用场景 | 注意事项 |
|---|---|---|
production、latest 或自定义标签 | 希望调用跟随标签所指向的版本 | 标签可以移动,不能当作不可变快照 |
| 固定版本号 | 回归评估、复现某次回答 | 明确使用正整数版本;不能同时指定标签 |
按名称解析时,不指定标签和版本默认使用 production,不代表自动获取最新版本。如果需要更早的历史版本,先在版本列表加载对应历史页,再在使用说明中选择。
Python / TypeScript 示例会按所选版本替换文本 Prompt 或聊天消息中的变量;curl 示例只提示变量,不执行替换。聊天 Prompt 中的消息占位项也不等于已填入完整对话,接入前需按业务要求处理。Prompt 版本核对通过后,可用同一组数据集对比效果;检索回答的质量检查见评估与评分。
常见问题与排障
1. 为什么在智能体工作台或知识库执行了操作,但在 Traces 列表中没有看到新增链路?
原因分析:排查以下三层开关与采样配置:① 平台全局总开关
agentops.enabled及对应子开关(agentops.runtimeExportEnabled或agentops.ingestionTracingEnabled)是否已启用;② 知识库或 Memory 项目自身的追踪开关(如知识库tracingEnabled、Memorypolicy.observability.enabled)是否开启;③ 异步摄取队列是否仍在处理中(遇到底层数据库连接瞬态波动时,队列会自动进入最长 30 秒的指数退避冷却保护,不会丢失事件)。解决措施:稍等数秒后刷新 Traces 列表;若持续无数据,请实例管理员在
/_internal/admin检查四项全局开关状态及导出器连接配置。
2. Trace 详情中的 Input / Output 显示 [REDACTED] 是什么原因?属于上报故障吗?
原因分析:不属于故障。当内容安全策略或隐私配置(例如关闭了
captureContent或命中敏感凭据脱敏规则)移除了Authorization、Cookie、API Key、密码或业务隐私正文时,系统会显式保留[REDACTED]标记,并在详情页提示原值未被存储。解决措施:切勿把
[REDACTED]当作遥测数据丢失。如需在调试环境查看 Memory 的完整模型输入输出,可在非敏感测试项目中同时开启平台agentops.memoryCaptureContentEnabled与项目policy.observability.captureContent。
3. 为什么普通项目成员调用 GET /v1/observability/settings/data-retention 会返回 404 project_not_found 或 403?
原因分析:数据保留设置属于高敏感管理面接口(
AuthType::ADMIN),不支持使用普通业务 API Key 调用。同时,调用者必须具备当前项目的访问权限及observability.settings.read(读取)或observability.settings.write(修改,仅限项目owner、admin、developer、editor角色)。无项目可见性的跨团队成员访问时统一返回404 project_not_found以防止项目枚举。解决措施:请使用具备当前项目管理权限的账号登录 Console 控制台操作,不要在客户端代码中使用业务 API Key 调用该设置接口。



