跳到主要内容

Langfuse · 评分、指标与告警

约 8 分钟2,052 字更新于 2026/10/22

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

7. Score、人工标注、标注队列、LLM-as-judge​

7.1 Score 模型​

  • Score 来源 source 有 API、EVAL、ANNOTATION（packages/shared/src/domain/scores.ts L4，permalink）。
  • 公共创建接口只允许 API 与 ANNOTATION，EVAL 保留给内部评估器（packages/shared/src/domain/scores.ts L15，permalink）。
  • Score 数据类型 dataType 有 NUMERIC、CATEGORICAL、BOOLEAN、CORRECTION、TEXT（packages/shared/src/domain/scores.ts L46-L52，permalink）。
  • 来源为 ANNOTATION 时必须带 configId，CORRECTION 例外（packages/shared/src/domain/scores.ts L31，permalink）。
  • TEXT 类型最长 500 个字符（packages/shared/src/domain/scores.ts L44，permalink）。
  • ClickHouse scores 表有 trace_id（后改为可空）、observation_id、session_id、dataset_run_id、source、data_type、string_value、queue_id、execution_trace_id（packages/shared/clickhouse/migrations/canonical/0003_scores.up.sql L6-L15，permalink；session_id 见 packages/shared/clickhouse/migrations/canonical/0012_add_session_id_column_scores.up.sql L1，permalink；execution_trace_id 见 packages/shared/clickhouse/migrations/canonical/0030_add_eval_execution_trace_id_to_scores.up.sql L1，permalink）。
  • 所以 Score 可以挂在 Trace、Observation、Session 或 Dataset Run 上。
  • ScoreConfig（Postgres）定义评分配置：dataType（CATEGORICAL、NUMERIC、BOOLEAN、TEXT）、minValue、maxValue、categories、isArchived（packages/shared/prisma/schema.prisma L516-L528，permalink、packages/shared/prisma/schema.prisma L540-L545，permalink）。
  • 写入入口：公共 POST /api/public/scores，权限 scores:create（web/src/pages/api/public/scores/index.ts L22，permalink）；也可通过 ingestion 的 score-create 事件（见 2.1）。
  • 读取入口：公共 v1 /api/public/scores、v2 /api/public/v2/scores、v3 /api/public/v3/scores（web/src/pages/api/public/v2/scores/index.ts L19，permalink、web/src/pages/api/public/v3/scores/index.ts L8，permalink）。
  • v1 与 v2 在 events_only 下返回 404；v3 没有这个开关（v3 文件里无 rejectInEventsOnlyMode；已搜索 web/src/pages/api/public/v3/scores/index.ts）。
  • 评分分析页：/project/[projectId]/scores/analytics 与 score-analytics 特性目录（web/src/pages/project/[projectId]/scores/analytics.tsx L1，permalink、web/src/features/score-analytics/README.md L1，permalink）。
  • 评分表页：ScoresPage、ScoresTable（web/src/features/scores/ScoresTable.tsx L1，permalink）。

7.2 人工标注与标注队列​

  • 标注队列 AnnotationQueue 绑定一组 scoreConfigIds，名称在项目内唯一（packages/shared/prisma/schema.prisma L547-L560，permalink）。
  • 队列项 AnnotationQueueItem 的对象类型是 TRACE、OBSERVATION、SESSION；状态是 PENDING、COMPLETED；带锁字段 lockedAt、lockedByUserId（packages/shared/prisma/schema.prisma L565-L582，permalink、packages/shared/prisma/schema.prisma L596-L600，permalink）。
  • 队列可分配给用户：AnnotationQueueAssignment（packages/shared/prisma/schema.prisma L602-L614，permalink）。
  • 队列项 tRPC 有 createMany、deleteMany、complete、itemsByQueueId、unseenPendingItemCountByQueueId（web/src/features/annotation-queues/server/annotationQueueItemsRouter.ts L280，permalink、web/src/features/annotation-queues/server/annotationQueueItemsRouter.ts L419，permalink）。
  • 公共 API 有 /api/public/annotation-queues、[queueId]、assignments、items（web/src/pages/api/public/annotation-queues/index.ts L1，permalink、web/src/pages/api/public/annotation-queues/[queueId]/assignments.ts L1，permalink）。
  • 从 Trace 表批量加入队列走批量操作 trace-add-to-annotation-queue（见 5.3）。
  • Trace 详情页自带评审面板 TraceReviewPanel（web/src/features/traces/components/TraceReviewPanel.tsx L1，permalink）。
  • 页面：/project/[projectId]/annotation-queues（web/src/pages/project/[projectId]/annotation-queues/index.tsx L1，permalink）。
  • 评论 Comment 可挂在 TRACE、OBSERVATION、SESSION、PROMPT 上（packages/shared/prisma/schema.prisma L751-L756，permalink）；公共 API 有 /api/public/comments（web/src/pages/api/public/comments/index.ts L1，permalink）。

