Self-Hosted · Open Source · MIT/EE

Langfuse 自建 LLM 可观测平台

ai-evals 教你"评什么、怎么评",Langfuse 教你"怎么让评估、trace、prompt、dataset 真正在生产跑起来"。从一条 docker compose 命令开始,到 Kubernetes 上日吞千万条 trace 的 ClickHouse 集群——十章把这套可观测系统端到端拉通,数据主权握在自己手里。

Trace / Span Prompt Management Dataset 回归 LLM-as-Judge ClickHouse Helm / K8s OpenTelemetry
开始学习 →
📊 10 章节 🧭 从 docker compose 到 K8s 生产 🚀 数据主权 + 深度定制

课程目录

一条自建路线:SaaS 对比 → 架构拆解 → 本地跑通 → SDK 接入 → Prompt/Dataset/Eval → K8s 部署 → 成本优化 → 端到端接入真实 Agent

Chapter 01
为什么要自建 LLM 可观测平台
SaaS(LangSmith / Braintrust / Helicone)对比自建(Langfuse / Phoenix / Arize)的取舍:数据主权、合规、成本曲线、定制 eval、与现有 OTel 栈共生。
选型自建 vs SaaS
Chapter 02
Langfuse 架构拆解
Web + API + Worker + ClickHouse + Postgres + Redis + S3,七个组件的职责、数据流、读写路径,看懂了才会选得准、调得出、扛得住。
架构ClickHouse
Chapter 03
一条命令本地跑通
docker compose up 十分钟起飞。组织、项目、API Key 体系,第一条 trace 怎么来的,UI 六大面板(Traces / Sessions / Users / Scores / Prompts / Datasets)各管什么。
docker compose第一条 trace
Chapter 04
SDK 接入:Python / TS / OpenTelemetry 三路
@observe 装饰器、context manager、低层 SDK;LangChain / LlamaIndex / OpenAI SDK 自动 instrumentation;OpenTelemetry OTLP 直送 Langfuse。
@observe自动 instrument
Chapter 05
Prompt Management:版本化与灰度
Prompt 当成代码版本化,label (production / staging) 做灰度,cache 设置、A/B 分桶、回滚策略,和 LangChain / LlamaIndex 运行时绑定。
Prompt as Code灰度
Chapter 06
Datasets:把生产 trace 变成回归集
从真实 trace 一键圈成 dataset item,CI 里用 dataset.runs() 跑评估,阈值卡回归,GitHub Actions 集成,基线文件进 Git。
DatasetCI 回归
Chapter 07
Evaluations:LLM-as-Judge 与自定义打分
内置 evaluators + 自定义 evaluator,在线(prod 采样)与离线(dataset 回归)两种模式;human annotation 队列与成本控制。
LLM-as-Judge人工标注
Chapter 08
生产部署:Kubernetes + Helm Chart
官方 Helm Chart 参数拆解,ClickHouse / Postgres 高可用,S3 / MinIO 对象存储,Ingress + TLS,zero-downtime 升级与备份。
HelmKubernetes
Chapter 09
性能与成本:扛住千万 trace/日
ClickHouse 分区 / TTL / Projection,S3 冷热分层,采样策略,trace 留存周期,100M events/月 的容量规划与成本公式。
ClickHouse 优化采样
Chapter 10
实战:把客服 Agent 接全链路可观测
复用 ai-agent 教程里的客服 Agent,从零接 Langfuse:trace + session + user + prompt 版本 + dataset 回归 + 在线 eval + 告警,端到端跑一遍。
端到端落地
读前须知
本教程假设你已读过 AI Evals 实战 或至少理解 trace / span / metric 这组 OpenTelemetry 概念。对 Docker、Kubernetes、Helm 有基础更顺;ClickHouse 从零讲,不需要前置经验。Python ≥ 3.10 / Node ≥ 20 任选其一即可做 SDK 章节。