主题
阶段 5：Langfuse 平台能力
预计学习时间：1 天
Tracing 只是起点；Langfuse 的真正价值在于「追踪 → 分析 → 迭代」闭环。
目录
1. 能力全景图
┌──────────────────────────────────────────┐
│ Langfuse 平台 │
└──────────────────────────────────────────┘
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Tracing │→ │ Prompt │→ │ Eval │→ │Dashboard│
│ 发现问题 │ │ 迭代优化 │ │ 量化效果 │ │ 持续监控 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘| 能力 | 解决什么问题 | 生活类比 |
|---|---|---|
| Tracing | AI 某次回答为什么错了 | 调监控录像 |
| Prompt Mgmt | Prompt 改了不知道哪个版本在线 | 菜谱版本管理 |
| Evaluation | 改好了还是不好，缺少客观分数 | 顾客试吃打分 |
| Datasets | 没法批量回归测试 | 标准考题库 |
| Dashboard | 成本/延迟/错误率趋势 | 经营日报 |
2. Prompt 管理
2.1 为什么需要
生产环境里 Prompt 经常改：
v1: "你是一个客服助手..."
v2: "你是一个专业客服，回答要简洁..."
v3: "你是一个专业客服，回答要简洁，引用知识库原文..."如果没有版本管理，出了问题你根本不知道线上跑的是哪个版本。
2.2 核心概念
| 概念 | 说明 |
|---|---|
| Prompt Name | 唯一标识，如 customer-service-system |
| Version | 自动递增的版本号 |
| Label | 标签，如 production、staging |
| Config | 关联的模型参数 |
2.3 基本用法（Python SDK）
python
from langfuse import Langfuse
lf = Langfuse()
# 创建 Prompt 版本
lf.create_prompt(
name="weather-bot-system",
prompt="你是一个天气助手。根据提供的天气数据回答用户。",
labels=["production"],
config={"model": "gpt-4o", "temperature": 0.3},
)
# 获取线上 Prompt
prompt = lf.get_prompt("weather-bot-system", label="production")
compiled = prompt.compile(city="北京", temp=25)2.4 生活类比
餐厅菜谱本：
- Name = 菜名「宫保鸡丁」
- Version = 第 3 版（少盐）
- Label = 「今日特供」还是「备用菜谱」
- 换错菜谱 = 线上 Prompt 回滚事故
3. Evaluation 评测
3.1 为什么需要
Tracing 告诉你「发生了什么」；Evaluation 告诉你「做得好不好」。
3.2 评分方式
| 方式 | 说明 | 适用 |
|---|---|---|
| 人工打分 | 在 UI 里给 Trace 打 1-5 分 | 早期、高质量样本 |
| Numeric Score | 数值分，如 0.85 | 自动化流水线 |
| Boolean Score | 通过/不通过 | 回归测试 |
| Categorical | 多类别标签 | 分类质量 |
| LLM-as-Judge | 用另一个 LLM 打分 | 大规模自动评测 |
3.3 SDK 打分示例
python
trace = lf.trace(name="qa-bot", id="trace-uuid-from-server")
# 方式 1：对 trace 打分
trace.score(
name="user-satisfaction",
value=4,
comment="回答准确但略啰嗦",
)
# 方式 2：对某个 observation 打分
generation.score(
name="faithfulness",
value=0.9,
data_type="NUMERIC",
)3.4 生活类比
外卖平台「骑手送达后请你打分」——Langfuse 的 Score 就是这张评分卡，可以挂在整单（Trace）或某道菜（Observation）上。
4. Datasets 与实验
4.1 Dataset
Dataset = 一组标准测试用例：
json
[
{"input": "北京天气", "expected_output": "应包含温度和天气状况"},
{"input": "退款政策", "expected_output": "应引用官方政策原文"},
{"input": "你好", "expected_output": "礼貌问候"}
]4.2 Experiment
用 Dataset 批量跑你的应用，对比：
- 模型 A vs 模型 B
- Prompt v1 vs v2
- 不同 temperature
Experiment: "prompt-v2-vs-v3"
Dataset: 50 条客服问题
Run A: gpt-4o + prompt v2 → 平均分 4.1
Run B: gpt-4o + prompt v3 → 平均分 4.6 ← 胜出4.3 生活类比
Dataset = 高考题库
Experiment = 两次模拟考，对比哪套复习方案更有效
5. Dashboard 与分析
Langfuse 内置 Dashboard，常见分析维度：
| 维度 | 用途 |
|---|---|
| Latency P50/P95 | 找到慢请求 |
| Token 用量 | 成本控制 |
| Cost by Model | 哪个模型最贵 |
| Error Rate | 失败率趋势 |
| Scores 分布 | 质量趋势 |
| User / Session | 按用户聚合 |
典型排查路径
Dashboard 发现 P95 延迟从 2s 升到 8s
↓
Traces 过滤 tags=prod, latency>5s
↓
点开最慢的 Trace，看哪个 Observation 耗时最长
↓
发现 retriever 步骤从 100ms 变成 5s → 向量库问题6. 生活类比：开餐厅的全流程
把 Langfuse 平台能力串成一条故事线：
- 开业（接入 Tracing）：每个订单都有后厨录像
- 菜谱迭代（Prompt Mgmt）：宫保鸡丁从 v1 改到 v3
- 试吃评分（Evaluation）：请美食博主打分
- 批量盲测（Datasets）：50 位顾客试吃新旧两版
- 看经营日报（Dashboard）：发现周末晚高峰出餐慢
这就是 LLM 应用从「能跑」到「跑得好」的工程化路径。
7. 学习检查
- [ ] 能解释 Prompt 版本和 Label 的作用
- [ ] 知道至少两种 Evaluation 打分方式
- [ ] 理解 Dataset + Experiment 的回归测试价值
- [ ] 能描述从 Dashboard 发现异常到定位 Trace 的排查路径
下一章 → 6_integration_cases.md