JS/TS v3 → v4

如果你当前使用 JS/TS SDK v3，建议直接升级到 v5（最新主版本）。请参见 JS/TS v4 → v5 迁移指南。下面 v3 → v4 的变更仍然适用——先完成它们，再按照 v4 → v5 指南操作。

请按照下面每个章节将你的应用从 v3 升级到 v4。

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

初始化

Litefuse base URL 的环境变量现在是 LANGFUSE_BASE_URL，不再是 LANGFUSE_BASEURL。出于向后兼容，后者在 v4 中仍然可用，但在未来版本中将不再支持。

Tracing

v4 SDK 的 tracing 是基于 OpenTelemetry 的重大重写，引入了若干破坏性变更。

基于 OTEL 的架构：SDK 现在构建在 OpenTelemetry 之上。需要进行 OpenTelemetry 设置，方法是把 LangfuseSpanProcessor 注册到 OpenTelemetry 的 NodeSDK 上。
新的 tracing 函数：langfuse.trace()、langfuse.span() 和 langfuse.generation() 方法已被来自 @langfuse/tracing package 的 startObservation、startActiveObservation 等替代。
职责分离：
- @langfuse/tracing 和 @langfuse/otel package 用于 tracing。
- @langfuse/client package 与 LangfuseClient 类现在仅用于评分、prompt 管理和数据集等非 tracing 功能。

详情参见 SDK v4 文档。

Prompt 管理

Import：Langfuse 客户端的 import 现在为：

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 集成

Import：OpenAI 集成的 import 现在为：

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。如果你在对 generation 跑评估，请留意这一点。

Langchain 集成

Import：Langchain 集成的 import 现在为：

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

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

`langfuseClient.getTraceUrl`

该方法现在是异步的，返回 promise

const traceUrl = await langfuseClient.getTraceUrl(traceId);

评分

Import：Langfuse 客户端的 import 现在为：

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

用法：Langfuse 客户端的用法现在为：

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

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

数据集

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

JS/TS v4 → v5 故障排查与 FAQ

这个页面对你有帮助吗？

支持