跳到主要内容

Langfuse · 联动、治理与前端

约 6 分钟1,455 字更新于 2026/10/22

本页覆盖：与 Prompt、评测、数据集联动，权限与隔离，前端页面。每条事实链到固定提交（f75c661d）。回到 Langfuse 总览。

10. 与 Prompt、数据集、实验的联动​

10.1 Prompt​

  • Prompt 存在 Postgres Prompt 表，按 (projectId, name, version) 唯一（packages/shared/prisma/schema.prisma L786-L812，permalink）。
  • Observation 上记录 prompt_id、prompt_name、prompt_version（旧表：packages/shared/clickhouse/migrations/canonical/0002_observations.up.sql L25-L27，permalink；events_full：packages/shared/clickhouse/migrations/canonical/0039_create_events_full.up.sql L31-L33，permalink）。
  • OTLP 属性 langfuse.observation.prompt.name 与 langfuse.observation.prompt.version 带入这些列（packages/shared/src/server/otel/attributes.ts L28，permalink、packages/shared/src/server/otel/attributes.ts L29，permalink）。
  • 写入校验：promptName 与 promptVersion 要么同时给，要么都不给（packages/shared/src/server/ingestion/types.ts L536，permalink）。
  • 按 Prompt 统计 observation 数用 uniq(span_id) 按 prompt_name 分组（packages/shared/src/server/repositories/events.ts L675，permalink）。
  • Prompt 指标页：/project/[projectId]/prompts/metrics（web/src/features/prompts/PromptMetricsPage.tsx L1，permalink）。
  • Trace 详情里有 PromptBadge（web/src/features/traces/components/PromptBadge.tsx L1，permalink）。
  • Prompt 变更先进入 EntityChangeQueue，再由 promptVersionProcessor 匹配 prompt 事件源的 Trigger（web/src/features/prompts/server/promptChangeEventSourcing.ts L12，permalink、worker/src/features/entityChange/promptVersionProcessor.ts L40，permalink）。

10.2 数据集与实验​

  • Dataset、DatasetItem、DatasetRuns 在 Postgres（packages/shared/prisma/schema.prisma L626-L629，permalink、packages/shared/prisma/schema.prisma L692-L695，permalink）。
  • 数据集运行项在 ClickHouse dataset_run_items_rmt，带 trace_id 与可空的 observation_id，把一次运行关联到具体 Trace（packages/shared/clickhouse/migrations/canonical/0024_dataset_run_items.up.sql L8-L9，permalink）。
  • events_full 里直接带实验字段：experiment_id、experiment_name、experiment_dataset_id 等（packages/shared/clickhouse/migrations/canonical/0039_create_events_full.up.sql L69-L74，permalink）。
  • OTLP 属性 langfuse.experiment.* 带入这些字段（packages/shared/src/server/otel/attributes.ts L46，permalink）。
  • 实验在 Worker 里由 ExperimentCreate 队列创建（worker/src/app.ts L532，permalink）。
  • 实验服务引入 scheduleExperimentObservationEvals 来调度实验评估（worker/src/features/experiments/experimentServiceClickhouse.ts L45，permalink、worker/src/features/experiments/scheduleExperimentEvals.ts L13，permalink）。
  • 页面：/project/[projectId]/datasets、/experiments、/experiments/results（web/src/pages/project/[projectId]/experiments/index.tsx L1，permalink、web/src/pages/project/[projectId]/experiments/results.tsx L1，permalink）。
  • 数据集可以配置「远程实验」回调：remoteExperimentUrl 等（packages/shared/prisma/schema.prisma L632，permalink）。
  • 批量把 observation 加入数据集是批量操作 observation-add-to-dataset（见 5.3）。
  • 数据集运行项公共 API：/api/public/dataset-run-items，该端点在 events_only 下返回 404（web/src/pages/api/public/dataset-run-items.ts L50，permalink）。

11. 权限、项目隔离、RBAC、保留、公开分享​

11.1 RBAC​

  • 角色有 OWNER、ADMIN、MEMBER、VIEWER、NONE（packages/shared/prisma/schema.prisma L493-L499，permalink）。
  • 项目权限用 scope 字符串表达，如 traces:read、traces:delete、scores:CUD、annotationQueues:CUD、dashboards:CUD、batchExports:create、automations:CUD（packages/shared/src/features/rbac/projectAccessRights.ts L14，permalink、packages/shared/src/features/rbac/projectAccessRights.ts L47，permalink、packages/shared/src/features/rbac/projectAccessRights.ts L82，permalink）。
  • 角色到 scope 的映射是 projectRoleAccessRights（packages/shared/src/features/rbac/projectAccessRights.ts L105，permalink）。
  • 服务端用 throwIfNoProjectAccess 检查 scope（web/src/features/rbac/utils/checkProjectAccess.ts L25，permalink）。
  • 公开与收藏有独立 scope：objects:publish、objects:bookmark（web/src/server/api/routers/traces.ts L637，permalink、web/src/server/api/routers/traces.ts L577，permalink）。
  • tRPC 过程基线是 protectedProjectProcedure，要求登录且是项目成员（web/src/server/api/trpc.ts L424，permalink）。
  • Trace 的收藏、公开、删除等写操作会调用 auditLog（web/src/server/api/routers/traces.ts L580，permalink、web/src/server/api/routers/traces.ts L644，permalink）。
  • AuditLog 表的 resourceType 是字符串，不建外键（packages/shared/prisma/schema.prisma L981-L1003，permalink）。
  • 审计日志也能批量导出（BatchTableNames.AuditLogs，见 5.2）。
  • 公共 API 的 API Key 有项目级与组织级，权限范围见 apiKeyAccessRights.ts（web/src/features/rbac/constants/apiKeyAccessRights.ts L1，permalink）。

