Python v2 → v3

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

Python SDK v3 相比旧版 v2 SDK 引入了显著改进与变更，不完全向后兼容。本完整指南将帮助你根据当前的集成方式进行迁移。

你可以在这里找到 v2 SDK 文档的快照。

⚠️

Langfuse SDK 现在原生支持 OpenTelemetry。升级后，Litefuse 也可以捕获你应用中其他 OpenTelemetry instrumentation 库（如数据库、HTTP 或框架的 instrumentation）发出的 span。

这可能引入大量与 LLM 可观测性无关的基础设施 span，并可能显著增加你的 Litefuse 账单。在大范围推广升级之前，请审视你的 trace 并按 instrumentation scope 过滤掉不需要的 span，参见按 instrumentation scope 过滤指南。

相对 SDK v2 的核心变更：

OpenTelemetry 基础：v3 构建在 OpenTelemetry 标准之上
Trace 输入/输出：默认从根 observation 派生
Trace 属性（user_id、session_id 等）：可以通过外层 span 设置，或直接通过集成的 metadata 字段（OpenAI 调用、Langchain 调用）设置
上下文管理：自动的 OTEL 上下文传播

按集成类型的迁移路径

@observe 装饰器用户

v2 模式：

from langfuse.decorators import langfuse_context, observe
 
@observe()
def my_function():
    # This was the trace
    langfuse_context.update_current_trace(user_id="user_123")
    return "result"

v3 迁移：

from langfuse import observe, get_client # new import
 
@observe()
def my_function():
    # This is now the root span, not the trace
    langfuse = get_client()
 
    # Update trace explicitly
    langfuse.update_current_trace(user_id="user_123")
    return "result"

OpenAI 集成

v2 模式：

from langfuse.openai import openai
 
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    # Trace attributes directly on the call
    user_id="user_123",
    session_id="session_456",
    tags=["chat"],
    metadata={"source": "app"}
)

v3 迁移：

如果你没有设置额外的 trace 属性，无需任何改动。

如果你设置了额外的 trace 属性，有两种选择：

方式 1：使用 metadata 字段（最简单的迁移方式）：

from langfuse.openai import openai
 
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    metadata={
        "langfuse_user_id": "user_123",
        "langfuse_session_id": "session_456",
        "langfuse_tags": ["chat"],
        "source": "app"  # Regular metadata still works
    }
)

方式 2：使用外层 span（控制更精细）：

from langfuse import get_client, propagate_attributes
from langfuse.openai import openai
 
langfuse = get_client()
 
with langfuse.start_as_current_observation(as_type="span", name="chat-request") as span:
 
    with propagate_attributes(
        user_id="user_123",
        session_id="session_456",
        tags=["chat"],
    ):
 
        response = openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Hello"}],
            metadata={"source": "app"}
        )
 
        # Set trace input and output explicitly
        span.update_trace(
            output={"response": response.choices[0].message.content},
            input={"query": "Hello"},
            )

⚠️

update_trace() 在 Python SDK v4 中已被弃用。参见 v3 → v4 迁移指南。

