Langfuse（朗格福斯）深度评测：开源LLM应用可观测性平台，调试与监控的智能利器使用教程：从入门到精通

一、什么是Langfuse？

Langfuse 是一款开源的 LLM 应用可观测性平台，专为调试、监控和优化基于大语言模型（LLM）的应用而设计。它提供了追踪（Traces）、观察（Observations）、评分（Scores）、成本分析等核心功能，帮助开发者快速定位问题、评估模型表现并管理提示（Prompts）。无论你是构建 RAG 系统、聊天机器人还是智能代理，Langfuse 都能让你对应用的内部运行状态一目了然。

二、核心概念速览

• Trace（追踪）：一次完整的请求链路，例如用户提问到回答返回的全过程。
• Observation（观察）：追踪中的单个操作，如 LLM 调用、向量检索、函数执行等。
• Score（评分）：对输出质量的人工或自动评价（0-1 或自定义范围）。
• Prompt（提示）：可版本管理、A/B 测试的提示模板。
• Cost（成本）：基于 Token 使用量的费用统计（需配置模型定价）。

三、部署与安装

3.1 选择部署方式

• 云托管（推荐快速体验）：访问 https://cloud.langfuse.com 注册账号（支持 GitHub 登录），即可获得免费额度。
• 自托管（用于生产环境）：使用 Docker Compose 一键部署：

  git clone https://github.com/langfuse/langfuse.git
  cd langfuse
  docker compose up -d

  部署后访问 http://localhost:3000。

3.2 获取 API 密钥

登录后，进入「Settings → API Keys」创建一对密钥（LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY）。建议将密钥存储在环境变量中。

四、快速集成：5 分钟跑通第一个追踪

4.1 安装 Python SDK

pip install langfuse

4.2 初始化客户端

from langfuse import Langfuse

langfuse = Langfuse(
    public_key="你的公钥",
    secret_key="你的私钥",
    host="https://cloud.langfuse.com"  # 自托管时改为你的地址
)

4.3 创建追踪并添加观察

使用上下文管理器（推荐）：

with langfuse.trace(name="用户咨询", user_id="user_123") as trace:
    with trace.span(name="调用 GPT-4") as span:
        response = openai.ChatCompletion.create(
            model="gpt-4",
            messages=[{"role": "user", "content": "今天天气如何？"}]
        )
        span.end(
            output=response["choices"][0]["message"]["content"],
            usage={"prompt_tokens": 20, "completion_tokens": 50}
        )

你还可以使用装饰器自动追踪函数：

@langfuse.observe()
def my_llm_call(prompt: str):
    # 你的 LLM 调用代码
    return result

4.4 查看追踪数据

运行代码后，进入 Langfuse 控制台的「Traces」页面，即可看到刚才生成的追踪记录。点击可展开每个 span 的详情，包括输入、输出、耗时、Token 用量等。

五、进阶功能实战

5.1 使用评分评估输出质量

手动评分：

trace.score(name="准确性", value=0.9, comment="回答了关键信息")

或通过 LLM 自动评分（需配置评判函数）。

5.2 提示管理与版本控制

在「Prompts」页面创建提示模板，然后通过 SDK 拉取：

prompt = langfuse.get_prompt("我的提示", version=2)
print(prompt.compile(variable1="值"))

5.3 成本监控

在「Settings → Model Pricing」中配置模型单价（如 GPT-4 每百万 Token 价格），系统会自动计算每次调用的成本。你可以在「Dashboard」中查看每日/每周成本趋势。

六、调试与告警设置

利用「Observations」中的错误状态（status_message）快速定位失败调用。可创建 Webhook 告警：当错误率超过阈值时，通过 Slack、邮件等方式通知。路径：「Settings → Alerts → New Alert」。

七、技巧与最佳实践

• Tip 1：开发阶段关闭采样。在 Langfuse 初始化时设置 sample_rate=1.0（默认 1.0），确保捕获所有请求；生产环境可降低采样率以节省存储。
• Tip 2：分组管理。使用 trace.session_id 或 tags 属性标记不同实验组或用户群体，方便后续对比分析。
• Tip 3：批量导出与自定义仪表盘。Langfuse 支持导出 CSV 和 JSON 格式数据，可通过 API 或 Python SDK 拉取后接入 Grafana 等外部工具。
• Tip 4：使用 @observe() 装饰器时，通过 capture_input=True 和 capture_output=True 控制是否记录输入输出（注意敏感信息脱敏）。