从零了解 Langfuse 2：整体架构与核心模块

从零了解 Langfuse 2：整体架构与核心模块

如果第 1 篇解决的是"Langfuse 里有哪些概念"，这一篇解决的是另一个更重要的问题：这些能力到底是怎么组织在一起的？
本文基于 Langfuse 2026 年当前官方文档整理。Langfuse 迭代较快，具体页面入口、字段名和版本要求请以官方最新文档为准。

---

1. 先看 Langfuse 的整体定位

Langfuse 可以理解成面向 LLM / Agent 应用的一套 AI Engineering 平台。它并不是只做 Trace，也不是只做 Prompt 管理，而是把 AI 应用从开发、调试、评估到生产监控串在一起。

从功能上可以拆成五块：

Langfuse
├── Observability      可观测
├── Prompt Management Prompt 管理
├── Evaluation         评估
├── Dataset/Experiment 数据集与实验
└── Metrics/Dashboard  指标与看板

如果用一句话区分它们：

• Observability：发生了什么？
• Prompt Management：模型到底使用了哪个 Prompt？
• Evaluation：结果好不好？
• Dataset / Experiment：改完之后是不是比之前更好？
• Dashboard / Metrics：整体质量、成本和性能趋势怎么样？

---

2. 产品能力之间是什么关系

一个典型 AI 应用的生命周期可以画成：
#mermaid-svg-j9Dm1YSA2a4sMx8q{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-j9Dm1YSA2a4sMx8q .error-icon{fill:#552222;}#mermaid-svg-j9Dm1YSA2a4sMx8q .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-j9Dm1YSA2a4sMx8q .marker{fill:#333333;stroke:#333333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .marker.cross{stroke:#333333;}#mermaid-svg-j9Dm1YSA2a4sMx8q svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-j9Dm1YSA2a4sMx8q p{margin:0;}#mermaid-svg-j9Dm1YSA2a4sMx8q .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .cluster-label text{fill:#333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .cluster-label span{color:#333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .cluster-label span p{background-color:transparent;}#mermaid-svg-j9Dm1YSA2a4sMx8q .label text,#mermaid-svg-j9Dm1YSA2a4sMx8q span{fill:#333;color:#333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .node rect,#mermaid-svg-j9Dm1YSA2a4sMx8q .node circle,#mermaid-svg-j9Dm1YSA2a4sMx8q .node ellipse,#mermaid-svg-j9Dm1YSA2a4sMx8q .node polygon,#mermaid-svg-j9Dm1YSA2a4sMx8q .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-j9Dm1YSA2a4sMx8q .rough-node .label text,#mermaid-svg-j9Dm1YSA2a4sMx8q .node .label text,#mermaid-svg-j9Dm1YSA2a4sMx8q .image-shape .label,#mermaid-svg-j9Dm1YSA2a4sMx8q .icon-shape .label{text-anchor:middle;}#mermaid-svg-j9Dm1YSA2a4sMx8q .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-j9Dm1YSA2a4sMx8q .rough-node .label,#mermaid-svg-j9Dm1YSA2a4sMx8q .node .label,#mermaid-svg-j9Dm1YSA2a4sMx8q .image-shape .label,#mermaid-svg-j9Dm1YSA2a4sMx8q .icon-shape .label{text-align:center;}#mermaid-svg-j9Dm1YSA2a4sMx8q .node.clickable{cursor:pointer;}#mermaid-svg-j9Dm1YSA2a4sMx8q .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .arrowheadPath{fill:#333333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-j9Dm1YSA2a4sMx8q .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-j9Dm1YSA2a4sMx8q .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-j9Dm1YSA2a4sMx8q .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-j9Dm1YSA2a4sMx8q .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-j9Dm1YSA2a4sMx8q .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-j9Dm1YSA2a4sMx8q .cluster text{fill:#333;}#mermaid-svg-j9Dm1YSA2a4sMx8q .cluster span{color:#333;}#mermaid-svg-j9Dm1YSA2a4sMx8q div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-j9Dm1YSA2a4sMx8q .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-j9Dm1YSA2a4sMx8q rect.text{fill:none;stroke-width:0;}#mermaid-svg-j9Dm1YSA2a4sMx8q .icon-shape,#mermaid-svg-j9Dm1YSA2a4sMx8q .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-j9Dm1YSA2a4sMx8q .icon-shape p,#mermaid-svg-j9Dm1YSA2a4sMx8q .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-j9Dm1YSA2a4sMx8q .icon-shape .label rect,#mermaid-svg-j9Dm1YSA2a4sMx8q .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-j9Dm1YSA2a4sMx8q .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-j9Dm1YSA2a4sMx8q .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-j9Dm1YSA2a4sMx8q :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 用户请求
Agent / LLM 应用
Observability
Trace / Observation / Session
Evaluation
Score
Dataset
Experiment
Prompt / Model / Code 调整
Dashboard