7.3 LLM-as-judge 与评估器​

  • 评估器类型 EvalTemplateType 有 LLM_AS_JUDGE、CODE、DECISION_MODEL、FACET（packages/shared/prisma/schema.prisma L1089-L1094，permalink）。
  • 评估器 Evaluator 带版本 EvaluatorVersion；规则 EvaluationRule 带 targetObject、filter、sampling、delay、idleTime、timeScope（packages/shared/prisma/schema.prisma L1156-L1176，permalink）。
  • 规则与评估器通过 EvaluationRuleEvaluatorAssignment 多对多，并带 variableMapping（packages/shared/prisma/schema.prisma L1181-L1199，permalink）。
  • 规则作用对象 EvalTargetObject 有 trace、dataset、event、experiment（packages/shared/src/features/evals/types.ts L116-L121，permalink）。
  • 执行记录是 JobExecution，状态有 COMPLETED、ERROR、PENDING、CANCELLED、DELAYED（packages/shared/prisma/schema.prisma L1201-L1207，permalink）。
  • 旧路径（trace 目标）：TraceUpsert 队列的处理器调用 createEvalJobs（worker/src/queues/evalQueue.ts L33，permalink）。
  • 新路径（observation 目标）：OTLP 处理器在写入 span 后调用 scheduleObservationEvals（worker/src/features/otel-ingestion/processOtelEvents.ts L134，permalink）。
  • scheduleObservationEvals 先用规则的过滤条件匹配，再用 span_id 做确定性采样（worker/src/features/evaluation/observationEval/scheduleObservationEvals.ts L115，permalink、worker/src/features/evaluation/observationEval/scheduleObservationEvals.ts L148，permalink）。
  • 内部环境（评估器自己产生的 trace）会被排除，避免评估器评估自己（worker/src/features/evaluation/observationEval/scheduleObservationEvals.ts L74，permalink）。
  • Worker 注册了 EvalExecutionQueue、SecondaryEvalExecutionQueue、CodeEvalExecutionQueue（worker/src/app.ts L49，permalink）。
  • 评估产生的 Score 来源是 EVAL，并通过 execution_trace_id 指向评估器自己的执行 Trace（见 7.1 的迁移 0030）。
  • 公共 API 有评估器与规则：/api/public/v2/evaluators、/api/public/v2/evaluation-rules（web/src/pages/api/public/v2/evaluators/index.ts L1，permalink、web/src/pages/api/public/v2/evaluation-rules/index.ts L1，permalink）。
  • 页面：/project/[projectId]/evals（含 rules、templates、default-model、remap）（web/src/pages/project/[projectId]/evals/rules.tsx L1，permalink）。
  • 批量对已有 observation 跑评估是批量操作 observation-run-batched-evaluation（见 5.3）。

