Skip to main content

JS/TS SDK 概述

背景介绍

Lighthouse 完全兼容 Langfuse SDK，您可以使用 Langfuse JS/TS SDK 来采集 LLM 应用的可观测性数据。

SDK 提供了异步数据处理能力，可以最小化对应用性能的影响。

支持的运行时

运行环境

SDK 支持以下运行环境：

  • Node.js
  • Edge Functions (Vercel, Cloudflare 等)
  • Deno
  • 浏览器环境 (使用 LangfuseWeb)

安装

安装方式

根据您的运行环境选择合适的安装方式：

# Node.js >= 18
npm i langfuse
# 或
yarn add langfuse

# Node.js < 18
npm i langfuse-node

# Deno
import { Langfuse } from "https://esm.sh/langfuse"

配置

环境变量配置

配置建议

推荐使用环境变量方式进行配置，这样可以更好地管理敏感信息：

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_BASEURL="https://xxx.xxx.xxx"

代码配置

配置注意事项

使用代码配置时，建议在应用程序入口处进行配置：

import { Langfuse } from "langfuse"; // 或 "langfuse-node"

// 基础配置
const langfuse = new Langfuse();

// 高级配置
const langfuse = new Langfuse({
  secretKey: "sk-lf-...",
  publicKey: "pk-lf-...",
  baseUrl: "https://xxx.xxx.xxx",

  // 可选配置
  release: "v1.0.0", // 应用版本号
  requestTimeout: 10000, // 请求超时时间(ms)
  enabled: true, // 是否启用数据发送
});

主要配置参数

参数名环境变量说明默认值
secretKeyLANGFUSE_SECRET_KEY密钥-
publicKeyLANGFUSE_PUBLIC_KEY公钥-
baseUrlLANGFUSE_BASEURLAPI 地址-
releaseLANGFUSE_RELEASE应用版本号系统环境名称
requestTimeout-请求超时时间(ms)10000
enabled-是否启用数据发送true

基础概念

Trace（追踪）

Trace 说明

Trace 表示 LLM 功能的一次完整执行过程，是所有观测数据的顶层容器。每个后端执行通常使用单个 Trace 记录。

主要用途：

  • 记录完整的请求处理流程
  • 关联相关的观测数据
  • 追踪请求的生命周期
  • 分析处理耗时和性能

Observation（观测）

Observation 类型

每个 Trace 可以包含多个 Observation 来记录执行的各个步骤：

  • Event（事件）：记录离散的事件点，如用户操作、系统状态变更等
  • Span（跨度）：记录一段时间区间内的执行过程，如 API 调用、数据处理等
  • Generation（生成）：特殊的 Span 类型，专门用于记录 AI 模型的生成过程，包含输入输出和相关参数

框架支持

支持的框架

SDK 提供了与主流 LLM 框架的集成支持：

  • OpenAI：自动记录模型调用信息
  • LangChain：追踪 Chain 执行过程
  • Anthropic：记录 Claude 模型调用
  • Vercel AI SDK：支持流式响应追踪

下一步

快速开始