这也是 Langfuse 与普通 APM 最大的差异之一：

普通 APM 往往止步于"看见问题"，Langfuse 还试图把"发现问题 → 形成测试集 → 重新实验 → 验证优化"串成闭环。

---

3. Observability：可观测模块

Langfuse 的可观测模型主要围绕三个对象：

Session
  ↓
Trace
  ↓
Observation

Trace

一次完整操作。例如：

用户：帮我查询账户余额
        ↓
Agent
        ↓
Model
        ↓
Tool
        ↓
MCP Server
        ↓
Model
        ↓
最终回答

整个过程可以作为一个 Trace。

Observation

Trace 里的某一个步骤，例如：

MODEL_INFER
TOOL_EXEC
RETRIEVAL
AGENT
EMBEDDING

Langfuse 允许 Observation 嵌套，因此可以表达真实的 Agent 调用树。

Session

多个 Trace 组成一次完整会话。

例如：

Session ABC
├── Trace 1：用户查询余额
├── Trace 2：用户继续问最近流水
└── Trace 3：用户继续问某笔交易详情

---

4. Prompt Management：Prompt 管理模块

Prompt 在 AI 应用里逐渐变成一种"配置资产"。

传统做法：

String systemPrompt = "你是一个银行业务助手......";

问题是每次改 Prompt 都要：

修改代码 → Code Review → 构建 → 发布

Langfuse 把 Prompt 独立出来：

Prompt
├── Name
├── Type
├── Variables
├── Version
├── Label
└── Config

核心能力包括：

• Text / Chat Prompt
• {``{variable}} 动态变量
• 自动版本管理
• production、latest 和自定义 Label
• 版本 Diff
• 回滚
• Prompt 与 Trace 关联
• Prompt Experiment

于是 Prompt 可以独立于应用代码持续迭代。

---

5. Evaluation：评估模块

Observability 告诉我们：

模型做了什么？

Evaluation 进一步回答：

模型做得对不对？

Langfuse 支持多种评估方式：

方式	适合场景
LLM-as-a-Judge	语义正确性、相关性、帮助程度、语气
Code Evaluator	JSON、字段、规则、Tool 调用等确定性判断
Annotation Queue	人工评审、专家标注
API / SDK Scores	接入企业已有评估平台

最终都沉淀成：

Score

Score 可以挂在 Trace、Observation、Session 或 Dataset Run 上。

---

6. Dataset：测试数据集

Dataset 可以理解成：

AI 应用的测试用例集。

例如：

账户 Agent 测试集
├── 查询账户余额
├── 查询最近三笔流水
├── 查询开户行
├── 模糊表达余额查询
└── 不应该调用 Tool 的闲聊问题

每一条：

Dataset Item

就是一条测试用例。

常见结构：

{
  "input": {"question": "查询账户余额"},
  "expectedOutput": {"expectedTool": "queryAccountBalance"},
  "metadata": {"priority": "P0", "scene": "账户查询"}
}

---

7. Experiment：实验模块

Experiment 用于回答：

Prompt V2、Model B 或新 Agent 逻辑，到底有没有比原来更好？

流程：

