🪢 Langfuse 图解教程Langfuse Visual Guide 共 55 课 · 11 个部分55 lessons · 11 parts 📖 术语表📖 Glossary
面向工程师 · 从第一性原理到源码For engineers · first principles to source

用图解读懂整个 LangfuseUnderstand all of Langfuse, visually

这套教程带你层层深入:先建立宏观全景与可观测性 2.0 / 宽事件基础,看懂 trace/observation/score 数据模型与 Postgres+ClickHouse 双存储, 然后顺着数据走一遍摄取(写)与查询(读)两条链路,再逐个拆解评估·数据集·Prompt·仪表盘等子系统,最后讲透鉴权与权限·运维与如何贡献。每课配真实源码对应、手绘图与设计取舍。 A layered tour: build the big picture and the Observability 2.0 / wide-event foundation first, understand the trace/observation/score data model and the Postgres + ClickHouse dual store, then follow the data through the ingestion (write) and query (read) paths, take apart the evaluation, datasets, prompt and dashboard subsystems, and finally master auth & RBAC, operations and how to contribute. Every lesson maps to real source, with hand-drawn diagrams and design trade-offs.

宏观理解Big picture 细节 / 源码Details / source 生活类比Analogy 关键要点Key points

📌 对照 langfuse/langfuse 仓库真实源码核实 · 源码引用以“文件 + 符号名/行号”标注(行号随上游更新而变)📌 Verified against the real langfuse/langfuse source; references cite file + symbol/line (line numbers drift upstream)

