langfuse/langfuse：开源LLM可观测性与评测平台

一、官方信息

项目名称	Langfuse
仓库地址	https://github.com/langfuse/langfuse
官方网站	https://langfuse.com/
最新更新	2026 年高速迭代
项目定位	开源 LLM 应用可观测性、Prompt 管理与评测平台
开源协议	MIT（核心）/ EE（部分企业功能）

二、项目背景

调试 LLM 应用是件痛苦的事：一次对话背后可能串了"检索 → Prompt 拼装 → 多次 LLM 调用 → 解析 → 工具调用"十几个环节，出了问题你根本不知道是哪一步出错、花了多少 token、花了多少钱、延迟多少。传统 APM 工具（Prometheus、Datadog）只看指标，看不懂 LLM 的调用链和 Prompt 内容。

Langfuse 就是为 LLM 应用量身定做的可观测性平台。它能把你的每一次 LLM 调用、每次检索、每个工具调用都记录成一条带时间线的 Trace，在网页上可视化展示：输入是什么、输出是什么、各步耗时、token 消耗、成本、用户反馈。你还可以在 Langfuse 里做 Prompt 版本管理、离线评测数据集、在线打分（Human Feedback），形成"开发 → 上线 → 观测 → 评测 → 优化"的闭环。

Langfuse 提供免费 SaaS 版，也支持完全自托管。它有 Python SDK、JS SDK，原生对接 OpenAI、LangChain、LlamaIndex、Vercel AI SDK 等几乎所有主流框架。对做产品的团队，自托管一份 Langfuse 就能把 LLM 调用治理得明明白白。

三、核心特性

Trace 可视化：记录完整 LLM 调用链，每一步输入输出、耗时、token。
Token 与成本追踪：自动按模型单价统计每次调用花费。
Prompt 管理：在 Web 上维护 Prompt 模板并版本化，代码里远程拉取。
评测数据集：构建测试集，跑离线评测、对比不同模型 / Prompt。
用户反馈采集：在线采集点赞点踩、人工打分。
大模型互操作：OpenAI / Anthropic / DeepSeek / 本地模型全兼容。
开源可自托管：数据完全私有，支持私有化部署。

四、环境要求

Linux 服务器（Ubuntu 22.04 推荐）。
Docker 20.10+ 与 Docker Compose v2。
内存：建议 4GB 以上（含 Postgres、MinIO）。
端口：3000（Web 界面）。

五、详细部署步骤

方式一：Docker Compose 自托管（官方推荐）

拉取官方 compose 文件：

git clone https://github.com/langfuse/langfuse.git
cd langfuse
# 使用仓库中 self-hosting 目录下的 compose 文件
cd docker-compose
docker compose up -d

官方 compose 会拉起以下服务：

langfuse-web：主 Web 服务，端口 3000。
langfuse-worker：后台任务（评测、批处理）。
postgres：主数据库。
minio：对象存储（存 trace 附件）。

关键环境变量（必须修改）

官方 compose 文件中所有敏感项都标了 # CHANGEME，部署前务必改：

# 生成两个随机密钥
openssl rand -hex 32   # 用作 NEXTAUTH_SECRET
openssl rand -hex 32   # 用作 SALT
openssl rand -hex 32   # 用作 ENCRYPTION_KEY（64 个 hex 字符 = 32 字节）

对应在 compose / .env 中：

NEXTAUTH_URL=http://你的服务器IP:3000
NEXTAUTH_SECRET=<上面生成的随机串1>
SALT=<上面生成的随机串2>
ENCRYPTION_KEY=<上面生成的随机串3>

# 数据库连接（compose 已内置 postgres，一般不用改）
DATABASE_URL=postgresql://langfuse:password@postgres:5432/postgres

各变量作用：

NEXTAUTH_URL：外部访问地址，登录回调要用，必须和浏览器地址一致。
NEXTAUTH_SECRET：NextAuth 会话加密密钥。
SALT：哈希用户 API Key 用的盐。
ENCRYPTION_KEY：加密存数据库里的凭证（如外部 LLM Key），一旦设置不可改。

方式二：快速单容器体验

docker run -d --name langfuse \
  -p 3000:3000 \
  -e NEXTAUTH_URL=http://localhost:3000 \
  -e NEXTAUTH_SECRET=$(openssl rand -hex 32) \
  -e SALT=$(openssl rand -hex 32) \
  -e ENCRYPTION_KEY=$(openssl rand -hex 32) \
  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
  langfuse/langfuse:latest

注意：单容器模式需要外部已准备好 Postgres，生产仍推荐用官方 compose。

Python SDK 接入你的应用

pip install langfuse

from langfuse import Langfuse

langfuse = Langfuse(
    public_key="pk-lf-xxxx",   # 在 Web UI 项目设置里创建
    secret_key="sk-lf-xxxx",
    host="http://服务器IP:3000",
)

# 记录一次 LLM 调用
with langfuse.start_as_current_span(name="chat") as span:
    span.update_trace(user_id="user-123", input="你好")
    # ... 调用你的 LLM ...
    span.end(output="你好，有什么可以帮你？")

langfuse.flush()

验证部署

docker compose ps
curl http://localhost:3000/api/public/health
# 浏览器访问 http://服务器IP:3000

六、使用方法

首次打开 http://服务器IP:3000，注册第一个账号（即管理员）。
创建 Organization → Project，在 Project Settings 里拿到 public_key 和 secret_key。
把 key 配进你的应用 SDK，Trace 就会实时出现在 Web 上。
Web UI 中可查看 Traces、建 Prompt、建 Dataset 跑评测、看 Usage 成本报表。
默认无预置账号；第一个注册用户即为管理员（部署后务必注册并关闭公开注册，或配置 OIDC）。

七、常见问题 FAQ

Q1：登录后跳转回 localhost？
A：NEXTAUTH_URL 没改成你的实际域名 / IP。改成外部访问地址后重启容器。

Q2：trace 数据看不到？
A：检查 SDK 的 host 是否指向你的 Langfuse 地址、public/secret key 是否正确；应用里调用了 langfuse.flush()。

Q3：ENCRYPTION_KEY 忘了 / 改了会怎样？
A：它加密数据库里的敏感凭证，丢了或改了会导致已加密数据无法解密，必须妥善备份。

Q4：如何关闭公开注册？
A：在环境变量设置 EMAIL_PASSWORD_AUTH_ENABLED=false，仅用 OIDC 登录；或部署后第一个账号注册完，反向代理限制访问。

Q5：数据存在哪？
A：业务数据在 Postgres，trace 大附件在 MinIO，compose 都做了 volume 持久化。

八、跳转链接

GitHub 仓库：https://github.com/langfuse/langfuse
官方文档：https://langfuse.com/docs
Docker 自托管：https://langfuse.com/self-hosting
Python SDK：https://github.com/langfuse/langfuse-python