Langfuse SDK

Litefuse 提供两套 SDK：

• Python
• JS/TS
• 通过 OpenTelemetry 支持的 其他语言

Langfuse SDK 是创建自定义 observation 与 trace，以及使用 Litefuse prompt 管理和评估功能的推荐方式。

核心优势

• 基于 OpenTelemetry，因此你可以使用任何基于 OTEL 的 instrumentation 库为你的 LLM 技术栈做埋点。
• 完全异步请求，意味着 Litefuse 几乎不增加延迟。
• 与 Litefuse 原生集成互操作。
• 通过同步时间戳实现准确的延迟追踪。
• 提供可在下游使用的 ID。
• 嵌套 observation 时具备良好的 DX。
• 不会破坏你的应用：SDK 错误会被捕获并记录。

快速开始

跟随快速开始指南把第一条 trace 上报到 Litefuse。更多细节请参见安装设置章节。

pip install langfuse

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://litefuse.cloud"

from langfuse import get_client
 
langfuse = get_client()
 
# Create a span using a context manager
with langfuse.start_as_current_observation(as_type="span", name="process-request") as span:
    # Your processing logic here
    span.update(output="Processing complete")
 
    # Create a nested generation for an LLM call
    with langfuse.start_as_current_observation(as_type="generation", name="llm-response", model="gpt-3.5-turbo") as generation:
        # Your LLM call logic here
        generation.update(output="Generated response")
 
# All spans are automatically closed when exiting their context blocks
 
 
# Flush events in short-lived applications
langfuse.flush()

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

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://litefuse.cloud"

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
 
export const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
 
sdk.start();

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());

npx tsx index.ts

安装设置

本章节涵盖 Langfuse SDK 的所有安装细节。请按照快速开始指南来创建你的第一条 trace。

pip install langfuse

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

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://litefuse.cloud"

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
 
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
 
sdk.start();

from langfuse import get_client
 
langfuse = get_client()
 
# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")
else:
    print("Authentication failed. Please check your credentials and host.")

from langfuse import Langfuse
 
langfuse = Langfuse(
  public_key="your-public-key",
  secret_key="your-secret-key",
  base_url="https://litefuse.cloud",
)

import { LangfuseClient } from "@langfuse/client";
 
const langfuse = new LangfuseClient();

import { LangfuseClient } from "@langfuse/client";
 
const langfuse = new LangfuseClient({
  publicKey: "your-public-key",
  secretKey: "your-secret-key",
  baseUrl: "https://litefuse.cloud", // or your self-hosted instance
});

OpenTelemetry 基础

Langfuse SDK 构建在 OpenTelemetry 之上。这带来了：

• 与更广泛的可观测性生态及工具链的标准化对接。
• 稳健的上下文传播，让嵌套 span 即便跨越异步工作负载也能保持连接。
• 属性传播，让 userId、sessionId、metadata、version 和 tags 在多个 observation 间保持一致。
• 生态互操作，意味着第三方 instrumentation 会自动出现在 Litefuse 的 trace 中。

下图展示了 Litefuse 如何映射到原生 OpenTelemetry 概念：

• OTel Trace：OTel trace 表示一次请求或事务在你的应用及其各个服务中流转的完整生命周期。trace 通常是一系列操作，例如 LLM 生成响应后跟着一个解析步骤。序列中创建的根（第一个）span 定义了 OTel trace。OTel trace 没有开始和结束时间，由根 span 定义。
• OTel Span：span 表示 trace 中的一个工作单元或操作。span 有开始和结束时间、名字，并可以拥有属性（键值对元数据）。span 可以嵌套形成层次结构，展示操作之间的父子关系。
• Litefuse Trace：Litefuse trace 收集 observation 并持有 trace 属性，例如 session_id、user_id，以及整体的输入和输出。它与 OTel trace 共享同一个 ID，其属性通过特定 OTel span 属性自动传播到 Litefuse trace。
• Litefuse Observation：在 Litefuse 的术语中，“observation” 是 OTel span 在 Litefuse 中的特定表示。它可以是通用 span（Litefuse-span）、特化的 “generation”（Litefuse-generation）、某个时刻的 event（Litefuse-event），或其他 observation 类型。
  • Litefuse Span：Litefuse-span 是 Litefuse 中通用的 OTel span，用于非 LLM 的操作。
  • Litefuse Generation：Litefuse-generation 是 Litefuse 中专门用于大语言模型（LLM）调用的 OTel span，包含额外字段如 model、model_parameters、usage_details（tokens）和 cost_details。
  • Litefuse Event：Litefuse-event 用于追踪某个时间点上的动作。
  • 其他 observation 类型：Litefuse 支持其他 observation 类型，例如工具调用、RAG 检索步骤等。
• 上下文传播：OpenTelemetry 自动处理当前 trace 和 span context 的传播。这意味着当你调用另一个函数时（无论它是否同样被 Litefuse 追踪、是 OTel instrumentation 库的，还是手动创建的 span），新创建的 span 会自动成为当前活跃 span 的子节点，从而形成正确的 trace 层级。
• 属性传播：可以通过 propagate_attributes() 将某些 trace 属性（user_id、session_id、metadata、version、tags）自动传播到所有子 observation。这能确保一条 trace 中所有 observation 的属性覆盖一致。详情见 instrumentation 文档。

Langfuse SDK 提供了对 OTel span 的封装（LangfuseSpan、LangfuseGeneration），提供了与 Litefuse 特性（如评分和媒体处理）交互的便捷方法，同时底层仍然是原生的 OTel span。你也可以使用这些封装对象通过 update_trace() 添加 Litefuse trace 属性，或使用 propagate_attributes() 自动传播到所有子 observation。

进一步学习

其他语言

Litefuse 维护 Python 和 JavaScript/TypeScript 的 SDK。其他语言可以使用我们的 OpenTelemetry endpoint 为应用做 instrumentation，并通过公共 API 使用 Litefuse 的 prompt 管理、评估和查询能力。

Instrumentation

要为应用做 instrumentation，你可以将 OpenTelemetry span 发送到 Litefuse OTel endpoint。可以使用以下 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

Prompt 管理、评估与查询：

要使用 Litefuse 的其他功能，可以通过公共 API 在任意运行时集成 Litefuse。我们也在这里整理了一份社区维护的 SDK 列表。