LangChain 集成 [#langchain-integration]

v2 模式：

from langfuse.callback import CallbackHandler
 
handler = CallbackHandler(
    user_id="user_123",
    session_id="session_456",
    tags=["langchain"]
)
 
response = chain.invoke({"input": "Hello"}, config={"callbacks": [handler]})

v3 迁移：

设置 trace 属性有两种选择：

方式 1：在 chain 调用中使用 metadata 字段（最简单的迁移方式）：

from langfuse.langchain import CallbackHandler
 
handler = CallbackHandler()
 
response = chain.invoke(
    {"input": "Hello"},
    config={
        "callbacks": [handler],
        "metadata": {
            "langfuse_user_id": "user_123",
            "langfuse_session_id": "session_456",
            "langfuse_tags": ["langchain"]
        }
    }
)

方式 2：使用外层 span（控制更精细）：

from langfuse import get_client, propagate_attributes
from langfuse.langchain import CallbackHandler
 
langfuse = get_client()
 
with langfuse.start_as_current_observation(as_type="span", name="langchain-request") as span:
 
    with propagate_attributes(
        user_id="user_123",
        session_id="session_456",
        tags=["langchain"],
    ):
 
        handler = CallbackHandler()
        response = chain.invoke({"input": "Hello"}, config={"callbacks": [handler]})
 
        # Set trace input and output explicitly
        span.update_trace(
            input={"query": "Hello"},
            output={"response": response}
            )

⚠️

update_trace() 在 Python SDK v4 中已被弃用。参见 v3 → v4 迁移指南。

LlamaIndex 集成用户

v2 模式：

from langfuse.llama_index import LlamaIndexCallbackHandler
 
handler = LlamaIndexCallbackHandler()
Settings.callback_manager = CallbackManager([handler])
 
response = index.as_query_engine().query("Hello")

v3 迁移：

from langfuse import get_client, propagate_attributes
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
 
# Use third-party OTEL instrumentation
LlamaIndexInstrumentor().instrument()
 
langfuse = get_client()
 
with langfuse.start_as_current_observation(as_type="span", name="llamaindex-query") as span:
 
    with propagate_attributes(
        user_id="user_123",
    ):
        response = index.as_query_engine().query("Hello")
 
    span.update_trace(
        input={"query": "Hello"},
        output={"response": str(response)}
        )

⚠️

update_trace() 在 Python SDK v4 中已被弃用。参见 v3 → v4 迁移指南。

底层 SDK 用户

v2 模式：

from langfuse import Langfuse
 
langfuse = Langfuse()
 
trace = langfuse.trace(
    name="my-trace",
    user_id="user_123",
    input={"query": "Hello"}
)
 
generation = trace.generation(
    name="llm-call",
    model="gpt-4o"
)
generation.end(output="Response")

v3 迁移：

在 v3 中，所有 span / generation 必须通过对返回对象调用 .end() 来结束。

from langfuse import get_client, propagate_attributes
 
langfuse = get_client()
 
# Use context managers instead of manual objects
with langfuse.start_as_current_observation(
    as_type="span",
    name="my-trace",
    input={"query": "Hello"}  # Becomes trace input automatically
) as root_span:
 
    # Propagate trace attributes to all child observations
    with propagate_attributes(
        user_id="user_123",
    ):
 
        with langfuse.start_as_current_observation(
            as_type="generation",
            name="llm-call",
            model="gpt-4o"
        ) as generation:
            generation.update(output="Response")
 
        # If needed, override trace output
        root_span.update_trace(
            input={"query": "Hello"},
            output={"response": "Response"}
            )

⚠️

update_trace() 在 Python SDK v4 中已被弃用。参见 v3 → v4 迁移指南。

关键迁移清单

更新 import：
- 使用 from langfuse import get_client 访问由环境变量配置的全局客户端实例
- 使用 from langfuse import Langfuse 创建一个新的、由构造函数参数配置的客户端实例
- 使用 from langfuse import observe import observe 装饰器
- 更新集成 import：from langfuse.langchain import CallbackHandler
Trace 属性模式：
- 方式 1：直接在集成调用中使用 metadata 字段（langfuse_user_id、langfuse_session_id、langfuse_tags）
- 方式 2：将 user_id、session_id、tags 移至 propagate_attributes()
Trace 输入/输出：
- 对 LLM-as-a-judge 至关重要：显式设置 trace 输入/输出
- 如果你需要特定值，不要依赖从根 observation 自动派生
Context manager：
- 如果想使用，请把手动的 langfuse.trace()、trace.span() 替换为 context manager
- 改为使用 with langfuse.start_as_current_observation()
LlamaIndex 迁移：
- 用第三方 OTEL instrumentation 替代 Langfuse 的 callback
- 安装：pip install openinference-instrumentation-llama-index

ID 管理：

不支持自定义 observation ID：v3 使用 W3C Trace Context 标准——你不能设置自定义 observation ID
Trace ID 格式：必须是 32 字符的小写十六进制（16 字节）
外部 ID 关联：使用 Langfuse.create_trace_id(seed=external_id) 从外部系统的 ID 生成确定性的 trace ID

from langfuse import Langfuse, observe
 
# v3: Generate deterministic trace ID from external system
external_request_id = "req_12345"
trace_id = Langfuse.create_trace_id(seed=external_request_id)
 
@observe(langfuse_trace_id=trace_id)
def my_function():
    # This trace will have the deterministic ID
    pass

初始化：
- 替换构造函数参数：
  - enabled → tracing_enabled
  - threads → media_upload_thread_count
数据集

dataset item 对象上的 link 方法已被替换为可通过 dataset item 上的 run 方法访问的 context manager。这是一个更高层的抽象，会自动管理 trace 创建以及把 dataset item 与生成的 trace 关联。

详情参见数据集文档。

详细变更摘要

核心变更：OpenTelemetry 基础
- 构建在 OpenTelemetry 标准之上，与生态有更好的兼容性
Trace 输入/输出行为
- v2：集成可以直接设置 trace 输入/输出
- v3：trace 输入/输出默认从根 observation 派生
- 迁移：通过 span.update_trace(input=..., output=...) 显式设置
Trace 属性的位置
- v2：可以直接设置在集成调用上
- v3：必须设置在外层 span 上
- 迁移：用 langfuse.start_as_current_observation() 包裹集成调用
创建 observation：
- v2：langfuse.trace()、langfuse.span()、langfuse.generation()
- v3：langfuse.start_as_current_observation()
- 迁移：使用 context manager，确保调用 .end() 或使用 with 语句
ID 与 context：

v3：W3C Trace Context 格式，自动上下文传播
迁移：使用 langfuse.get_current_trace_id() 替代 get_trace_id()

事件大小限制：
- v2：事件大小限制为 1MB
- v3：SDK 端不再对事件强制限制大小

未来对 v2 的支持

我们将在可预见的未来继续支持 v2 SDK，提供关键 bug 修复和安全补丁。我们不会再向 v2 SDK 添加新功能。你可以在这里找到 v2 SDK 文档的快照。

JS/TS SDK v3 → v4

请按照下面每个章节将你的应用从 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,
});

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

数据集

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

Python v3 → v4 JS/TS v4 → v5

这个页面对你有帮助吗？

支持