coze-loop · 评分、指标与告警

约 7 分钟1,844 字更新于 2026/10/22

本页覆盖：评分与标注、自动评估、指标与大盘、告警与通知。每条事实链到固定提交（3a6a2bf0）。回到 coze-loop 总览。

七、评分与标注

• 标注类型有 auto_evaluate、manual_evaluation_set、manual_feedback、coze_feedback、openapi_feedback（idl/thrift/coze/loop/observability/domain/annotation.thrift L5-L10）。
• Annotation 同时带 span_id 和 trace_id（idl/thrift/coze/loop/observability/domain/annotation.thrift L50-L53）。
• 自动评估结果含 score、correction、reasoning，关联 evaluator、record、task、experiment（idl/thrift/coze/loop/observability/domain/annotation.thrift L26-L40）。
• 手工反馈含 tag key 和 tag value（idl/thrift/coze/loop/observability/domain/annotation.thrift L43-L48）。
• 手工标注的增删改查路由在 /api/observability/v1/annotations，另有 annotations/list_by_workspace 和 annotation/list_evaluators（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L637-L641、idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L645）。
• 创建手工标注时先按 span 找原记录，再写成 manual_feedback 并插入标注表（backend/modules/observability/domain/trace/service/trace_service.go L1955-L1998）。
• 应用层用 tag 服务校验这条手工标注（backend/modules/observability/application/trace.go L867-L871）。
• 创建标注检查 createLoopTraceAnnotation，删除检查 deleteLoopTraceAnnotation（backend/modules/observability/domain/component/rpc/auth.go L15-L16）。
• OpenAPI 也能创建和删除反馈：POST 和 DELETE /v1/loop/annotations（idl/thrift/coze/loop/observability/coze.loop.observability.openapi.thrift L240-L241、backend/modules/observability/application/openapi.go L463-L556）。
• OpenAPI 标注有单独的 QPS 限流（backend/modules/observability/application/openapi.go L1189-L1209）。
• 改评估分的接口是 POST /api/observability/v1/traces/change_eval_score，要求 annotation id 和 correction（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L644、backend/modules/observability/application/trace.go L1171-L1212、backend/modules/observability/domain/trace/service/trace_service.go L2349-L2437）。
• 标注写入 ClickHouse 后，会向 observability_span_queue 发一条带 span 的事件（backend/modules/observability/infra/repo/trace.go L583-L618、release/deployment/docker-compose/conf/observability.yaml L28-L42）。
• 异步标注事件由 Send 处理：找到 span 后补 metadata 再写标注，找不到就重发（backend/modules/observability/domain/trace/service/trace_service.go L2214-L2263）。
• 自动评估和 Trace 的关系是：评估结果作为 auto_evaluate 类型的标注写回对应 span（backend/modules/observability/domain/task/service/task_callback.go L115-L145）。
• 评估分被人工修正时，回调会更新同一条标注的 correction（backend/modules/observability/domain/task/service/task_callback.go L186-L222）。
• 标注与 span 的关联键是 span_id 加 trace_id（backend/modules/observability/domain/trace/entity/loop_span/span.go L946-L957）。
• 前端有手工标注面板，调用 CreateManualAnnotation 与更新接口（frontend/packages/loop-components/tag-components/src/components/annotation-panel/label-item.tsx L82、frontend/packages/loop-components/tag-components/src/components/annotation-panel/label-item.tsx L109）。
• 观测组件里有 Feedback 页签，渲染 TraceFeedBack（frontend/packages/loop-components/observation-components/src/features/trace-detail/components/feedback/tab.tsx L9-L20）。
• Trace 页面没有把 Feedback 页签挂进 span 详情。列表加详情面板默认传空的额外页签（frontend/packages/loop-components/observation-components/src/trace-list-with-detail-panel.tsx L390）。

自动评估任务

