文档 / Python v2 → v3

Python v2 → v3

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

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

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

Langfuse SDK 现在是 OpenTelemetry 原生的。升级后,Langfuse 还可以捕获应用中其他 OpenTelemetry 埋点库发出的 spans,例如数据库、HTTP 或框架埋点。

这可能会添加许多与 LLM 可观测性无关的基础设施 spans,并可能显著增加你的 Langfuse 账单。在广泛推出升级之前,请查看你的 traces,并使用按埋点作用域过滤指南按埋点作用域过滤掉不需要的 spans。

对 SDK v2 的核心变更:

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

按集成类型的迁移路径

@observe 装饰器用户

v2 模式:

python

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 迁移:

python

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 模式:

python

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 字段(最简单的迁移):

python

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(更多控制):

python

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

v2 模式:

python

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:在链调用中使用 metadata 字段(最简单的迁移):

python

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(更多控制):

python

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 模式:

python

from langfuse.llama_index import LlamaIndexCallbackHandler

handler = LlamaIndexCallbackHandler()
Settings.callback_manager = CallbackManager([handler])

response = index.as_query_engine().query("Hello")

v3 迁移:

python

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 模式:

python

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 中,所有 spans / generations 必须通过在返回的对象上调用 .end() 来结束。

python

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 迁移指南。

关键迁移清单

更新导入:
- 使用 from langfuse import get_client 访问通过环境变量配置的全局客户端实例
- 使用 from langfuse import Langfuse 创建通过构造函数参数配置的新客户端实例
- 使用 from langfuse import observe 导入 observe 装饰器
- 更新集成导入: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 的自动派生
上下文管理器:
- 如果你想使用手动 langfuse.trace()、trace.span(),请替换为上下文管理器
- 改用 with langfuse.start_as_current_observation()
LlamaIndex 迁移:
- 用第三方 OTEL 埋点替换 Langfuse 回调
- 安装: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) 从外部系统生成确定性的 trace ID

python

   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
数据集

数据集条目对象上的 link 方法已被一个上下文管理器替换,该上下文管理器可通过数据集条目上的 run 方法访问。这是一个更高级别的抽象,管理 trace 创建以及数据集条目与结果 trace 的链接。

更多细节参见数据集文档。

详细变更摘要

核心变更:OpenTelemetry 基础
- 构建在 OpenTelemetry 标准之上,以获得更好的生态系统兼容性
Trace 输入/输出行为
- v2:集成可以直接设置 trace 输入/输出
- v3:Trace 输入/输出默认派生自根 observation
- 迁移:通过 span.update_trace(input=..., output=...) 显式设置
Trace 属性位置
- v2:可以直接在集成调用上设置
- v3:必须在外层 spans 上设置
- 迁移:用 langfuse.start_as_current_observation() 包装集成调用
创建 Observations:
- v2:langfuse.trace()、langfuse.span()、langfuse.generation()
- v3:langfuse.start_as_current_observation()
- 迁移:使用上下文管理器,确保调用 .end() 或使用 with 语句
ID 和上下文:

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。

Langfuse SDK 现在是 OpenTelemetry 原生的。升级后,Langfuse 还可以捕获应用中其他 OpenTelemetry 埋点库发出的 spans,例如数据库、HTTP 或框架埋点。

这可能会添加许多与 LLM 可观测性无关的基础设施 spans,并可能显著增加你的 Langfuse 账单。在广泛推出升级之前,请查看你的 traces,并使用按埋点作用域过滤指南按埋点作用域过滤掉不需要的 spans。

初始化

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

追踪

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

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

各项细节参见 SDK v4 文档。

提示词管理

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

typescript

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

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

typescript

  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() 选项对象的一个可选属性,而非位置参数。

typescript

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

OpenAI 集成

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

typescript

  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 集成的导入现在是:

typescript

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

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

`langfuseClient.getTraceUrl`

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

typescript

  const traceUrl = await langfuseClient.getTraceUrl(traceId);

打分

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

typescript

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

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

typescript

  const langfuse = new LangfuseClient();

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

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

数据集

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