第一部分 · 宏观全景Part 1 · The Big Picture
01Langfuse 是什么What is LangfuseLLM 可观测性 · trace/observation/score · 为何要这样一套平台LLM observability; trace/observation/score; why a platform like this 02可观测性 2.0 与宽事件Observability 2.0 & wide events可观测性 1.0 的困境 · 宽事件 · 十条原则 · unknown unknownsthe 1.0 trouble; wide events; the principles; unknown unknowns 03三大支柱深入:trace/observation/scoreThe three pillars in depthtrace 薄 · observation 厚(10 型·树)· score 两维 · 落到三张 CH 表thin trace; heavy observation (10 types, tree); score 2-D; three CH tables 04项目全景地图(monorepo 与窄腰)Project map (monorepo & narrow waist)monorepo · 四工作区 · 窄腰依赖 · Turbo 编排 · 高频目录速查monorepo; four workspaces; narrow-waist deps; Turbo; hot-dir cheat-sheet 05一条 trace 的一生·鸟瞰Life of a trace (bird's-eye)写:SDK→API→队列→worker→CH · 读:UI→tRPC→仓储→CH · 异步·最终一致write: SDK→API→queue→worker→CH; read: UI→tRPC→repo→CH; async; eventual consistency
第二部分 · 前置基础Part 2 · Foundations
06给 LLM 应用埋点Instrumenting an LLM app两个入口:SDK 原生事件 / OTel · 事件信封 · create+update 增量two entries: native SDK events / OTel; the event envelope; incremental create+update 07双存储架构The dual-store architecture四存储分工:PG 配置 · CH 宽事件 · Redis 队列/缓存 · S3 真相之源 · OLTP vs OLAPfour stores: PG config; CH wide events; Redis queue/cache; S3 source-of-truth; OLTP vs OLAP 08ClickHouse 与宽事件表ClickHouse & the wide-event tablesReplacingMergeTree · 排序键 project_id 打头 · 月分区 · ZSTD/Map/bloom · 少扫才是关键ReplacingMergeTree; ordering key project_id-first; monthly partitions; ZSTD/Map/bloom; scan-less 09元数据 schema(Postgres/Prisma)The metadata schema (Postgres)控制面 vs 数据面 · Project 枢纽 · 模型分组 · Legacy 残留 · API key 哈希control plane vs data plane; Project hub; model groups; Legacy remnants; hashed API keys 10多租户:org → project → environmentMulti-tenancy三层嵌套 org→project→env · project 硬隔离 · environment 软切片 · project_id 贯穿three levels org→project→env; hard project isolation; soft environment slice; project_id threaded 11部署拓扑与依赖Deployment topology2 应用 + 4 基础设施 · docker-compose · web vs worker · MinIO 替身 · env 启动即校验2 apps + 4 infra; docker-compose; web vs worker; MinIO stand-in; env validated at startup
第三部分 · 摄取链路Part 3 · The Ingestion Path
12摄取 APIThe ingestion API鉴权+Zod+入队 · processEventBatch · 攒批上报 · 两道关 · 快返回auth+Zod+enqueue; processEventBatch; batched reporting; two gates; fast return 13事件类型与合并语义Event types & merge semantics事件信封 · discriminatedUnion · body 继承链 · 两套 id · 合并最新者胜 · 18→3event envelope; discriminatedUnion; body inheritance; two ids; latest-wins merge; 18→3 14摄取队列The ingestion queueRedis+BullMQ · 队列放指针 fileKey · S3 存本体 · 分片 · 主/次队列 · 重试退避Redis+BullMQ; queue holds fileKey pointer; S3 stores body; sharding; primary/secondary; retry backoff 15IngestionService:合并的心脏IngestionService: the merge heartmergeAndWrite 分派 · S3 事件+CH 记录双输入 · mergeRecords 左折叠 · 只入队不直写mergeAndWrite dispatch; S3 events + CH record; mergeRecords left-fold; enqueue, never direct-write 16Token 计数与成本Token counting & costprovided 压倒 computed · findModel 正则匹配 · tokenizer 分词 · matchPricingTier 选档provided beats computed; findModel regex; tokenizer counting; matchPricingTier; price × units 17ClickhouseWriter:批量落盘ClickhouseWriter: batched persistence单例批写器 · 每表内存队列 · batchSize/writeInterval 双触发 · 批量 INSERT · 优雅排空 · 内存换吞吐(S3 兜底)singleton writer; per-table memory queues; batchSize/writeInterval triggers; bulk INSERT; graceful drain 18OpenTelemetry 摄取OpenTelemetry ingestionOTLP 端点 · protobuf/JSON · 万能适配器 · 优先级属性键 gen_ai/ai/llm · 映射成原生事件 · 边缘适配核心归一OTLP endpoint; protobuf/JSON; universal adapter; priority keys gen_ai/ai/llm; adapt-at-edge, unify-at-core 19媒体与 blob 存储Media & blob storage大二进制不进 ClickHouse · langfuseMedia 引用串 · presigned 直传 S3 · sha256 内容寻址去重big binaries stay out of ClickHouse; langfuseMedia reference; presigned direct S3 upload; sha256 dedup
第四部分 · 查询链路Part 4 · The Read Path
20web 应用架构The web app architectureNext.js Pages Router 为主 · 三种 API(tRPC/REST/App-Router) · 对内类型安全、对外契约稳定Next.js, mostly Pages Router; three APIs (tRPC/REST/App-Router); internal type-safety, external stability 21tRPC 骨架The tRPC backboneappRouter 聚合 ~64 路由 · context 注入 session/prisma · 可叠中间件栈 · 安全靠结构appRouter aggregates ~64 routers; context injects session/prisma; stackable middleware; security by structure 22仓储层:从 ClickHouse 读The repository layerqueryClickhouse 统一执行器 · OTel/log_comment 标签/退避重试/资源错误包装 · 回看时间窗 2天/1小时 · 流式变体queryClickhouse unified executor; OTel tags + backoff retry + resource-error wrap; look-back windows 2d/1h 23过滤·搜索栏·查询构建Filtering & the search barFilterState 中间契约 · 编译到 CH/PG 两套 SQL · 随机占位符防注入 · 搜索栏与 AI filter 同源FilterState contract; compiles to CH/PG SQL; random placeholders block injection; search bar & AI filter, one source 24列表与表格Lists & tables紧凑行 vs 指标双查并发 · 按 id 合并 · 按需 JOIN/FINAL · 表态以 URL 为真源compact rows vs metrics, parallel; merge by id; conditional JOIN/FINAL; table state as URL-truth 25trace 详情与观测树Trace detail & the observation tree全量取观测树 · 树与评分并行 · includeIO:false 懒加载 · verbosity 给巨型 trace 封顶fetch the whole tree; tree+scores in parallel; includeIO:false lazy-load; verbosity caps giant traces 26sessionsSessionssession = traces 按 session_id 分组聚合 · 派生视图非新实体 · 复用第 24 课表格机制session = traces grouped by session_id; a derived view, not a new entity; reuses Lesson 24's tables 27公共 REST APIThe public REST API路由工厂统一鉴权/限流/校验 · Redis 缓存+负缓存 · 文件夹版本 v1/v2/v3 · Fern 生成 SDKroute factory unifies auth/rate-limit/validation; Redis + negative caching; Fern generates SDKs
第五部分 · 评估与评分Part 5 · Evaluation & Scoring
28评分模型The scoring modelscore=评估原子单位 · 三种刻度 数值/分类/布尔 · config 是某 name 的 schema · 三来源同写 scores 表score = the atomic unit; three scales numeric/categorical/boolean; config is a name's schema; three sources, one table 29LLM 当裁判LLM-as-a-judge一个 LLM 给另一个评分 · 模板/评估器/执行 · 变量映射填占位符 · source=EVAL 回流摄取链路one LLM scores another; template/evaluator/execution; variable mapping fills placeholders; source=EVAL flows back 30eval 执行流水线The eval execution pipelinecreateEvalJobs 扇出到 ACTIVE 评估器 · 两级队列 · 三道闸 去重/采样/延迟 · 前缀防无限循环createEvalJobs fans out to ACTIVE evaluators; two-stage queues; three gates dedup/sampling/delay; prefix guards loops 31代码 evalCode-based evaluation确定性代码评估 vs LLM 概率判断 · dispatcher 策略模式 · 沙箱铁律 禁网络+限大小+超时deterministic code eval vs LLM judgment; dispatcher strategy; sandbox iron rules: no-network + size caps + timeout 32人工标注Human annotation第三种来源 source=ANNOTATION · 常作 ground truth 校准 AI · 标注队列绑 scoreConfigIds · 5 分钟软锁third source ANNOTATION; often ground truth to calibrate the AI; annotation queue binds scoreConfigIds; 5-min soft lock 33监控器与告警Monitors & alerting质量监测从拉变推(越线告警) · 复用 widget 查询 · severity 状态机 · 只在变化时告警quality monitoring from pull to push (alert); reuses a widget's query; severity state machine; alert only on change
第六部分 · 数据集与实验Part 6 · Datasets & Experiments
34数据集与数据项Datasets & items数据集=测试用例 · 题可从真实 trace 提拔 · 数据项 SCD Type2 版本化 · run 钉住版本保可复现a dataset = test cases; questions promotable from traces; items versioned SCD Type 2; a run pins the version 35数据集运行与运行项Dataset runs & run itemsrun=一场考试 · run item 钉 runId+itemId→traceId · upsert 自动触发评分 · 按 run 聚合均分a run = an exam; a run item pins runId+itemId→traceId; upsert auto-triggers scoring; aggregate scores per run 36实验与对比Experiments & comparison实验=prompt×数据集×模型,服务端自动跑 · 评分自动接 L30/35 · 对比靠 baseline+增量experiment = prompt × dataset × model, run server-side; scoring auto-connects (L30/35); compare via baseline + deltas
第七部分 · Prompt 与 PlaygroundPart 7 · Prompts & Playground
37Prompt 管理Prompt managementprompt = 专为 prompt 的 git · 版本不可变 · label 可移动指针(零部署发布/回滚) · 依赖可组合a prompt = git for prompts; immutable versions; a label is a movable pointer (zero-deploy release/rollback) 38Prompt 服务与缓存Prompt serving & caching生产每次调用都取 prompt 故须快 · Redis read-through · 服务时解析依赖内联 · epoch 失效 O(1)production fetches a prompt every call, so it must be fast; Redis read-through; epoch invalidation O(1) 39Playground 与 LLM 连接Playground & LLM connectionsPlayground=同一引擎的交互前台 · API key 用 AES-256-GCM 即用即解 · LlmSchema/LlmTool 可复用积木Playground = the engine's interactive front desk; API keys AES-256-GCM, decrypt-on-use; reusable blocks
第八部分 · 仪表盘·指标·成本Part 8 · Dashboards, Metrics & Cost
40仪表盘与 widget 系统Dashboards & widgets仪表盘=布局+一排 widget · widget=声明式查询+图表 · 查询与呈现解耦 · 一份查询形状三处复用a dashboard = layout + a row of widgets; widget = declarative query + chart; query and presentation decoupled 41查询引擎The query engine声明式查询→ClickHouse SQL 编译器 · 语义层映射逻辑名 · 值走 parameters 防注入 · 一引擎多消费a declarative-query → ClickHouse SQL compiler; a semantic layer maps logical names; one engine, many consumers 42模型与定价Models & pricing定价数据模型喂成本计算 · matchPattern 一条正则统一命名 · 默认档+条件档分级 · 规则即数据the pricing model feeds cost computation; matchPattern unifies naming via regex; default + conditional tiers 43云用量计量与花费Cloud usage metering & spendCloud 专属平台计费 · 按观测数每小时报 Stripe · 命门「恰好一次」cronJobs 锁+整点对齐+兜底接管Cloud-exclusive platform billing; meter usage events hourly to Stripe; exactly-once via cronJobs lock + hour-align
第九部分 · 自动化与集成Part 9 · Automation & Integrations
44自动化与 webhookAutomations & webhooks自动化 Trigger→Action · 命门是 SSRF · 纵深防御黑白名单+fail-closed · HMAC 签名+重试+自动停用automation Trigger→Action; the SSRF risk; defense-in-depth allow/blocklists; HMAC signing + retry 45Slack 与通知Slack & notificationsSlack 一等公民投递 · OAuth 把 bot 令牌加密入库 · 用时解密发 Block Kit 富消息 · 站内通知队列Slack as a first-class channel; the OAuth bot token stored encrypted; decrypt at use for Block Kit messages 46分析集成Analytics integrations把数据导回你的 PostHog/S3 · 三个同构集成 · 两级 fan-out 调度+处理 · 增量水位+按日切块流式导出export your data to PostHog/S3; three isomorphic integrations; two-level fan-out; incremental watermark 47批量导出与批量操作Batch exports & actions一个查询两条路:导出(只读产文件) vs 操作(改数据) · 流式+分块防内存爆 · 操作分块 1000+幂等one query, two paths: export (read-only file) vs action (mutate); stream + chunk to bound memory
第十部分 · 平台与运维Part 10 · Platform & Operations
48鉴权与会话Auth & sessions谁能进:鉴权=你是谁 · 密码(bcrypt)+十几种 SSO · 密码登录四护栏 · 会话=无状态 JWT 利于扩展who gets in: auth = who you are; password (bcrypt) + a dozen SSO; session = a stateless JWT that scales out 49RBAC · API key · SCIMRBAC, API keys & SCIM你能干什么:人走 RBAC、机器走 API key · 角色→scope,前后端双查 · API key 两层哈希 · SCIM 企业自动开通what you can do: humans via RBAC, machines via API keys; role→scope dual-checked; API-key two-tier hash 50开源核与权益Open-core & entitlements开源核:全代码开放,区别在运行时能否启用 · plan 分层 · entitlementAccess 总表+一道闸 · EE 许可证按前缀判open core: all code is open, the difference is runtime enablement; plan tiers via one entitlementAccess table 51自我可观测与配置Self-observability & config自我可观测 dogfooding · instrumentAsync span 包装器 · 每行日志盖 trace_id · 配置过 Zod 启动即校验self-observability (dogfooding) on the same OTel; instrumentAsync span wrapper; trace_id on every log line 52数据生命周期与删除Data lifecycle & deletion一条 trace 散在三存储,删除须一处不漏 · 删除有序先 CH+S3 后 PG · 三种删除 · 后台迁移在线做手术one trace spans three stores, deletion must miss none; ordered CH+S3 first, PG last; three deletion kinds 53构建·测试·开发流Build, test & dev workflow平台自己怎么构建/测试 · pnpm monorepo 依赖只朝下 · Turbo 拓扑序+内容哈希缓存 · 一键 dx 从空环境到能跑how the platform is built/tested; pnpm monorepo, deps point down; Turbo topological order + hash cache
第十一部分 · 设计专题与终章Part 11 · Design Themes & Capstone
54设计专题综合Design themes synthesis退一步收成六主题:宽事件/不可变/异步/双存储/多租户/成本 · 非六技巧而是一套世界观的六切面step back into six themes: wide events / immutability / async / dual storage / multi-tenancy / cost 55终章·一条 trace 的完整一生Capstone: the full life of a trace跟一条 trace 走完一生,把 55 课串成流水线 · 七驿站 · 三隐线 · trace→score 闭环反哺应用follow one trace through its whole life, stringing all 55 lessons; seven stations; three hidden threads
没有匹配的课程,换个关键词试试。No matching lessons, try another keyword.

本项目是第三方、非官方的学习材料,不含 Langfuse 源码(仅引用少量标注来源的片段);Langfuse 由其作者以 MIT 许可发布(部分企业版功能除外)。Third-party, unofficial learning material; contains no Langfuse source code beyond small, cited snippets. Langfuse is MIT-licensed by its authors (except some enterprise features).