JS/TS v3 → v4

如果你使用的是 JS/TS SDK v3,我们建议直接升级到 v5(最新主版本)。参见 JS/TS v4 → v5 迁移指南。下面的 v3 → v4 变更仍然适用——先完成它们,然后遵循 v4 → v5 指南。

请遵循下面的每个章节,将你的应用从 v3 升级到 v4。

如果在升级过程中遇到任何问题,请在 GitHub 上提一个 issue。

初始化

Langfuse 基础 URL 环境变量现在是 LANGFUSE_BASE_URL,而不再是 LANGFUSE_BASEURL。不过为了向后兼容,后者在 v4 中仍然有效,但在未来版本中不再有效。

追踪

v4 SDK 追踪是基于 OpenTelemetry 的重大重写,并引入了若干破坏性变更。

1. 基于 OTEL 的架构:SDK 现在构建在 OpenTelemetry 之上。现在需要 OpenTelemetry 设置,通过将 LangfuseSpanProcessor 注册到 OpenTelemetry NodeSDK 来完成。
2. 新的追踪函数:langfuse.trace()、langfuse.span() 和 langfuse.generation() 方法已被 @langfuse/tracing 包中的 startObservation、startActiveObservation 等取代。
3. 职责分离:
   • @langfuse/tracing 和 @langfuse/otel 包用于追踪。
   • @langfuse/client 包和 LangfuseClient 类现在仅用于非追踪功能,如打分、提示词管理和数据集。

各项细节参见 SDK v4 文档。

提示词管理

• 导入:Langfuse 客户端的导入现在是:

  import { LangfuseClient } from "@langfuse/client";
  

• 用法:Langfuse 客户端的用法现在是:

  const langfuse = new LangfuseClient();

  const prompt = await langfuse.prompt.get("my-prompt");

  const compiledPrompt = prompt.compile({ topic: "developers" });

  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: compiledPrompt }],
  });
  

• version 现在是 langfuse.prompt.get() 选项对象的一个可选属性,而非位置参数。

  const prompt = await langfuse.prompt.get("my-prompt", { version: "1.0" });
  

OpenAI 集成

• 导入:OpenAI 集成的导入现在是:

  import { observeOpenAI } from "@langfuse/openai";
  

• 你现在可以通过 LANGFUSE_TRACING_ENVIRONMENT 和 LANGFUSE_TRACING_RELEASE 环境变量设置 environment 和 release。

Vercel AI SDK

与 v3 非常相似,但用 @langfuse/otel 中的常规 LangfuseSpanProcessor 取代了 langfuse-vercel 中的 LangfuseExporter。

更多细节请参见与 AI SDK 一起使用的完整示例。

请注意,提供给 LLM 的工具定义现在映射到 metadata.tools,而不再是 input.tools。如果你在对 generations 运行评估,这一点很重要。

Langchain 集成

• 导入:Langchain 集成的导入现在是:

  import { CallbackHandler } from "@langfuse/langchain";
  

• 你现在可以通过 LANGFUSE_TRACING_ENVIRONMENT 和 LANGFUSE_TRACING_RELEASE 环境变量设置 environment 和 release。

langfuseClient.getTraceUrl

• 该方法现在是异步的,返回一个 promise

  const traceUrl = await langfuseClient.getTraceUrl(traceId);
  

打分

• 导入:Langfuse 客户端的导入现在是:

  import { LangfuseClient } from "@langfuse/client";
  

• 用法:Langfuse 客户端的用法现在是:

  const langfuse = new LangfuseClient();

  await langfuse.score.create({
    traceId: "trace_id_here",
    name: "accuracy",
    value: 0.9,
  });
  

新的打分方法参见自定义分数文档。

数据集

新的数据集方法参见数据集文档。