一条命令跑通 Langfuse

10 分钟跑起来

官方 repo 自带 docker compose,克隆即用:

# 1) 克隆仓库(完整 compose 文件和 .env.example 都在里面)
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# 2) 启动(默认把 Web/Worker/ClickHouse/Postgres/Redis/MinIO 全拉起来)
docker compose up -d

# 3) 看看状态
docker compose ps

第一次启动会拉 ~2GB 镜像,有耐心。成功之后你会看到类似这样的服务矩阵:

NAME                        STATUS        PORTS
langfuse-web-1              Up (healthy)  0.0.0.0:3000->3000/tcp
langfuse-worker-1           Up (healthy)  0.0.0.0:3030->3030/tcp
langfuse-postgres-1         Up (healthy)  5432/tcp
langfuse-clickhouse-1       Up (healthy)  8123/tcp, 9000/tcp
langfuse-redis-1            Up (healthy)  6379/tcp
langfuse-minio-1            Up (healthy)  9000/tcp, 9090/tcp

浏览器打开 http://localhost:3000,能看到登录页就算成功。

第一次登录:organization / project / key

Langfuse 的权限模型三级:

• Organization:一个公司或一个独立团队。计费、SSO、成员管理都在这层
• Project:organization 下的一个 scope,一般对应一个应用或业务线。trace/prompt/dataset 都归属 project
• API Key:project 级别的凭证,SDK 靠它识别去哪个 project 写数据

1. 注册管理员账号(默认 email 注册开启,可在 AUTH_DISABLE_SIGNUP=true 关闭)
2. 创建 organization,叫啥都行
3. 在 org 下创建第一个 project,比如 demo-app
4. 进入 project → Settings → API Keys,创建一对 pk-lf-xxx(public)和 sk-lf-xxx(secret)
5. 把两把 key 记下来,下一步要用

发出第一条 trace

新建一个目录,安装 SDK:

pip install langfuse openai

写一个最小脚本:

import os
from langfuse.openai import openai  # 关键: 用 langfuse 包装后的 openai

os.environ["LANGFUSE_HOST"] = "http://localhost:3000"
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["OPENAI_API_KEY"] = "sk-proj-..."

rsp = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "说一句格言"}],
    # ↓ 这是 langfuse 专属参数,其余参数与官方 openai SDK 一致
    name="motto-demo",
    user_id="user-1",
    tags=["hello-world"],
)
print(rsp.choices[0].message.content)

跑完几秒钟后回到 UI,Traces 面板就能看到一条新记录。点进去:

• 整棵 trace 树:根节点是一次 HTTP 请求,子节点是那次 chat.completions 调用
• Input / Output 原文
• 模型名、token 数、cost(Langfuse 按模型自动估算)、延迟
• User / Tags / Session(我们只传了 user 和 tags,session 为空)

UI 六大面板各管什么

① Traces

最常用。列表按时间倒排,能按 model / user / tag / session / score 过滤。进详情可以看完整的 span 树、每一步的 I/O、cost、timeline。

你大概 80% 的时间都在这个面板——出 bug 先来这儿找是哪条 trace 出的问题。

② Sessions

一通对话可能触发几十条 trace。给它们挂同一个 session_id,UI 会自动聚成一个会话视图。像 ChatGPT 那样一条 session 看到底。

rsp = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[...],
    session_id="chat-abc-123",  # 同一对话的所有 trace 共享
)

③ Users

传 user_id 后聚合到这里。每个用户维度看:总 trace 数、总 token、总 cost、近期 trace、平均评分——定位"谁在制造成本 / 谁最不满意"。

④ Prompts

Prompt Management 的入口,详细讲第 5 章。这里先知道:

• 每条 prompt 有 name + version + label
• 可以是 text 或 chat 两种类型
• SDK 运行时用 get_prompt("customer-bot", label="production") 拉取,命中 trace 时自动关联 prompt 版本

⑤ Datasets

评估用的金标准集。每条 dataset item 是一个 {input, expected_output, metadata}。第 6 章会把"从 trace 一键圈成 dataset"的流程走一遍。

⑥ Scores

所有 trace / observation 的打分(人工、LLM-as-Judge、程序化)汇总。按时间趋势看质量漂移,按模型/prompt 版本对比。

另外还有几个辅助面板:Dashboards(自己配图)、Evaluators(配 LLM-as-Judge)、Settings(API Key、member、LLM connection、SSO)。

让 SDK 正确刷盘

默认 SDK 批量上报,进程退出可能丢最后几条。脚本或 CI 环境下记得:

from langfuse import Langfuse

lf = Langfuse()  # 从环境变量读 host + keys

# ... 业务逻辑 ...

lf.flush()  # 手动把内存里的 batch 推送掉
# 或者: atexit.register(lf.flush)

长跑服务(web server、worker)不用手动 flush,SDK 会按时间 + 批量阈值自动上报。

排障:常见 3 个坑

升级与数据保留

Langfuse 迭代很快,升级基本就是:

git pull origin main
docker compose pull
docker compose up -d

Web 容器启动时会自动跑 Postgres migration;ClickHouse migration 需要 Worker 跑(所以 Worker 要先于 Web 起来或者让 Web 跑在迁移完成的 ClickHouse 上)。

本章小结