[JS/TS] langfuse开源LLM可观测平台实战：监控、追踪与调试大模型应用

Langfuse 是一款面向大模型应用开发的开源可观测性平台。它提供了三个层级的追踪体系，能够实现从单次请求、多轮对话到用户全局行为的全方位覆盖：

• Trace（单轮执行追踪）：聚焦单条LLM请求的完整链路，记录从输入、中间步骤到输出的全量数据，包括层级化执行树、耗时分布、Token与成本消耗等细节，为问题根因分析提供最细粒度的依据。
• Session（多轮对话追踪）：将同一上下文的关联请求（如用户的多轮连续问答）聚合为会话，还原完整对话逻辑，解决“单轮Trace孤立无关联”的问题，便于分析用户在多轮交互中的行为模式。
• User（用户维度追踪）：基于用户唯一ID聚合其所有Session和Trace，实现“用户-对话-单轮执行”的三层关联，支持从用户视角全局分析行为特征与问题分布，是面向用户留存、个性化优化等业务场景的顶层观测维度。

官方文档地址：https://github.com/langfuse/langfuse，https://langfuse.com/self-hosting/deployment/docker-compose。

在 Dify 等知名 AI 应用开发平台的源码中，我们也能看到其集成了 Langfuse 来实现监控观测。下面我们将通过实战快速体验其使用方法，并简单分析其实现原理。

环境部署与启动

首先，我们通过 Docker Compose 快速部署 Langfuse 服务。这种方式非常适合本地开发与测试，是体验 云原生 应用部署的常见方式。

cd langfuse
docker compose up

启动过程中会拉取相关镜像，包括 Postgres、ClickHouse、MinIO 等组件。

[+] Running 0/5
⠏ langfuse-worker Pulling        34.0s
⠋ postgres Pulling                34.0s
⠋ clickhouse Pulling              34.0s
⠋ langfuse-web Pulling            34.0s
⠏ minio Pulling

当服务启动成功后，控制台会输出类似以下提示，其中包含了 Next.js 前端服务的访问地址：

|▲ Next.js 15.5.9
langfuse-web-1     |    - Local:        http://ff7bf206810a:3000
langfuse-web-1     |    - Network:      http://ff7bf206810a:3000

在浏览器中打开 http://127.0.0.1:3000，即可看到 Langfuse 的 Web 管理界面。

创建与配置 API Key

首次使用需要创建一个项目，并申请 API Key 用于代码集成。

1. 在界面中创建新项目。
2. 进入项目设置，在 “API Keys” 选项卡中生成新的密钥对（Public Key 和 Secret Key）。

申请到 API Key 后，即可开始在代码层面进行集成。首先，在项目根目录创建 .env 文件，并填入上面申请的密钥以及服务地址：

LANGFUSE_SECRET_KEY = "sk-lf-00820f1a-e42b-4794-90f5-7967e5ec92ca"
LANGFUSE_PUBLIC_KEY = "pk-lf-1763ff0c-45f9-481c-b3eb-83efb5e5854f"
LANGFUSE_BASE_URL = "http://127.0.0.1:3000"

代码集成与监控实战

接下来，我们编写一个简单的 Python 脚本来演示如何集成。可以看到，Langfuse 的集成非常简洁，通常只需要在目标函数上添加一个 @observe() 装饰器。

from langfuse import observe
from langfuse.openai import openai # OpenAI integration
from dotenv import load_dotenv
from openai import OpenAI

# 加载.env文件中的环境变量
load_dotenv()

@observe()
def story():
    api_key = "xx"  # 替换为实际API密钥
    base_url = ""   # 替换为实际API路径
    client = OpenAI(base_url=base_url, api_key=api_key)
    return client.chat.completions.create(
        model="xxx",                     # 指定模型版本
        messages=[{"role": "user", "content": "What is Langfuse?"}],
    ).choices[0].message.content

@observe()
def main():
    return story()

main()

使用以下命令安装依赖并运行脚本：

uv init
uv add -i https://mirrors.aliyun.com/pypi/simple/ langfuse openai
uv add -i https://mirrors.plus/pypi/simple/ dotenv
uv run ./main.py

脚本执行后，再次打开 http://127.0.0.1:3000 的监控界面，就能看到刚才函数执行的详细追踪信息，包括调用链、输入输出和耗时等。

原理浅析：@observe() 装饰器

为了理解其工作原理，我们可以查看 @observe 装饰器的定义。其核心实现在 langfuse/_client/observe.py 文件中。

关键代码节选如下，它主要完成了在函数执行前后进行日志记录和数据上报的功能：

def observe(
    self,
    func: Optional[F] = None,
    *,
    name: Optional[str] = None,
    as_type: Optional[ObservationTypeLiteralNoEvent] = None,
    capture_input: Optional[bool] = None,
    capture_output: Optional[bool] = None,
    transform_to_string: Optional[Callable[[Iterable], str]] = None,
) -> Union[F, Callable[[F], F]]:
    # ... 参数处理逻辑 ...
    with _set_current_public_key(public_key):
        langfuse_client = get_client(public_key=public_key)
        context_manager = (
            langfuse_client.start_as_current_observation(
                name=final_name,
                as_type=as_type or "span",
                trace_context=trace_context,
                input=input,
                end_on_exit=False,
            )
            if langfuse_client
            else None
        )
    # ... 执行函数并处理输出的逻辑 ...

其内部机制与常见的日志装饰器类似，核心是围绕 langfuse_client.start_as_current_observation 方法创建了一个观测上下文，在此上下文中执行的函数调用、输入输出等信息会被自动捕获并发送到 Langfuse 服务端，最终在 人工智能 应用的可观测面板上呈现。