8. Dashboard 与指标​

  • Dashboard 存 definition（JSON）与 filters；projectId 可空，代表 Langfuse 托管的 dashboard（packages/shared/prisma/schema.prisma L1630-L1652，permalink）。
  • DashboardWidget 存 view、dimensions、metrics、filters、chartType、chartConfig、minVersion（packages/shared/prisma/schema.prisma L1675-L1703，permalink）。
  • Widget 的 view 有 TRACES、OBSERVATIONS、SCORES_NUMERIC、SCORES_CATEGORICAL、SCORES_BOOLEAN（packages/shared/prisma/schema.prisma L1655-L1661，permalink）。
  • 图表类型有 LINE_TIME_SERIES、AREA_TIME_SERIES、BAR_TIME_SERIES、HORIZONTAL_BAR、VERTICAL_BAR、PIE、NUMBER、HISTOGRAM、PIVOT_TABLE（packages/shared/prisma/schema.prisma L1663-L1674，permalink）。
  • 查询引擎的 views 是 traces、observations、scores-numeric、scores-categorical、scores-boolean；公共 v2 的 viewsV2 去掉了 traces（packages/shared/src/features/query/types.ts L123-L131，permalink、packages/shared/src/features/query/types.ts L135-L141，permalink）。
  • 视图版本 v1、v2；v2 视图在 dataModel.ts 里声明为 events_*（如 events_traces）（packages/shared/src/features/query/types.ts L164，permalink、packages/shared/src/features/query/dataModel.ts L171，permalink）。
  • 查询由 QueryBuilder 编译、executeQuery 执行（packages/shared/src/features/query/server/queryBuilder.ts L1，permalink、packages/shared/src/features/query/server/queryExecutor.ts L92，permalink）。
  • Dashboard tRPC：allDashboards、getDashboard、createDashboard、updateDashboardDefinition、cloneDashboard、getHomeDashboard、setHomeDashboard、updateDashboardFilters、executeQuery、delete（web/src/features/dashboard/server/dashboard-router.ts L446，permalink、web/src/features/dashboard/server/dashboard-router.ts L601，permalink、web/src/features/dashboard/server/dashboard-router.ts L693，permalink）。
  • Widget tRPC：create、all、get、update、copyToProject、delete（web/src/server/api/routers/dashboardWidgets.ts L170，permalink）。
  • 项目首页有预设图表组件：延迟、模型成本、模型用量、用户（web/src/features/dashboard/components/home-preset-registry.tsx L1，permalink、web/src/features/dashboard/components/LatencyChart.tsx L1，permalink、web/src/features/dashboard/components/ModelCostTable.tsx L1，permalink、web/src/features/dashboard/components/ModelUsageChart.tsx L1，permalink）。
  • 图表库在 web/src/features/widgets/chart-library（web/src/features/widgets/chart-library/ARCHITECTURE.md L1，permalink）。
  • 公共 API：GET /api/public/metrics（v1）与 GET /api/public/v2/metrics，均调用 executeQuery（web/src/pages/api/public/metrics/index.ts L11，permalink、web/src/pages/api/public/v2/metrics.ts L10，permalink）。
  • v1 metrics 在 events_only 下返回 404（web/src/pages/api/public/metrics/index.ts L25，permalink）。
  • 另有按日汇总 GET /api/public/metrics/daily（web/src/pages/api/public/metrics/daily.ts L20，permalink）。
  • 另有不稳定接口 /api/public/unstable/dashboards 与 dashboard-widgets（web/src/pages/api/public/unstable/dashboards/index.ts L1，permalink）。
  • Cost、latency、usage 都是 observation 上的度量，通过上面的 measures 聚合（度量定义见 packages/shared/src/features/query/dataModel.ts L82，permalink）。

9. 告警、通知、Webhook、自动化​