11.2 项目隔离​

  • traces 与 events_full 的排序键都以 project_id 开头（traces：packages/shared/clickhouse/migrations/canonical/0001_traces.up.sql L28-L29，permalink；events_full：packages/shared/clickhouse/migrations/canonical/0039_create_events_full.up.sql L112-L115，permalink）。
  • Postgres 的多数业务表带 projectId，并 onDelete: Cascade 到 Project（例：packages/shared/prisma/schema.prisma L516-L523，permalink）。
  • 公共 API 的项目由 API Key 决定，路由里用 auth.scope.projectId（web/src/pages/api/public/sessions/index.ts L30，permalink）。
  • 新的查询编译器 query-ast 强制注入 project_id 条件（见 4.4），但目前只有 environments.ts 在用。

11.3 数据保留​

  • 项目级 retentionDays 最小值是 3 天，且需要 data-retention 权益（web/src/features/projects/server/projectsRouter.ts L147，permalink、web/src/features/projects/server/projectsRouter.ts L158，permalink）。
  • 其余保留与删除机制见 3.4。

11.4 公开分享​

  • Trace 有 public 标志，通过 traces.publish 修改（web/src/server/api/routers/traces.ts L625，permalink）。
  • Session 有 public 标志（packages/shared/prisma/schema.prisma L508，permalink）。
  • 未登录或非项目成员访问 Trace，只要 Trace 公开或其 Session 公开，就放行（web/src/server/api/trpc.ts L630-L640，permalink）。
  • 公开页面路由：/trace/[traceId] 与 /public/traces/[traceId]（web/src/pages/trace/[traceId].tsx L1，permalink、web/src/pages/public/traces/[traceId].tsx L1，permalink）。
  • 公开开关组件是 publish-object-switch.tsx（web/src/components/publish-object-switch.tsx L1，permalink）。
  • 实例管理员（user.admin）读取非自己项目的 Trace 时，会发送管理员访问 webhook（web/src/server/api/trpc.ts L649，permalink）。

12. 前端页面与组件​

  • 页面路由在 web/src/pages/project/[projectId]/：traces、observations、sessions、users、scores、dashboards、widgets、alerts、automations、annotation-queues、datasets、experiments、evals、prompts、models、playground（web/src/pages/project/[projectId]/traces/index.tsx L1，permalink、web/src/pages/project/[projectId]/dashboards/index.tsx L1，permalink、web/src/pages/project/[projectId]/models.tsx L1，permalink）。
  • Trace 列表页根据 isV4 选表：v4 用 ObservationsEventsTable，否则用 TracesTable（web/src/features/traces/TracesPage.tsx L97-L107，permalink）。
  • 旧表 TracesTable 调 api.traces.all、countAll、metrics（web/src/features/traces/TracesTable.tsx L525，permalink、web/src/features/traces/TracesTable.tsx L531，permalink）。
  • v4 表数据 hook 调 api.events.all、countAll、batchIO（web/src/features/events/hooks/useEventsTableData.ts L106，permalink、web/src/features/events/hooks/useEventsTableData.ts L245，permalink、web/src/features/events/hooks/useEventsTableData.ts L192，permalink）。
  • Observation 列表页在 tracing-tables/observations（web/src/pages/project/[projectId]/observations/index.tsx L1，permalink）。
  • Trace 详情页 TracePage 由 TraceDetailBody、TraceDetailActions 和 hook useTraceDetailData 组成（web/src/features/traces/TracePage.tsx L7，permalink）。
  • v4 详情用 hook useEventsTraceData 调 events.byTraceId、events.batchIO、events.scoresForTrace（web/src/features/events/hooks/useEventsTraceData.ts L62，permalink、web/src/features/events/hooks/useEventsTraceData.ts L130，permalink）。
  • 详情内的主要组件：TraceTree、VirtualizedTree、TraceTimelineDense、TraceGraphView、TraceLogView、TraceMessagesView、TracePanelDetail、TraceReviewPanel、ObservationDetailView、IOPreview、PromptBadge（目录见 web/src/features/traces/components/TraceTree.tsx L1，permalink、web/src/features/traces/components/TraceReviewPanel.tsx L1，permalink）。
  • 图视图在独立特性目录 trace-graph-view（web/src/features/trace-graph-view/components/TraceGraphView.tsx L1，permalink）。
  • 过滤器特性在 web/src/features/filters，排序在 orderBy，全文搜索栏在 search-bar，自然语言过滤在 natural-language-filters（web/src/features/filters/index.ts L1，permalink、web/src/features/orderBy/index.ts L1，permalink、web/src/features/search-bar/index.ts L1，permalink、web/src/features/natural-language-filters/server/router.ts L1，permalink）。
  • Dashboard 特性：DashboardDetailPage、DashboardsPage、ProjectHomePage；Widget 特性：NewWidgetPage、EditWidgetPage、WidgetsPage（web/src/features/dashboard/DashboardDetailPage.tsx L1，permalink、web/src/features/widgets/NewWidgetPage.tsx L1，permalink）。
  • Score 特性：ScoresPage、ScoresTable、ScoresAnalyticsPage（web/src/features/scores/ScoresAnalyticsPage.tsx L1，permalink）。
  • Session 特性：SessionsPage、SessionsTable、SessionDetailPage（web/src/features/sessions/SessionsTable.tsx L1，permalink）。
  • v4 迁移引导：v4-migration 特性与页面 /v4-migration（web/src/pages/v4-migration.tsx L1，permalink）。
  • 设计系统组件在 web/src/components/design-system。