Langfuse 快速上手教程

是什么

Langfuse 是一个开源的大语言模型（LLM）工程平台，帮助团队协作开发、监控、评估和调试 AI 应用。它基于 ClickHouse 构建，支持分钟级自部署，已在生产环境中经过大量验证。

能干什么

• LLM 应用可观测性：在你的应用中埋点，将 LLM 调用、检索、嵌入、Agent 行为等关键逻辑的追踪数据（traces）发送到 Langfuse，实现复杂日志和用户会话的检查与调试。
• 评估与调试：对比不同模型输出、分析 token 消耗、追踪错误和延迟，快速定位问题。
• 协作开发：团队成员可共享追踪数据、标注样本、共同优化 Prompt 和模型表现。

怎么装

方式一：Docker 自部署（推荐）

# 克隆仓库
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# 使用 Docker Compose 启动
docker compose up -d

启动后访问 http://localhost:3000 即可进入控制台。

方式二：云服务（国内访问受限）

可直接使用官方托管的 Langfuse Cloud，无需自行部署。

怎么用第一个例子

1. 安装 Python SDK

pip install langfuse

2. 初始化客户端

from langfuse import Langfuse

langfuse = Langfuse(
    public_key="your-public-key",
    secret_key="your-secret-key",
    host="http://localhost:3000"  # 自部署地址
)

3. 追踪一次 LLM 调用

# 创建一个追踪
trace = langfuse.trace(name="my-first-trace")

# 记录一次 LLM 调用
generation = trace.generation(
    name="openai-completion",
    model="gpt-3.5-turbo",
    input="Hello, how are you?",
    output="I'm fine, thank you!",
    usage={
        "promptTokens": 10,
        "completionTokens": 8,
        "totalTokens": 18
    }
)

# 在 Langfuse 控制台查看结果
print(f"Trace ID: {trace.id}")

4. 查看数据

打开浏览器访问 http://localhost:3000，在 Traces 页面即可看到刚才记录的追踪数据，包括输入输出、token 用量、耗时等信息。

社区资源

• 文档：https://langfuse.com/docs
• GitHub：https://github.com/langfuse/langfuse
• Discord 社区：加入讨论
• 报告 Bug：https://langfuse.com/issues
• 功能建议：https://langfuse.com/ideas
• 更新日志：https://langfuse.com/changelog

翻译整理自 GitHub README，原文：https://github.com/langfuse/langfuse