Langfuse入门指南 [2026版]

创建和部署使用大型语言模型 (LLM) 的应用程序会面临一系列问题。LLM 具有非确定性，可能会生成看似合理但实则错误的信息，而且追踪其在复杂序列中的行为也可能非常困难。在本指南中，我们将了解 Langfuse 如何成为解决这些问题的关键工具，它为 LLM 应用程序的全面可观测性、评估和快速处理提供了强大的基础。

什么是Langfuse？

Langfuse 是一个突破性的开源可观测性和评估平台，专为 LLM 应用程序而设计。它为追踪、查看和调试 LLM 交互的所有阶段奠定了基础，从初始提示到最终响应，无论是简单的呼叫还是代理之间复杂的多轮对话。

Langfuse 不仅是一款日志记录工具，更是一种系统性评估 LLM 性能、进行 A/B 测试以及收集用户反馈的工具，从而有助于形成反馈闭环，实现迭代改进。其主要价值在于提升了 LLM 的透明度，使开发者能够：

• 了解 LLM 的行为：准确了解已发送的提示、已接收的响应以及多阶段应用程序中的中间步骤。
• 查找问题：快速定位错误、性能低下或意外输出的根源。
• 质量评估：通过手动和自动方式，根据预定义的指标衡量 LLM 响应的有效性。
• 优化改进：利用数据驱动的洞察来完善提示、模型和应用程序逻辑。
• 管理提示：控制提示的版本并进行测试，以获得最佳的 LLM 体验。

主要特性和概念

Langfuse 提供以下主要特性：

1. 追踪和监控：Langfuse 帮助我们捕获 LLM 每次交互的详细追踪信息。“追踪”本质上是对端到端用户请求或应用程序流程的表示。在追踪中，逻辑工作单元用“跨度”（span）表示，对 LLM 的调用用“代”（generation）表示。
2. 评估：Langfuse 支持手动和编程两种评估方式。开发人员可以定义自定义指标，用于对不同的数据集运行评估，并将其集成到基于 LLM 的评估器中。
3. 提示管理：Langfuse 提供对提示管理的直接控制，以及存储和版本控制功能。可以通过 A/B 测试测试各种提示，同时在不同位置保持准确性，这为数据驱动的提示优化铺平了道路。
4. 反馈收集：Langfuse 会收集用户建议并将其融入到您的代码中。您可以将特定评论或用户评分链接到产生输出结果的 LLM 交互，从而为我们提供实时反馈，以便进行故障排除和改进。

为什么选择Langfuse？它解决了什么问题？

传统的软件可观测性工具特性迥异，在以下几个方面无法满足基于 LLM 的应用需求：

• 不确定性：即使输入完全相同，LLM 也并非总能产生相同的结果，这使得调试极具挑战性。而 Langfuse 则会记录每次交互的输入和输出，从而清晰地展现当时的运行状态。
• 提示符敏感性：提示符的任何细微变化都可能彻底改变 LLM 的响应。Langfuse 能够帮助跟踪提示符版本及其性能指标。
• 复杂链：大多数 LLM 应用都包含多个 LLM 调用、不同的工具以及数据检索（例如，RAG 架构）。追踪是了解流程并精确定位瓶颈或错误所在位置的唯一方法。 Langfuse 为这些交互提供了一个可视化的时间线。
• 主观质量：LLM 响应的“好坏”通常等同于个人意见。Langfuse 支持客观（例如，延迟、令牌计数）和主观（人工反馈、基于 LLM 的评估）质量评估。
• 成本管理：调用 LLM API 会产生费用。如果使用 Langfuse 监控令牌使用情况和调用量，则更容易了解和优化成本。
• 缺乏可见性：开发人员无法了解其 LLM 应用程序在市场上的表现，因此由于缺乏可观察性，他们很难逐步改进这些应用程序。

Langfuse 不仅提供了一种系统化的 LLM 交互方法，而且还将开发过程从试错转变为数据驱动的迭代工程方法。

Langfuse入门指南

在使用 Langfuse 之前，您必须先安装客户端库，并将其配置为向 Langfuse 实例（可以是云托管实例，也可以是自托管实例）传输数据。

安装

Langfuse 提供 Python 和 JavaScript/TypeScript 客户端库。

Python 客户端

pip install langfuse

JavaScript/TypeScript 客户端

npm install langfuse

或

yarn add langfuse

配置

安装完成后，请务必使用您的项目密钥和主机配置客户端。您可以在 Langfuse 项目设置中找到这些信息。

• public_key：用于前端应用程序或仅发送有限且非敏感数据的场景。
• secret_key：用于后端应用程序以及需要完全可观测性（包括敏感输入/输出）的场景。
• host：指您的 Langfuse 实例的 URL（例如，https://cloud.langfuse.com）。
• environment：这是一个可选字符串，可用于区分不同的环境（例如，生产环境、测试环境、开发环境）。

出于安全性和灵活性的考虑，建议将这些定义为环境变量。

export LANGFUSE_PUBLIC_KEY="pk-lf-..." 
export LANGFUSE_SECRET_KEY="sk-lf-..." 
export LANGFUSE_HOST="https://cloud.langfuse.com" 
export LANGFUSE_ENVIRONMENT="development"