9.1 Monitor（告警规则）​

  • Monitor 对一个指标做窗口聚合并与阈值比较：view、filters、metric、windowMs、cadenceMs、thresholdOperator、alertThreshold、warningThreshold（packages/shared/prisma/schema.prisma L1892-L1922，permalink）。
  • Monitor 的 view 只有 OBSERVATIONS、SCORES_NUMERIC、SCORES_CATEGORICAL、SCORES_BOOLEAN，没有 TRACES（packages/shared/prisma/schema.prisma L1869-L1874，permalink）。
  • 严重度有 PAUSED、UNKNOWN、NO_DATA、OK、WARNING、ALERT（packages/shared/prisma/schema.prisma L1876-L1883，permalink）。
  • 比较符有 GT、GTE、LT、LTE、EQ、NEQ（packages/shared/prisma/schema.prisma L1860-L1867，permalink）。
  • 处理器 MonitorProcessor 用 Dashboard 同一个 executeQuery 取标量结果（packages/shared/src/features/monitors/processor/processor.ts L17，permalink、packages/shared/src/features/monitors/processor/processor.ts L229，permalink）。
  • 处理时会读取 eventSource 为 monitor 且状态为 ACTIVE 的 Trigger，并据此生成 webhook 输入（packages/shared/src/features/monitors/processor/processor.ts L81-L82，permalink、packages/shared/src/features/monitors/processor/processor.ts L90，permalink）。
  • 调度器 MonitorScheduler 由 MonitorRunner（周期独占任务）驱动，投递到 MonitorQueue（worker/src/features/monitor-runner/index.ts L17，permalink、worker/src/app.ts L454，permalink）。
  • tRPC monitors：create、update、delete、get、all、count、suggestName、linkedEvaluatorAlerts 等（web/src/server/api/routers/monitors.ts L34，permalink、web/src/server/api/routers/monitors.ts L136，permalink）。
  • 页面：/project/[projectId]/alerts（web/src/pages/project/[projectId]/alerts/index.tsx L1，permalink）。

9.2 Automation（Trigger + Action）​

  • Trigger 有 eventSource、eventActions、filter、status（packages/shared/prisma/schema.prisma L1774-L1791，permalink）。
  • Action 类型有 WEBHOOK、SLACK、GITHUB_DISPATCH（packages/shared/prisma/schema.prisma L1815-L1820，permalink）。
  • Automation 把一个 Trigger 和一个 Action 绑在一起，AutomationExecution 记录执行（packages/shared/prisma/schema.prisma L1798-L1815，permalink）。
  • Trigger 的 eventSource 只有三种：prompt、monitor、project-notification（packages/shared/src/domain/automations.ts L5-L13，permalink）。
  • 也就是说，没有「Trace 创建」或「Score 创建」这类事件源。已搜索：packages/shared/src/domain/automations.ts 的枚举、packages/shared/src/server/repositories/automation-repository.ts 与 processor.ts 的 eventSource 用法。
  • Webhook 队列任务默认最多重试 5 次，指数退避，初始延迟 5 秒（packages/shared/src/server/redis/webhookQueue.ts L27-L31，permalink）。
  • Worker 的 webhooks.ts 同时处理 webhook、Slack 与 GitHub dispatch（worker/src/queues/webhooks.ts L128，permalink、worker/src/queues/webhooks.ts L174，permalink）。
  • 请求签名用 createSignatureHeader，头名 x-langfuse-signature（worker/src/queues/webhooks.ts L686，permalink）。
  • tRPC automations：getCountOfConsecutiveFailures、regenerateWebhookSecret、getAutomations 等（web/src/features/automations/server/router.ts L74，permalink）。
  • 页面：/project/[projectId]/automations（web/src/pages/project/[projectId]/automations.tsx L1，permalink）。

9.3 通知​

  • ProjectNotification 是一类事件源，路由「平台出错」事件到通知渠道（packages/shared/src/domain/automations.ts L8，permalink）。事件类型目前有 blob-export-failed、posthog-export-failed、evaluator-blocked（packages/shared/src/domain/automations.ts L30-L34，permalink）。
  • 分发函数是 dispatchProjectNotification（packages/shared/src/server/notifications/dispatchProjectNotification.ts L74，permalink）。
  • Slack 集成：SlackIntegration 表存加密的 bot token，一个项目对应一个 Slack 工作区（packages/shared/prisma/schema.prisma L1945-L1957，permalink）。
  • Slack OAuth 路由是 /api/public/slack/install 与 /api/public/slack/oauth（web/src/pages/api/public/slack/install/index.ts L1，permalink）。
  • 评论里的 @提及由 commentMentionHandler 处理，用户通知偏好是 NotificationPreference（worker/src/features/notifications/commentMentionHandler.ts L1，permalink、packages/shared/prisma/schema.prisma L768-L778，permalink）。
  • 云端有支出告警 CloudSpendAlert（packages/shared/prisma/schema.prisma L2002-L2014，permalink）。