版本与兼容性
关于 Langfuse 的服务器、SDK 和 API 版本如何在 Langfuse Cloud 和自托管部署之间关联的参考。
Langfuse v4 已正式发布:Langfuse Cloud(自 2026 年 3 月起以预览形式推出 v4)将切换到 v4 作为唯一体验,届时剩余的旧版 API 和接入路径也会被移除。自托管版本正在路上,确切日期随后公布。
SDK 版本
| SDK | 当前主版本 | 包 | 备注 |
|---|---|---|---|
| Python SDK | v4 | langfuse |
自 v3 起基于 OpenTelemetry |
| JS/TS SDK | v5 | @langfuse/* |
自 v4 起基于 OpenTelemetry。需要 Node.js 20+。 |
| 其他语言 | n/a | OpenTelemetry | 任何 OTel SDK 到 Langfuse OTel 端点 |
功能可用性矩阵
Langfuse Cloud 在 v4 切换之前并行运行 v3 和 v4(日期随后公布)。v3 列已弃用:下面标记为 Deprecated 的所有内容在切换之前继续工作,然后被移除。点击行查看详情。
自托管 Langfuse?请改用自托管兼容性矩阵;它涵盖每个服务器版本和每个 SDK 的最低服务器版本。
| 功能 | Langfuse Cloud v3(已弃用) | Langfuse Cloud v4(GA) |
|---|---|---|
| Python · 升级指南 | ||
| Python SDK v4 | 完整 | 完整 |
| Python SDK v3 | 完整 | 已弃用 |
| Python SDK v2 | 完整 | 已弃用 |
| Python SDK v1 | 不支持 | 不支持 |
| JS/TS · 升级指南 | ||
| JS/TS SDK v5 | 完整 | 完整 |
| JS/TS SDK v4 | 完整 | 已弃用 |
| JS/TS SDK v3 / v2 | 完整 | 已弃用 |
| JS/TS SDK v1 | 不支持 | 不支持 |
| 第三方埋点 · OpenTelemetry 文档 | ||
OpenTelemetry /api/public/otel/v1/traces |
完整 | 完整 |
分数接入 /api/public/scores |
完整 | 完整 |
旧版接入 API /api/public/ingestion |
完整 | 已弃用 |
| 读取 API · Public API 文档 | ||
Observations API v2 & Metrics API v2 /api/public/v2/... |
完整 | 完整 |
Scores API v3 /api/public/v3/scores |
完整 | 完整 |
已弃用的读取 API traces, observations, sessions, scores, metrics, dataset runs |
完整 | 已弃用 |
| 集成与导出 · 导出文档 | ||
| Blob 存储导出 | Traces & observations | Enriched observations |
| PostHog 集成 | Traces & observations | Enriched observations |
| Mixpanel 集成 | Traces & observations | Enriched observations |
| 旧版导出源(traces 和 observations) | 完整 | 已弃用 |
| 评估 · LLM-as-a-judge 文档 | ||
| Observation 级评估器 | 完整 | 完整 |
| Trace 级评估器 | 完整 | 已弃用 |
旧版 Python SDK(v2/v3)已弃用。请升级到 Python SDK v4。在 v4 上,追踪受支持(数据最多延迟 10 分钟;Python SDK v4 ≥ 4.7.0 可实时);数据集受支持(实验需要 Python SDK v4);Public API 与查询在 v4 切换前受支持,之后移除已弃用的读取 API。
旧版 JS/TS SDK(v3/v4)已弃用。请通过 SDK 升级路径升级。在 v4 上,追踪受支持(数据最多延迟 10 分钟;JS/TS SDK v5 ≥ 5.4.0 可实时);数据集受支持(实验需要 JS/TS SDK v5);旧版批量接入在 v4 切换时移除。
常见问题
我在 Langfuse Cloud 上,需要关心哪些版本?
只需关心你的 SDK 版本和你调用的 API 端点。Langfuse Cloud 始终运行最新的服务器版本,因此自托管服务器最低版本永远不适用于你。将你的 SDK 保持在 GA 主版本(Python v4、JS/TS v5),并在 v4 切换之前迁移离开已弃用的端点(日期随后公布)。
我自托管 Langfuse v3 并升级到了 Python SDK v4 / JS SDK v5,什么能用?
追踪、提示词管理、数据集和分数完全可用(服务器 ≥ 3.63.0)。默认的 api.observations 和 api.metrics 资源调用需要 Langfuse v4 的 v2 端点;在将服务器升级到 v4 之前,请使用 api.legacy.* 资源。自托管兼容性矩阵有每个服务器版本的完整情况。
我的数据需要几分钟才在 UI 中显示,为什么?
在 v4 数据模型上,来自 Python SDK < 4.0.0、JS SDK < 5.0.0 或没有 x-langfuse-ingestion-version: 4 header 的 OTel 导出器的数据可能延迟最多 10 分钟。升级到 Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0(或设置该 header)以获得实时数据。
旧 SDK 何时在 Langfuse Cloud 上停止工作?
Python SDK v2 和 JS/TS SDK v3(及更旧版本)通过旧版批量接入 API 发送 traces,该 API 在 v4 切换时在 Langfuse Cloud 上移除(日期随后公布)。现在就升级到 GA SDK 主版本;参见 SDK 升级路径。
升级我的自托管服务器会破坏我的 SDK 吗?
每个服务器主版本支持每种语言的当前和上一个 SDK 主版本。升级 v3 → v4 保持 Python SDK v3+/v4 和 JS SDK v4/v5 工作(更旧的 SDK 失去实时可见性;Python v2 / JS v3 追踪接入在 v4 上不受支持)。升级前请检查自托管兼容性矩阵。