Dataset
   ↓
Task
   ↓
Actual Output
   ↓
Evaluator
   ↓
Scores
   ↓
Experiment Run

例如：

指标	Prompt V1	Prompt V2
Tool 正确率	91%	97%
回答正确率	89%	95%
平均延迟	2.1s	1.8s
Token	2200	1800

这样 Prompt 优化就不再依赖主观感觉。

---

8. Dashboard 与 Metrics

Langfuse 可以把 Trace、Observation 和 Score 聚合成 Dashboard。

典型关注项：

Traces
Model Cost
Latency
Scores
Model Usage
Token Usage

Dashboard 可以进一步按：

User
Model
Trace Name
Tags
Time
Environment

进行聚合和过滤。

所以 Dashboard 更偏向：

运营与生产质量视角。

---

9. 自托管架构

如果使用 Langfuse Cloud，这部分基础设施由官方维护；如果自托管，则需要理解后端组件。

当前 Langfuse 自托管架构主要包括：
#mermaid-svg-6b04s5ioY8yq2vis{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-6b04s5ioY8yq2vis .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-6b04s5ioY8yq2vis .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-6b04s5ioY8yq2vis .error-icon{fill:#552222;}#mermaid-svg-6b04s5ioY8yq2vis .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-6b04s5ioY8yq2vis .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-6b04s5ioY8yq2vis .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-6b04s5ioY8yq2vis .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-6b04s5ioY8yq2vis .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-6b04s5ioY8yq2vis .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-6b04s5ioY8yq2vis .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-6b04s5ioY8yq2vis .marker{fill:#333333;stroke:#333333;}#mermaid-svg-6b04s5ioY8yq2vis .marker.cross{stroke:#333333;}#mermaid-svg-6b04s5ioY8yq2vis svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-6b04s5ioY8yq2vis p{margin:0;}#mermaid-svg-6b04s5ioY8yq2vis .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-6b04s5ioY8yq2vis .cluster-label text{fill:#333;}#mermaid-svg-6b04s5ioY8yq2vis .cluster-label span{color:#333;}#mermaid-svg-6b04s5ioY8yq2vis .cluster-label span p{background-color:transparent;}#mermaid-svg-6b04s5ioY8yq2vis .label text,#mermaid-svg-6b04s5ioY8yq2vis span{fill:#333;color:#333;}#mermaid-svg-6b04s5ioY8yq2vis .node rect,#mermaid-svg-6b04s5ioY8yq2vis .node circle,#mermaid-svg-6b04s5ioY8yq2vis .node ellipse,#mermaid-svg-6b04s5ioY8yq2vis .node polygon,#mermaid-svg-6b04s5ioY8yq2vis .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-6b04s5ioY8yq2vis .rough-node .label text,#mermaid-svg-6b04s5ioY8yq2vis .node .label text,#mermaid-svg-6b04s5ioY8yq2vis .image-shape .label,#mermaid-svg-6b04s5ioY8yq2vis .icon-shape .label{text-anchor:middle;}#mermaid-svg-6b04s5ioY8yq2vis .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-6b04s5ioY8yq2vis .rough-node .label,#mermaid-svg-6b04s5ioY8yq2vis .node .label,#mermaid-svg-6b04s5ioY8yq2vis .image-shape .label,#mermaid-svg-6b04s5ioY8yq2vis .icon-shape .label{text-align:center;}#mermaid-svg-6b04s5ioY8yq2vis .node.clickable{cursor:pointer;}#mermaid-svg-6b04s5ioY8yq2vis .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-6b04s5ioY8yq2vis .arrowheadPath{fill:#333333;}#mermaid-svg-6b04s5ioY8yq2vis .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-6b04s5ioY8yq2vis .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-6b04s5ioY8yq2vis .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-6b04s5ioY8yq2vis .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-6b04s5ioY8yq2vis .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-6b04s5ioY8yq2vis .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-6b04s5ioY8yq2vis .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-6b04s5ioY8yq2vis .cluster text{fill:#333;}#mermaid-svg-6b04s5ioY8yq2vis .cluster span{color:#333;}#mermaid-svg-6b04s5ioY8yq2vis div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-6b04s5ioY8yq2vis .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-6b04s5ioY8yq2vis rect.text{fill:none;stroke-width:0;}#mermaid-svg-6b04s5ioY8yq2vis .icon-shape,#mermaid-svg-6b04s5ioY8yq2vis .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-6b04s5ioY8yq2vis .icon-shape p,#mermaid-svg-6b04s5ioY8yq2vis .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-6b04s5ioY8yq2vis .icon-shape .label rect,#mermaid-svg-6b04s5ioY8yq2vis .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-6b04s5ioY8yq2vis .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-6b04s5ioY8yq2vis .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-6b04s5ioY8yq2vis :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 可选
SDK / OpenTelemetry / API
Langfuse Web
PostgreSQL
Redis / Valkey
Langfuse Worker
ClickHouse
Blob Storage / S3
LLM API / Gateway

