(找了一圈发现没有资料发现没人写这个边缘业务自己写一个。。欢迎菜鸡互啄大佬勿喷本次副本使用的是langfuseV3。GitHub - langfuse/langfuse at v3.224.4 · GitHubLangfuse V3 是面向大规模生产环境重构的 LLM 可观测平台。同类产品还有langsmith。个人认为对于国内所有需要用到ai的企业都不会去使用国外在线的langsmith去托管数据。。。1. 整体概述核心设计思想冷热数据分层存储、读写链路解耦、同步接收 异步消费。相较于 V2 单体架构V3 拆分为 Web 服务 Worker 异步消费集群引入 ClickHouse、Redis、对象存储解决 V2 单 PostgreSQL 承载全量日志带来的写入阻塞、查询性能瓶颈。2. 组件总览langfuse/web主要是langfuse的Web 应用服务框架用的是Next.js tRPC主要实现了前端页面、鉴权、SDK 上报入口、前端所有操作 APIDataset 上传、评测任务、REST 开放接口相关功能。langfuse/worker是langfuse异步任务消费者主要包括BullMQ 队列消费、事件解析、Token 计算、后台评估任务、报表计算、数据迁移任务。PostgreSQL是langfuse的OLTP 事务数据库存储的数据包括用户、项目、密钥、Prompt 模板、Dataset 测评集、评测项、权限配置结构化元数据ClickHouse是langfuse的OLAP 时序分析库存储的数据包括Trace、Observation、Score、指标统计海量 LLM 调用日志Redis是langfuse的消息队列 缓存组件技能包括BullMQ 任务队列、分布式锁、热点数据缓存。S3/MinIO是langfuse的对象存储组件主要负责二进制存储技能包括原始上报事件载荷、超长文本、多模态附件、导出文件。最小部署缺一不可Web Worker PG Redis ClickHouse对象存储生产环境强制要求。3. 核心数据流3.1 LLM 追踪上报链路Ingest 链路SDK 上报自定义 Trace客户端 SDK 上报 Trace 事件 → Web 服务Web 完成鉴权、基础参数校验原始事件写入对象存储仅将事件索引推入 Redis 队列立刻返回 HTTP 响应Worker 进程轮询 Redis 队列拉取事件索引从 S3 读取完整事件数据Worker 执行分片合并、Token 统计、数据清洗结构化观测数据写入 ClickHouse少量关联元数据按需写入 PostgreSQL特点入口同步、处理异步极大提升接口吞吐避免大批量上报压垮 Web 服务。3.2 Dataset 测评集操作数据流CSV 批量导入、样本增删本次二次开发核心链路重点该流程不经过 Worker、不经过 ClickHouse、不经过 S3用户前端上传 CSV 测评集文件 → Web 前端组件请求转发至 Web 服务内部 tRPC 批量上传接口服务端解析 CSV组装 DatasetItem 数据通过 Prisma 直接操作 PostgreSQL 读写测评集数据返回导入、新增条目结果至前端改造点在 tRPC 接口增加前置 Hash 校验实现重复样本自动跳过仅改动 Web 模块无底层存储变更。3.3 Annotation 人工标注人评模块数据流前端页面发起标注操作新增 / 修改评分、人工备注→ Web tRPC 接口参数校验完成后Prisma 写入 PostgreSQL 存储标注元数据同时同步更新 ClickHouse 内对应 Observation 关联 Score 记录无需异步 Worker 参与大规模批量评估任务才会下发至 Worker 队列。3.4 自动化评估 模型对比任务数据流前端创建评测任务Dataset 运行模型对比、批量自动打分→ Web tRPCWeb 校验配置后将评估任务推送至 Redis BullMQ 队列Worker 消费任务读取 PostgreSQL 中的 Dataset 测评样本调用目标 LLM 执行推理生成输出结果评估指标计算完成后评测结果存入 PostgreSQL评估任务配置、对比汇总元数据单条推理 Trace、打分 Score 写入 ClickHouse 任务结束后前端可查看多模型对比报表、导出评测结果。3.5 数据导出 / 下载数据流Trace、测评报告、模型对比结果导出前端发起导出请求 → Web tRPC 接口小型导出Web 进程直接查询 PG/ClickHouse在线组装文件返回超大批量导出任务投递 Redis 队列由 Worker 执行查询、生成文件文件持久化至 S3生成完毕后推送前端下载链接。3.6 Prompt 管理数据流Prompt 模板新增、版本切换前端维护 Prompt 模板 → Web tRPC 接口Prisma 操作 PostgreSQL 持久化所有 Prompt 及版本信息推理时 SDK 通过 REST 接口拉取 Prompt 配置无 Worker、ClickHouse 参与。4. 分层存储详细设计4.1 PostgreSQLOLTP事务优先存储内容租户、组织、项目、API 密钥、成员权限Prompt 模板、Prompt 版本Dataset测评集、DatasetItem测评样本 input/output人工评分配置、评估任务配置特征强事务、数据量可控、频繁变更不适合存储亿万级 Trace 日志。4.2 ClickHouseOLAP查询分析优先存储内容Trace整条调用链路ObservationLLM 调用、工具调用Score自动 / 人工打分结果各类统计指标特征追加写入、极少更新面向仪表盘筛选、检索、聚合统计。4.3 RedisBullMQIngest 事件队列、后台评估任务队列、定时任务应用缓存项目配置缓存、权限缓存4.4 S3/MinIO原始未结构化事件报文、超大文本、图片等多模态数据、报表导出文件。5. 代码架构分层二次开发视角5.1前端层Next.js App Router页面组件、CSV 上传交互、表单校验、tRPC 客户端调用。5.2API 层tRPC运行在 Web 容器所有前端操作入口Dataset 增删改查、批量导入、评测启动。5.3共享包 langfuse/shared类型定义、通用工具、Hash 工具、数据模型前后端共享。5.4数据库访问层Prisma Client操作 PostgreSQLDataset、元数据Kysely操作 ClickHouse观测日志查询5.5Worker 任务层独立进程消费 Redis 任务与 Web 进程代码隔离。
