Langfuse v4

Langfuse v4 围绕 observations 重建了数据模型:trace 级属性存在于每个 observation 上,且记录是不可变的(写一次,永不更新)。读取不再需要 join 或去重,因此查询在规模化时快了一个数量级。本页解释了什么发生了变化以及为什么。要迁移,请遵循逐步升级指南;版本与兼容性矩阵展示了什么与什么兼容。

初次接触 Langfuse?没有需要迁移的内容。从入门指南开始;它已经使用 v4。

时间线

在 Langfuse Cloud 上,查看你项目在应用中的剩余迁移操作。

升级

遵循逐步升级指南。它涵盖每种情况:使用旧 SDK 的 Langfuse Cloud、使用当前 SDK 的 Langfuse Cloud、直接使用 API 和 OpenTelemetry 的用户,以及自托管部署。

发生了什么变化

新的心智模型:Langfuse 存储一张不可变的 observations 表。trace 仅仅是共享同一 trace_id 的所有行,而 trace 级属性被复制到每一行上:

Trace 级的 input/output 在整个产品中已弃用。 每个之前读取 trace 输入和输出的功能(UI 中的表格、LLM-as-a-judge 评估器、导出)现在读取正确 observation 的输入和输出,通常是持有相关数据的根 span 或 LLM 调用。选择一个持有正确数据的 observation,而非在整个 trace 中拼装它,是加载速度变快的重要原因。

为什么 observations 优先:两个问题推动了这一变化。首先,agentic traces 变得很大,单一 trace 的 input/output 不再是你关心的:你关心的是运行中的某个特定子 agent、某个特定工具调用或某个特定 LLM 调用。以 observations 作为主要实体,你可以直接查询它们("哪些 LLM 调用很慢?"),并且 observation 级评估在几秒内完成。其次,可扩展性:应用随着 agent 推进不断更新 trace 输出,每次更新都创建另一个记录版本,Langfuse 必须在读取时去重,从而降低了整个产品的性能。不可变 observations 消除了这一成本。数据模型文档解释了该模型;observations 指南涵盖了 UI 中的日常工作流。

问题

在专门的 GitHub Discussion 中提出上线和迁移问题;我们用该线程发布更新和答案。