langfuse/langfuse · 上手攻略

• 仓库：langfuse/langfuse
• 链接：https://github.com/langfuse/langfuse
• 分类：ai / llm-infra · evaluation · trending
• 作者：Jay
• 更新：2026-07-09

这是什么

Langfuse 是一个开源 LLM 工程平台，帮助团队协作地开发、监控、评测和调试 AI 应用。2026 年 1 月，Langfuse 团队加入 ClickHouse，继续深耕开源可观测性领域。它同时提供 Langfuse Cloud（托管版，有慷慨的免费额度）和私有化部署（Docker Compose，一键起立）。

核心功能覆盖 LLM 应用全生命周期：

• 可观测性（Tracing）：接入你的应用，自动记录 LLM 调用链，支持 OpenAI SDK / LangChain / Vercel AI SDK / OpenTelemetry，附带 Web UI 会话 debug
• Prompt 管理：集中管理、版本控制、团队协作迭代 prompt，客户端/服务端双侧缓存，迭代不增加延迟
• 评测（Evaluations）：LLM-as-a-Judge、代码评测器、用户反馈收集、人工标注，支持自定义评测管道
• 数据集（Datasets）：构建测试集和基准，支持持续改进、预部署测试、结构化实验，与 LangChain / LlamaIndex 无缝集成
• Playground：直接在 UI 中测试 prompt 和模型配置，发现 bad case 后可直接跳转到 Playground 迭代
• 全面 API：OpenAPI 规范，Python / JS/TS typed SDK，适合驱动自定义 LLMOps 工作流

解决什么问题

开发 LLM 应用时，团队常面临这些痛点：

1. 黑盒调试：LLM 调用不透明，出问题不知道是 prompt、模型还是数据的问题
2. 迭代效率低：改一个 prompt 要改代码、重新部署，没有独立的 prompt 版本管理
3. 缺乏评测：没有量化指标衡量应用质量，靠人工肉眼判断
4. 多框架分散：同时用 LangChain、OpenAI SDK、LlamaIndex，日志散落在各处
5. 团队协作难：prompt 和评测结果没有共享空间

Langfuse 统一了这些环节，让你在一个平台里完成从开发到上线的闭环。

快速安装

方式一：Langfuse Cloud（即用）

1. 注册 cloud.langfuse.com（免费额度慷慨，无需信用卡）
2. 在项目设置中创建 API 凭证（LANGFUSE_SECRET_KEY / LANGFUSE_PUBLIC_KEY）
3. 接入你的代码（见下文核心用法）

方式二：本地 Docker Compose 私有部署

git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up -d
# 访问 http://localhost:3000 完成初始化

私有部署支持 PostgreSQL + ClickHouse（内置 Docker Compose 中），生产环境建议连接外部 ClickHouse 实例。

核心用法

1. 安装 Python SDK

pip install langfuse

2. 配置环境变量

# .env
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_BASE_URL="https://cloud.langfuse.com"          # EU 区
# LANGFUSE_BASE_URL="https://us.cloud.langfuse.com"   # US 区
# LANGFUSE_BASE_URL="https://jp.cloud.langfuse.com"   # 日本区

⚠️ 注意：私有部署时，LANGFUSE_BASE_URL 改为你的实例地址（如 http://localhost:3000）。

3. 接入 OpenAI SDK（最常用方式）

Langfuse 的 OpenAI SDK 是drop-in 替换，几乎零改动接入：

# 替换前
from openai import OpenAI
client = OpenAI()

# 替换后
from langfuse.openai import OpenAI
client = OpenAI()

# 后续调用完全一样，Langfuse 自动在后台记录 trace
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)
print(response.choices[0].message.content)

效果：每次 LLM 调用自动生成一个 Trace，可在 Langfuse Dashboard 查看调用详情、耗时、token 消耗。

4. 接入 LangChain Python

from langchain_openai import ChatOpenAI
from langfuse.callback import CallbackHandler

langfuse_handler = CallbackHandler()

llm = ChatOpenAI(model="gpt-4o")
# LangChain 的 Runnable 均可自动被 CallbackHandler 捕获
chain = prompt | llm
result = chain.invoke({"question": "..."}, config={"callbacks": [langfuse_handler]})

5. 接入 Vercel AI SDK（Node.js/TypeScript）

npm install langfuse

import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  baseUrl: "https://cloud.langfuse.com",
});

const generation = langfuse.generation({
  name: "my-llm-call",
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});

// 使用 OpenAI SDK 兼容方式调用
// langfuse 会自动拦截并记录

6. Prompt 管理（版本控制 + 热更新）

在 Langfuse Web UI 中创建 prompt 模板：

You are a helpful assistant. The user's question is: {{question}}

代码中调用：

from langfuse.prompt import Prompt

prompt = Prompt.get("my-prompt-v1")  # 支持版本指定
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": prompt.compile(question="What is RAG?")}]
)

热更新：UI 中修改 prompt 后，应用无需重新部署即可生效（服务端缓存）。

7. 评测（Datasets + Evaluations）

# 创建 dataset
langfuse.create_dataset(name="qa-test-set", rows=[
    {"input": "What is RAG?", "expected": "Retrieval-augmented generation is..."},
    {"input": "Explain transformers", "expected": "Attention is all you need..."},
])

# 运行评测
from langfuse.evaluation import evaluate

results = evaluate(
    model="gpt-4o",
    dataset="qa-test-set",
    evaluator="llm-judge",  # LLM-as-a-Judge
    metrics=["relevance", "accuracy"]
)

典型适用场景

坑与注意

1. 隐私合规：用 Cloud 版时数据会上传到 Langfuse 服务器；敏感数据场景务必私有化部署，且注意网络隔离
2. 私有部署 ClickHouse 资源：单节点 Docker Compose 适合开发/小规模团队，生产环境建议独立 ClickHouse 集群
3. CallbackHandler 生命周期：确保 handler 实例在 LLM 调用期间不被 GC（尤其在异步场景下）
4. LangChain 版本兼容性：CallbackHandler API 随 LangChain 版本变化，建议在 requirements.txt 中锁定版本
5. Tracing 开销：高频调用场景下，Langfuse SDK 的后台上报有一定网络开销（约几毫秒），生产环境可配置采样率（sample_rate 参数）
6. 中文文档：官方英文文档完整，中文翻译覆盖部分页面，有疑问建议直接读英文原版

与同类对比

结论： - 选 Langfuse：想要开源 + 自托管 + 全套 LLMOps 能力（尤其 prompt 管理和评测） - 选 LangSmith：不介意付费，追求与 LangChain 生态的原生深度集成 - 选 Helicone：只需轻量 LLM 可观测性，不需要 Prompt 管理和评测 - 选 OTel：已有成熟可观测性基础设施，只需记录 LLM spans

一句话推荐结论

Langfuse 是目前开源 LLMOps 平台中功能最完整、上手最友好的选择——私有化部署 5 分钟搞定，Tracing + Prompt 管理 + 评测三件套一站配齐，是 LangSmith 的强力开源替代。