然后，在您的应用程序中初始化 Langfuse 客户端：

Python 示例

from langfuse import Langfuse
import os
langfuse = Langfuse(public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),    secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),    host=os.environ.get("LANGFUSE_HOST"))

JavaScript/TypeScript 示例

import { Langfuse } from "langfuse";
const langfuse = new Langfuse({  publicKey: process.env.LANGFUSE_PUBLIC_KEY,  secretKey: process.env.LANGFUSE_SECRET_KEY,  host: process.env.LANGFUSE_HOST});

设置您的第一个跟踪

Langfuse 中可观测性的基本单元是跟踪 (trace)。跟踪通常代表一次用户交互或一个完整的请求生命周期。在跟踪中，您可以记录单个 LLM 调用（生成）和任意计算步骤（跨度）。

让我们使用 OpenAI 的 API 通过一个简单的 LLM 调用来演示。

Python 示例

import os
from openai import OpenAI
from langfuse import Langfuse
from langfuse.model import InitialGeneration
# Initialize Langfuse
langfuse = Langfuse(
public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),
secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),
host=os.environ.get("LANGFUSE_HOST"),
)
# Initialize OpenAI client
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
def simple_llm_call_with_trace(user_input: str):
# Start a new trace
trace = langfuse.trace(
name="simple-query",
input=user_input,
metadata={"user_id": "user-123", "session_id": "sess-abc"},
)
try:
# Create a generation within the trace
generation = trace.generation(
name="openai-generation",
input=user_input,
model="gpt-4o-mini",
model_parameters={"temperature": 0.7, "max_tokens": 100},
metadata={"prompt_type": "standard"},
)
# Make the actual LLM call
chat_completion = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": user_input}],
temperature=0.7,
max_tokens=100,
)
response_content = chat_completion.choices[0].message.content
# Update generation with the output and usage
generation.update(
output=response_content,
completion_start_time=chat_completion.created,
usage={
"prompt_tokens": chat_completion.usage.prompt_tokens,
"completion_tokens": chat_completion.usage.completion_tokens,
"total_tokens": chat_completion.usage.total_tokens,
},
)
print(f"LLM Response: {response_content}")
return response_content
except Exception as e:
# Record errors in the trace
trace.update(
level="ERROR",
status_message=str(e)
)
print(f"An error occurred: {e}")
raise
finally:
# Ensure all data is sent to Langfuse before exit
langfuse.flush()
# Example call
simple_llm_call_with_trace("What is the capital of France?")

执行此代码后，下一步是访问 Langfuse 界面。界面上会显示一个新的跟踪记录“simple-query”，它包含一个生成记录“openai-generation”。您可以点击它来查看输入、输出、使用的模型和其他元数据。

核心功能详解

学习如何使用跟踪、跨度和生成对象是充分利用 Langfuse 的主要前提。

跟踪LLM调用

Source: Langfuse

• langfuse.trace()：此命令启动一个新的跟踪记录。它是整个操作的顶级容器。
  • name：跟踪记录的描述性名称。
  • input：整个过程的第一个输入。
  • metadata：用于过滤和分析的键值对字典（例如，user_id、session_id、AB_test_variant）。
  • session_id：（可选）来自同一用户会话的所有跟踪共享的标识符。
  • user_id：（可选）特定用户的所有交互共享的标识符。

• trace.span()：这是跟踪中的一个逻辑步骤或次要操作，它不是与 LLM 的直接输入输出交互。工具调用、数据库查找或复杂计算都可以通过这种方式进行跟踪。
  • name：span 的名称（例如，“retrieve-docs”、“parse-json”）。
  • input：与此 span 相关的输入。
  • output：此 span 创建的输出。
  • metadata：span 元数据的格式为 additional。
  • level：严重级别（INFO、WARNING、ERROR、DEBUG）。
  • status_message：与状态关联的消息（例如，错误详情）。
  • parent_observation_id：将此 span 连接到嵌套结构的父 span 或 trace。

• trace.generation()：表示特定的 LLM 调用。
  • name：生成名称（例如，“initial-response”、“refinement-step”）。
  • input：传递给 LLM 的提示或消息。
  • output：从 LLM 收到的回复。
  • model：所使用的具体 LLM 模型（例如，“gpt-4o-mini”、“claude-3-opus”）。
  • model_parameters：特定模型参数的字典（例如 temperature, max_tokens, top_p）。
  • usage：显示所用标记数的字典（prompt_tokens, completion_tokens, total_tokens）。
  • metadata：LLM 调用的附加元数据。
  • parent_observation_id：将当前生成与父级 span 或 trace 关联起来。
  • prompt：（可选）可以标识 Langfuse 中正在管理的特定提示模板。

小结

Langfuse 将基于 LLM 的应用程序的开发和维护转变为结构化和数据驱动的过程，从而减轻了其工作负担。它通过广泛的跟踪、系统化的评估和强大的提示管理，使开发人员能够以前所未有的方式访问与 LLM 的交互。

此外，它还鼓励开发人员自信地调试工作，加快迭代过程，并不断提升其 AI 产品的质量和性能。因此，无论您开发的是基本的聊天机器人还是复杂的自主代理，Langfuse 都能提供必要的工具，确保 LLM 应用程序值得信赖、经济高效且功能强大。