Langfuse：LLM 应用的可观测性平台，Prompt 与成本追踪的开源标准

开篇

这篇教程带你从零启动一个 Langfuse 实例，并用一个真实的 OpenAI 调用脚本完成 LLM 调用的追踪与成本统计。最终你会得到一个可运行的本地 Langfuse 服务，以及一份包含 token 消耗和延迟的可视化 Trace。

前置条件

• 安装 Docker 24+ 与 Docker Compose v2（用于一键启动 Postgres、Redis 等依赖服务）
• Node.js 20+ 与 npm 10+（用于运行 Langfuse 本体，开发模式还不要用旧版 LTS）
• Python 3.10+ 与 pip（用于跑示例客户端，OpenAI SDK 需要它）
• 一个可用的 OpenAI API Key（或者任何兼容 OpenAI 协议的本地模型端点也可以）
• 至少 4GB 可用内存，本机端口 3000 和 5432 未被占用

安装部署

1. 安装 Langfuse CLI 与初始化项目

这一步要做什么：把官方仓库克隆到本地，并进入项目目录快速启动生产配置。

git clone https://github.com/langfuse/langfuse.git
cd langfuse
cp .env.example .env

然后编辑 .env，至少修改下面两个值（否则第一次启动会报错）：

NEXTAUTH_URL=http://localhost:3000
SALT=replace_this_with_a_random_string

2. 启动依赖服务

这一步要做什么：Langfuse 需要 Postgres 和 Redis，用 Compose 把他们拉起来。

docker compose -f docker-compose.yml up -d

预期输出：看到 database、redis 两个容器显示 healthy 状态。

3. 初始化数据库并启动应用

这一步要做什么：执行 Prisma 迁移创建数据表，然后以开发模式启动 Langfuse 主服务。

npx prisma migrate deploy
npm run dev

预期输出：终端出现 ready started server on 0.0.0.0:3000，浏览器打开 http://localhost:3000 能看到登录页。

第一个 Demo

1. 创建项目并获取公私钥

这一步要做什么：在 Langfuse UI 中点击右上角头像 → "Create Project" → 命名为 demo。进入项目设置，复制 Public Key 和 Secret Key，后面两步要用。

2. 安装 Python SDK 并写一个最小调用脚本

这一步要做什么：装好 langfuse 与 openai 库，然后写一个带追踪的 chat completion 脚本。核心思路是创建一个 Trace，再把 OpenAI 调用作为 Generation 记录进去。

pip install langfuse openai

cat > trace_demo.py << 'EOF'
from langfuse import Langfuse
from openai import OpenAI

langfuse = Langfuse(
    public_key="pk-xxxx",
    secret_key="sk-xxxx",
    host="http://localhost:3000"
)

client = OpenAI()

trace = langfuse.trace(name="first-trace")

generation = trace.generation(
    name="chat",
    model="gpt-4o-mini",
    input={"messages": [{"role": "user", "content": "用一句话解释什么是可观测性"}]}
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=generation.input["messages"]
)

generation.end(
    output=response.choices[0].message.content,
    usage={
        "input": response.usage.prompt_tokens,
        "output": response.usage.completion_tokens,
        "total": response.usage.total_tokens,
        "unit": "TOKENS"
    }
)

langfuse.flush()
print("完成，Trace 地址: http://localhost:3000/trace/" + trace.id)
EOF

3. 运行并观察结果

这一步要做什么：执行脚本，然后打开终端输出的 Trace 地址。

python trace_demo.py

预期输出：终端打印 完成，Langfuse UI 中出现一条名为 first-trace 的 trace。点进去可以看到 prompt 原文、回复内容以及精确到分页符的 token 数。左侧的 Cost 列会自动按模型单价换算成美元数额。

配置与调优

1. 持久化存储与备份

默认写进 Docker volume 的 Postgres 数据容易丢。建议在 .env 中改成外部数据库连接串，并定期用 pg_dump 备份。核心是把 DATABASE_URL 指向你的托管 Postgres，而不是本地容器。

2. 关闭调试日志与鉴权增强

生产环境建议把 NODE_ENV 设为 production，并配置 NEXTAUTH_SECRET 而不是默认的 SALT。同时打开 LANGFUSE_ENABLE_ORG_PROJECT 选项，让不同团队的 key 严格隔离。

3. 采样率优化

高流量时不必记录全部请求。在 SDK 初始化时传 sample_rate=0.1，只保留 10% 的 trace。也可以使用 Langfuse 的 "Sampling" 特性在服务端按 trace id 过滤，这样既能保持监控覆盖，又不会压垮存储。

常见坑与排错

下一步

• 把 Langfuse 接入 FastAPI 中间件，用 @observe() 装饰器自动追踪所有路由的 LLM 调用链路
• 在评估环节使用 Langfuse 的 Prompt 版本管理，A/B 测试两条 prompt 哪个更省 token
• 用官方 pino-langfuse 结合日志系统，把传统 error log 与 metric trace 关联起来做告警