Langfuse SDK

Langfuse 提供两个 SDK:

• Python SDK v4
• JS/TS SDK v5
• 通过 OpenTelemetry 的其他语言

Langfuse SDK 是创建自定义 observations 和 traces以及使用 Langfuse 提示词管理和评估功能的推荐方式。

关键好处

• 基于 OpenTelemetry,因此你可以为 LLM 栈使用任何基于 OTEL 的埋点库。
• 完全异步请求,意味着 Langfuse 几乎不增加延迟。
• 与 Langfuse 原生集成可互操作。
• 通过同步时间戳实现准确的延迟追踪。
• ID 可用于下游使用。
• 嵌套 observations 时出色的开发体验。
• 不会破坏你的应用:SDK 错误被捕获并记录。

本节记录 Langfuse SDK 的追踪相关功能。要将 Langfuse SDK 用于提示词管理和评估,请访问它们各自的文档。

快速开始

遵循快速开始指南,将第一个 trace 接入 Langfuse。更多细节参见设置部分。

1. 安装包:

npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

2. 设置环境变量:

3. 初始化 OpenTelemetry:

创建一个 instrumentation.ts 以注册 Langfuse span processor,以便 traces 到达 Langfuse。

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

export const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});

sdk.start();

在应用入口点的顶部导入此文件(例如 index.ts)。

4. 为你的应用埋点:

埋点意味着添加记录应用中正在发生什么的代码,以便它可以发送到 Langfuse。用 TypeScript SDK 为你的代码埋点主要有三种方式。

在本示例中,我们将使用上下文管理器。你也可以使用装饰器或创建手动 observations。

import { sdk } from "./instrumentation";
import { startActiveObservation } from "@langfuse/tracing";

async function main() {
  await startActiveObservation("my-first-trace", async (span) => {
    span.update({
      input: "Hello, Langfuse!",
      output: "This is my first trace!",
    });
  });
}

// Shutdown flushes events and is required for short-lived applications
main().finally(() => sdk.shutdown());

我何时需要使用 shutdown()?

5. 运行你的应用并在 Langfuse 中查看 trace:

npx tsx index.ts

在 Langfuse 中查看该 trace。

设置

本节涵盖设置 Langfuse SDK 的所有细节。遵循快速开始指南创建你的第一个 trace。

OpenTelemetry 基础

Langfuse SDK 构建在 OpenTelemetry 之上。这提供:

• 与更广泛的可观测性生态系统和工具的标准化。
• 稳健的上下文传播,以便嵌套的 spans 保持连接,即使跨异步工作负载。
• 属性传播,以保持 userId、sessionId、metadata、version 和 tags 跨 observations 对齐。
• 生态系统互操作性,意味着第三方埋点自动出现在 Langfuse traces 内。

下图展示了 Langfuse 如何映射到原生 OpenTelemetry 概念:

graph TD
    subgraph OTEL_Core_Concepts ["OpenTelemetry"]
        direction LR
        OTEL_Trace["OTel Trace"]
        Root_OTEL_Span["Root OTel Span"]
        Child_OTEL_Span["Child OTel Span"]

        OTEL_Trace -- is defined by --> Root_OTEL_Span
        Root_OTEL_Span -- Hierarchy via <br/> Context Propagation --> Child_OTEL_Span
    end

    subgraph Langfuse_Mapping ["Langfuse"]
        direction LR
        LF_Trace["Langfuse Trace"]
        LF_Observation["Langfuse Observation <br/> (typed as either Span, Generation or Event)"]

        LF_Trace -- Collects one or more --> LF_Observation
    end

    OTEL_Trace -.->|shares ID with | LF_Trace

    Root_OTEL_Span -.->|Mapped to| LF_Observation
    Child_OTEL_Span -.->|Mapped to| LF_Observation

    Root_OTEL_Span -.->|sets default input and output | LF_Trace
    Root_OTEL_Span -.->|can hold trace attributes| LF_Trace
    Child_OTEL_Span -.->|can hold trace attributes| LF_Trace

    classDef otel fill:#D6EAF8,stroke:#3498DB,stroke-width:2px,color:#000;
    classDef langfuse fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,color:#000;
    class OTEL_Trace,Root_OTEL_Span,Child_OTEL_Span otel;
    class LF_Trace,LF_Observation langfuse;

