Langfuse Practice
Langfuse 覆盖 observability、prompt management、evaluation、datasets、experiments、playground 和 API。能力很多，但落地时不建议一次性全部铺开。更稳妥的顺序是：先接入 trace，再设计 metadata，再建立失败样本回流，最后把 prompt 发布和评测门禁纳入团队流程。
| 阶段 | 目标 | 完成标志 |
|---|---|---|
| 接入期 | 让关键链路有 trace | 能定位一次坏回答经过了哪些步骤 |
| 结构化期 | 统一 trace schema 和 metadata | 能按业务、模型、prompt、检索配置切片 |
| 评测期 | 把失败样本沉淀为 dataset | 每次改动可运行 experiment 对比 |
| 治理期 | 把 prompt / model / eval 纳入发布流程 | 生产变更有记录、有指标、有回滚路径 |
Langfuse 的价值不只取决于工具本身，也取决于团队是否围绕它建立规则。对于生产级 LLM 应用，至少应该治理六类对象：trace schema、prompt 版本、模型配置、dataset、score 和 experiment。
治理清单
- Trace：关键链路必须有业务 metadata。
- Prompt：production label 的变更需要评审或实验记录。
- Model：模型供应商、版本、参数必须可回溯。
- Dataset：线上事故样本进入回归集。
- Score：区分用户反馈、人工标注、LLM judge 和规则评分。
- Experiment：重要变更用实验结果说话，而不是只看主观体验。
真正落地时，可以把 Langfuse 项目拆成四周推进，而不是一次性建设完整平台。第一周只保证关键链路有 trace；第二周统一 metadata；第三周接入 score 与 dataset；第四周把 prompt 发布和实验结果纳入变更流程。
| 周期 | 任务 | 验收方式 |
|---|---|---|
| 第 1 周 | 接入核心应用 trace，覆盖模型调用和检索调用 | 能打开任意线上请求的完整链路 |
| 第 2 周 | 统一 metadata、trace name、observation name | 能按场景、模型、prompt、tenant 切片 |
| 第 3 周 | 建立 score、annotation、dataset 回流 | 失败样本能进入回归集 |
| 第 4 周 | 绑定 prompt 版本、experiment 和发布流程 | 生产变更有指标、有记录、有回滚路径 |
| 失败模式 | 表现 | 修正方式 |
|---|---|---|
| 只接模型调用 | 看得到 LLM，但看不到检索和工具错误 | 补齐 retrieval、tool、post-processing observation |
| metadata 太少 | 无法按场景定位问题 | 强制写入 app、feature、tenant、prompt_version、model |
| eval 太主观 | 每次发布靠人工感觉 | 建立 dataset、score config 和 experiment 基线 |
| prompt 无治理 | 线上版本不清楚，回滚困难 | 用 label 管理 production，变更关联 experiment |
| 自托管无监控 | trace 延迟出现或查询变慢 | 监控 Web、Worker、Redis 队列、S3、ClickHouse |
Langfuse 自托管的关键路径包括 Web、S3、Redis、Worker、ClickHouse 和 Postgres。出现性能问题时，不要只看 Web CPU，而要先判断瓶颈发生在写入路径、队列路径、对象存储、后台消费，还是分析查询。#Langfuse Self Hosting, 2026
| 目标 | 优先检查 | 改进方向 |
|---|---|---|
| 降低接入开销 | SDK 上报方式、batch、采样 | 避免请求路径同步等待过多 |
| 提高写入可靠性 | S3、Redis、Worker lag | 保留原始事件并监控队列积压 |
| 提升查询速度 | ClickHouse 查询与容量 | 治理 dashboard 查询和冷热数据 |
| 保护敏感数据 | trace 输入、输出、metadata | 脱敏、最小权限、内网部署、密钥轮转 |
如果要直接参与 langfuse/langfuse，可以从四类贡献入手：新增框架或模型供应商集成；优化 ingestion、queue、ClickHouse 查询和后台任务；增强 evaluation、dataset、CI/CD 实验工作流；完善自托管文档、迁移脚本和故障排查案例。Langfuse 官方通过 GitHub Issues、Discussions、roadmap 和 changelog 与社区协作。#Langfuse GitHub, 2026 #Langfuse Docs, 2026
贡献前的阅读路线
先读 docker-compose.yml 理解运行组件，再读 web 和 worker 的 package 依赖理解职责边界，最后沿着一个具体功能阅读共享包和 API。不要一开始就全仓库扫读。
成熟的 LLM 应用不是一次上线后就结束，而是不断从线上行为中学习。Langfuse 最适合承担这条反馈链路：线上 trace 暴露问题，score 判断质量，dataset 保存案例，experiment 比较方案，prompt 或模型配置再发布回生产。
flowchart LR
Production[生产应用] --> Trace[Trace]
Trace --> Score[Score]
Score --> Dataset[Dataset]
Dataset --> Experiment[Experiment]
Experiment --> Release[Prompt / Model / Code Release]
Release --> Production参考来源
- Langfuse. (2026). Langfuse Overview. https://langfuse.com/docs
- Langfuse. (2026). Self-host Langfuse. https://langfuse.com/self-hosting
- Langfuse. (2026). langfuse/langfuse GitHub Repository. https://github.com/langfuse/langfuse