• 任务类型有 auto_evaluate 和 auto_data_reflow（idl/thrift/coze/loop/observability/domain/task.thrift L13-L15）。
• 任务含过滤规则、采样器、生效时间窗和回填时间窗（idl/thrift/coze/loop/observability/domain/task.thrift L56-L75）。
• 采样器有采样率、采样上限、是否循环、每轮上限、间隔和时间单位（idl/thrift/coze/loop/observability/domain/task.thrift L63-L70）。
• 自动评估配置是 evaluator 版本加字段映射（trace 字段键加 jsonpath）（idl/thrift/coze/loop/observability/domain/task.thrift L107-L113、idl/thrift/coze/loop/observability/domain/task.thrift L130-L135）。
• 任务状态有 unstarted、running、failed、success、pending、disabled（idl/thrift/coze/loop/observability/domain/task.thrift L21-L27）。
• 任务 API 只有 check_name、创建、更新、列表、详情，没有删除（idl/thrift/coze/loop/observability/coze.loop.observability.task.thrift L80-L84）。
• MySQL 表是 task 和 auto_task_run（release/deployment/docker-compose/bootstrap/mysql-init/init-sql/task.sql L1-L23、release/deployment/docker-compose/bootstrap/mysql-init/init-sql/auto_task_run.sql L1-L12）。
• 处理器工厂只注册了 auto_evaluate（backend/modules/observability/application/wire.go L396-L404）。
• auto_data_reflow 没有注册处理器。已在 backend/modules/observability/application/wire.go 与 backend/modules/observability/domain/task/service/taskexe/processor/ 搜索，只有 NoopTaskProcessor 一个空实现（backend/modules/observability/domain/task/service/taskexe/processor/noop.go L12-L30）。
• 实时触发入口 SpanTrigger 先按 workspace 过滤、跳过 Evaluator 类型 span，再匹配任务规则、采样、派发（backend/modules/observability/domain/task/service/taskexe/tracehub/span_trigger.go L69-L109、backend/modules/observability/domain/task/service/taskexe/tracehub/span_trigger.go L111-L184）。
• SpanTrigger 的两个调用来源是 MQ 消费者：trace_to_task 的原始 span，和 observability_span_queue 的带标注 span（backend/modules/observability/infra/mq/consumer/task_consumer.go L55-L66、backend/modules/observability/infra/mq/consumer/span_with_annotation_consumer.go L54-L64、backend/modules/observability/application/task.go L300-L339）。
• 本仓库没有 trace_to_task 的生产者。已在 backend、release（排除文档）搜索该 topic 名，只出现在消费者配置和 RMQ 订阅文件里（release/deployment/docker-compose/conf/observability.yaml L410-L417、release/deployment/docker-compose/bootstrap/rmq-init/init-subscription/subscriptions.cfg L14）。
• 历史数据回填走 cozeloop_async_tasks topic 和 BackFillConsumer（release/deployment/docker-compose/conf/observability.yaml L386-L400、backend/modules/observability/infra/mq/consumer/backfill_consumer.go L53）。
• 评估完成后由 cozeloop_evaluation_online_expt_eval_result 回调写标注（release/deployment/docker-compose/conf/observability.yaml L402-L408、backend/modules/observability/infra/mq/consumer/autotask_callback_consumer.go L50）。
• 前端业务源码没有任务相关接口的调用。已在 frontend/packages、frontend/apps（排除 api-schema）搜索 observabilityTask、ListTasks、CreateTask，无命中。

八、指标与大盘