• OTel Trace:OTel-trace 表示请求或事务在应用及其服务中流转时的整个生命周期。trace 通常是一系列操作,如 LLM 生成响应后跟一个解析步骤。序列中创建的根(第一个)span 定义 OTel trace。OTel traces 没有开始和结束时间,它们由根 span 定义。
• OTel Span:span 表示 trace 内的单个操作单元。Spans 有开始和结束时间、名称,并可以有属性(元数据的键值对)。Spans 可以嵌套以创建层级,显示操作之间的父子关系。
• Langfuse Trace:Langfuse trace 收集 observations 并持有 trace 属性,如 session_id、user_id 以及整体输入和输出。它与 OTel trace 共享相同的 ID,其属性通过特定的 OTel span 属性设置,这些属性会自动传播到 Langfuse trace。
• Langfuse Observation:在 Langfuse 术语中,"observation"是 OTel span 的 Langfuse 专属表示。它可以是通用 span(Langfuse-span)、专门的 "generation"(Langfuse-generation)、时间点事件(Langfuse-event),或其他 observation 类型。
  • Langfuse Span:Langfuse-span 是 Langfuse 中的通用 OTel span,为非 LLM 操作设计。
  • Langfuse Generation:Langfuse-generation 是 Langfuse 中专门的 OTel span 类型,专为大语言模型(LLM)调用设计。它包含额外字段,如 model、model_parameters、usage_details(tokens)和 cost_details。
  • Langfuse Event:Langfuse-event 追踪一个时间点的动作。
  • 其他 observation 类型:Langfuse 支持其他 observation 类型,如工具调用、RAG 检索步骤等。
• 上下文传播:OpenTelemetry 自动处理当前 trace 和 span 上下文的传播。这意味着当你调用另一个函数(无论它也由 Langfuse 追踪、由 OTel 埋点的库追踪,还是手动创建的 span),新 span 将自动成为当前活动 span 的子节点,形成正确的 trace 层级。
• 属性传播:某些 trace 属性(user_id、session_id、metadata、version、tags,以及 Python SDK 中请求作用域的 environment)可以使用 propagate_attributes() 自动传播到所有子 observations。这确保 trace 中所有 observations 的属性覆盖一致。细节参见埋点文档。

Langfuse SDK 提供围绕 OTel spans 的包装器(LangfuseSpan、LangfuseGeneration),提供与 Langfuse 专属功能(如打分和媒体处理)交互的便捷方法,同时在底层仍是原生 OTel spans。你也可以使用这些包装器对象通过 update_trace() 添加 Langfuse trace 属性,或使用 propagate_attributes() 自动传播到所有子 observations。

了解更多

其他语言

Langfuse 维护 Python 和 JavaScript/TypeScript 的 SDK。对于其他语言,你可以使用我们的 OpenTelemetry 端点为你的应用埋点,并使用 public API 使用 Langfuse 提示词管理、评估和查询。

埋点

要为你的应用埋点,你可以将 OpenTelemetry spans 发送到 Langfuse OTel 端点。为此,你可以使用以下 OpenTelemetry SDK:

• JetBrains Tracy for Kotlin/Java
• OpenTelemetry Java
• OpenTelemetry .NET
• OpenTelemetry Go
• OpenTelemetry C++
• OpenTelemetry Erlang/Elixir
• OpenTelemetry Ruby
• OpenTelemetry PHP
• OpenTelemetry Rust
• OpenTelemetry Swift

提示词管理、评估和查询:

要使用其他 Langfuse 功能,你可以使用 public API 从任何运行时集成 Langfuse。我们还提供一份社区维护的 SDK 列表在此。