主要组件职责：

组件	作用
Langfuse Web	Console 与 API
Langfuse Worker	异步处理事件和后台任务
PostgreSQL	事务型状态数据
ClickHouse	Trace、Observation、Score 等高吞吐分析数据
Redis / Valkey	队列与缓存
S3 / Blob Storage	原始事件、大对象、多模态内容、导出等
LLM API / Gateway	Evaluator、Playground 等能力可能调用外部模型

这里可以看出 Langfuse 为什么适合大量 Trace：

Trace / Observation / Score 这种高写入、高分析查询数据主要进入 ClickHouse，而不是全部压在 PostgreSQL 上。

---

10. 一次 Trace 从应用到 Langfuse 大致怎么走

Agent 应用
   ↓
SDK / OpenTelemetry
   ↓
Langfuse 接收事件
   ↓
队列 / Worker 异步处理
   ↓
ClickHouse / Blob Storage
   ↓
Langfuse Console
   ↓
Trace / Dashboard / Evaluation

这也是为什么在生产环境里通常推荐异步采集，而不是把可观测写入变成业务主链路上的同步依赖。

---

11. 放到 AgentScope + MCP 里怎么理解

假设已有链路：

REQUEST_ACCESS
    ↓
AGENT_CALL
    ↓
MODEL_INFER
    ↓
TOOL_EXEC
    ↓
HTTP_OUTBOUND

可以映射为：

业务节点	Langfuse 中建议理解
REQUEST_ACCESS	Trace / Root Observation
AGENT_CALL	Agent Observation
MODEL_INFER	Generation Observation
TOOL_EXEC	Tool Observation
HTTP_OUTBOUND	Span Observation
userId	User
sessionId	Session
traceId	Trace ID

最终页面大概呈现：

Trace: 查询账户余额
│
├── AGENT_CALL
│   ├── MODEL_INFER
│   ├── TOOL_EXEC
│   │    └── HTTP_OUTBOUND
│   └── MODEL_INFER
│
└── Final Output

---

12. 初学者最合理的学习顺序

建议顺序：

Trace / Observation / Session
        ↓
LLM Generation
        ↓
Agent / Tool
        ↓
Prompt
        ↓
Dataset
        ↓
Experiment
        ↓
Evaluator / Score
        ↓
Dashboard

不要一上来就研究全部菜单，因为 Langfuse 的核心还是一条链：

先把 AI 执行过程看清，再评估质量，再通过数据持续优化。

---

13. 总结

Langfuse 可以分成两个层面理解。

第一层是"看"：

Trace
Observation
Session
Prompt
Token
Cost
Latency

第二层是"评和改"：

Score
Evaluator
Dataset
Experiment
Dashboard

这两层结合起来，才构成完整的 AI Engineering 闭环。

---

参考资料

• https://langfuse.com/docs
• https://langfuse.com/docs/observability/data-model
• https://langfuse.com/docs/prompt-management/overview
• https://langfuse.com/docs/evaluation/overview
• https://langfuse.com/self-hosting