• 指标 API 是 POST /api/observability/v1/metrics/list 和 metrics/drill_down_values（idl/thrift/coze/loop/observability/coze.loop.observability.metric.thrift L76-L77）。
• TraverseMetrics 没有 HTTP 路由注解（idl/thrift/coze/loop/observability/coze.loop.observability.metric.thrift L78）。
• 请求含 metric_names、granularity、filters、platform_type、drill_down_fields、compare（idl/thrift/coze/loop/observability/coze.loop.observability.metric.thrift L9-L21）。
• 响应的 Metric 有三种形态：summary、pie、time_series（idl/thrift/coze/loop/observability/domain/metric.thrift L15-L24）。
• 对比类型有同比 yoy 和环比 mom（idl/thrift/coze/loop/observability/domain/metric.thrift L3-L5、idl/thrift/coze/loop/observability/domain/metric.thrift L26-L29）。
• 下钻维度有 model_name、tool_name、inner_model_name、annotation_key、feedback_source（idl/thrift/coze/loop/observability/domain/metric.thrift L8-L13）。
• 时间粒度有 1min、1hour、1day、1week（backend/modules/observability/domain/metric/entity/metric.go L32-L35）。
• 指标名分五组：general、model、tool、service、agent、feedback，共约 55 个（backend/modules/observability/domain/metric/entity/metric.go L41-L114）。
• 总量与失败率有 general_total_count、general_fail_ratio、general_model_total_tokens（backend/modules/observability/domain/metric/entity/metric.go L41-L48）。
• token 类指标有输入、输出、system、tool_choice 的 token 数和饼图（backend/modules/observability/domain/metric/entity/metric.go L51-L56）。
• 延迟类指标有 model_duration、model_ttft、model_tpot、tool_duration、service_duration（backend/modules/observability/domain/metric/entity/metric.go L66-L68、backend/modules/observability/domain/metric/entity/metric.go L80、backend/modules/observability/domain/metric/entity/metric.go L100）。
• 吞吐类指标有 QPS、QPM、TPS、TPM（backend/modules/observability/domain/metric/entity/metric.go L57-L65）。
• 反馈类指标有 feedback_count、feedback_score、feedback_value_distribution 和两个饼图，数据源是标注表（backend/modules/observability/domain/metric/entity/metric.go L110-L114、backend/modules/observability/domain/metric/entity/metric.go L29-L30）。
• 同一指标可套 avg、max、min、pct50、pct90、pct99、sum、time_series 包装器（backend/modules/observability/domain/metric/service/metric/model/model_duration_metric.go L55-L57）。
• 复合指标支持 divide 和 pie 算子（backend/modules/observability/domain/metric/entity/metric.go L117-L118、backend/modules/observability/domain/metric/service/metric.go L305-L370）。
• 在线指标直接查 ClickHouse span 表，SQL 由 buildMetricsSql 把过滤 SQL 包成子查询再聚合（backend/modules/observability/infra/repo/ck/spans.go L109-L166）。
• 指标权限动作是 readLoopIndictor（backend/modules/observability/domain/component/rpc/auth.go L22、backend/modules/observability/application/metric.go L53-L60）。
• 指标平台只配了 cozeloop 和 prompt 两个（release/deployment/docker-compose/conf/observability.yaml L64-L69）。
• 离线指标是空实现：OfflineMetricDaoImpl.GetMetrics 返回 nil, nil（backend/modules/observability/infra/repo/ck/metric.go L13-L25）。
• 离线开关 support_offline 默认 false，配置读取失败时也返回 false（release/deployment/docker-compose/conf/observability.yaml L71-L72、backend/modules/observability/infra/config/trace.go L235-L244、backend/modules/observability/domain/metric/service/metric.go L372-L376）。
• 大盘页面：无。前端业务源码里没有指标接口的调用，也没有图表页面。已在 frontend/packages/loop-pages、frontend/packages/loop-components/observation-components/src、frontend/apps/cozeloop/src 搜索 observabilityMetric、metrics/list，仅在生成的 API 客户端出现。
• 路由和菜单里观测只有一个 observation/traces 入口（frontend/apps/cozeloop/src/components/navbar/menu-config.tsx L87-L96、frontend/packages/loop-pages/observation-pages/src/app.tsx L9-L11）。
• 成本统计：无金额口径，只有 token 数量，见第一节。

九、告警与通知

• 无。已搜索的位置：backend/modules/observability、idl/thrift/coze/loop/observability、release/deployment/docker-compose/conf、release/deployment/docker-compose/bootstrap、frontend/packages/loop-pages/observation-pages、frontend/packages/loop-components/observation-components/src。
• 搜索词：alert、webhook、notif、告警、报警。
• 唯一相关命中在评测配置：实验有 expt_webhook_notify_event 队列，与 Trace 无关（release/deployment/docker-compose/conf/evaluation.yaml L80-L84）。
• 其余命中是进程信号 signal.Notify、UI 通知样式和代码注释里的「告警」字样，不是告警功能。