基础使用指南

概述

本文档介绍 Langfuse JS/TS SDK 的基本使用方法。通过本指南，您将了解如何：

• 创建和管理 Trace
• 记录不同类型的观测数据
• 集成常用的 LLM 框架
• 处理短期运行环境
• 使用调试功能

Trace 管理

创建 Trace

Trace 创建

Trace 是所有观测数据的顶层容器，用于记录一次完整的功能执行过程。建议为每个独立的用户请求或任务创建一个新的 Trace：

// 创建新的 Trace
const trace = langfuse.trace({
  name: "chat-app-session", // 功能名称
  userId: "user_123456789", // 用户标识
  metadata: { user: "user@example.com" }, // 附加信息
  tags: ["production"], // 环境标签
});

// 使用自定义 ID 创建 Trace
const trace = langfuse.trace({
  id: "custom-trace-001", // 自定义追踪 ID
  name: "chat-app-session",
});

更新 Trace

Trace 更新

您可以随时更新 Trace 的属性，用于记录状态变化：

trace.update({
  metadata: {
    status: "completed",
    processingTime: 1500,
  },
  tags: ["processed"],
});

Observation 管理

创建 Event

Event 使用场景

Event 用于记录离散的事件点，如：

• 用户操作
• 系统状态变更
• 关键节点执行
• 错误发生

const event = trace.event({
  name: "get-user-profile",
  metadata: {
    attempt: 2,
    httpRoute: "/api/retrieve-person",
  },
  input: {
    userId: "user_123456789",
  },
  output: {
    firstName: "张",
    lastName: "三",
    email: "zhangsan@example.com",
  },
});

创建 Span

Span 使用场景

Span 用于记录一段时间内的执行过程，如：

• API 调用
• 数据处理
• 资源加载
• 计算任务

// 创建并开始计时
const span = trace.span({
  name: "embedding-retrieval",
  input: {
    userInput: "如何使用 Langfuse？",
  },
});

// 执行操作
const retrievedDocs = await retrieveDoc("如何使用 Langfuse？");

// 结束 Span 并记录输出
span.end({
  output: {
    retrievedDocs,
  },
  metadata: {
    docCount: retrievedDocs.length,
  },
});

创建 Generation

Generation 使用场景

Generation 用于记录 AI 模型的生成过程，包括：

• 模型调用参数
• 输入提示词
• 生成结果
• token 使用统计

const generation = trace.generation({
  name: "chat-completion",
  model: "gpt-3.5-turbo",
  modelParameters: {
    temperature: 0.9,
    maxTokens: 2000,
  },
  input: messages,
});

// 执行生成
const chatCompletion = await llm.respond(prompt);

// 记录生成结果
generation.end({
  output: chatCompletion,
  metadata: {
    tokensUsed: chatCompletion.usage.total_tokens,
  },
});

框架集成

OpenAI 集成

OpenAI 集成说明

使用 OpenAI 集成可以自动捕获以下信息：

• 模型名称和参数
• 输入提示词
• 生成结果
• Token 使用统计
• 响应延迟

import { observeOpenAI } from "langfuse-openai";
import OpenAI from "openai";

const openai = new OpenAI();

// 创建 Span 作为父容器
const span = trace.span({ name: "OpenAI-Chat" });

// 使用 observeOpenAI 包装 OpenAI 调用
const response = await observeOpenAI(openai, {
  parent: span,
  generationName: "chat-completion",
}).chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: [
    { role: "system", content: "你是一个助手。" },
    { role: "user", content: "介绍一下自己。" },
  ],
});

span.end();

LangChain 集成

LangChain 集成说明

使用 LangChain 集成可以自动追踪：

• Chain 执行过程
• 中间步骤结果
• 模型调用信息
• 错误和异常

import { CallbackHandler } from "langfuse-langchain";
import { ChatOpenAI } from "@langchain/openai";
import { PromptTemplate } from "@langchain/core/prompts";
import { RunnableSequence } from "@langchain/core/runnables";

// 创建 Span 作为父容器
const span = trace.span({ name: "LangChain-Chat" });

// 创建 LangChain 处理器
const handler = new CallbackHandler({ root: span });

// 创建并执行 Chain
const model = new ChatOpenAI({});
const promptTemplate = PromptTemplate.fromTemplate("讲一个关于{topic}的笑话");
const chain = RunnableSequence.from([promptTemplate, model]);

const result = await chain.invoke(
  { topic: "程序员" },
  { callbacks: [handler] }
);

span.end();

短期环境处理

短期环境注意事项

在 Serverless 等短期环境中，需要确保在函数结束前等待数据发送完成：

// Vercel Edge Function
import { waitUntil } from "@vercel/functions";

export default async function handler(req, res) {
  const trace = langfuse.trace({ name: "edge-function" });
  // ... 处理逻辑 ...

  // 等待数据发送
  waitUntil(langfuse.flushAsync());

  return res.json({ status: "success" });
}

// AWS Lambda
export const handler = async (event) => {
  const trace = langfuse.trace({ name: "lambda-function" });
  // ... 处理逻辑 ...

  // 等待数据发送
  await langfuse.shutdownAsync();

  return { statusCode: 200 };
};

调试功能

调试功能说明

SDK 提供了多种调试功能帮助排查问题：

• 调试日志输出
• 错误事件监听
• 配置验证检查

// 启用调试日志
langfuse.debug();

// 监听错误
langfuse.on("error", (error) => {
  console.error("Langfuse 错误:", error);
});

// 验证配置
const isValid = await langfuse.authCheck();
console.log("配置是否有效:", isValid);

注意事项

1. 在生产环境中建议关闭调试模式
2. 错误监听应该根据实际需求进行处理
3. 定期验证配置确保正常运行