文档 / 发布与版本(Releases & Versioning)

发布与版本(Releases & Versioning)

你可以在 Langfuse 中追踪 LLM 应用变更对指标的影响。这让你能够:

在生产环境**运行实验(A/B 测试)**并衡量对成本、延迟和质量的影响。
- 示例:"切换到新模型的影响是什么?"
解释指标随时间的变化。
- 示例:"为什么这条链路的延迟增加了?"

Releases(发布)

mermaid


flowchart LR

    A1[LLM application<br/>release:v2.1.23]
    A2[LLM application<br/>release:v2.1.24]

    A1 --> A2

release 追踪应用的整体版本。通常它被设置为应用的_语义化版本_或 git commit hash。

SDK 按以下顺序查找 release:

SDK 初始化
环境变量
在流行的部署平台上自动设置的 release 标识符

初始化

Python SDK 允许你在初始化客户端时设置 release:

python

from langfuse import Langfuse

# Set the release when initializing the client
langfuse = Langfuse(release="v2.1.24")

JS/TS SDK 会查找 LANGFUSE_RELEASE 环境变量。用它来配置 release,例如在你的 CI/CD 流水线中。

bash

LANGFUSE_RELEASE = "<release_tag>" # <- github sha or other identifier

SDK 会查找 LANGFUSE_RELEASE 环境变量。用它来配置 release,例如在你的 CI/CD 流水线中。

bash

LANGFUSE_RELEASE = "<release_tag>" # <- github sha or other identifier

在流行平台上自动设置

如果没有设置其他 release,Langfuse SDK 会默认使用一组已知的 release 环境变量。

支持的平台包括:Vercel、Heroku、Netlify。完整的支持环境变量列表参见 JS/TS 和 Python。

Versions(版本)

mermaid


flowchart LR

    A1[Generation<br/>name:guess-countries<br/>version:1.0]
    A2[Generation<br/>name:guess-countries<br/>version:1.1]

    A1 --> A2

version 参数可以添加到所有 observation 类型(例如 span、generation、event 和其他 observation 类型)。由此,你可以使用 Langfuse analytics 追踪新 version 对具有特定 name 的对象指标的影响。

在某个上下文内的所有 observations 上设置版本:

python

from langfuse import observe, propagate_attributes

@observe()
def process_data():
    # Propagate version to all child observations
    with propagate_attributes(version="1.0"):
        # All nested operations automatically inherit version
        result = perform_processing()

        return result

直接创建 observations 时:

python

from langfuse import get_client, propagate_attributes

langfuse = get_client()

with langfuse.start_as_current_observation(as_type="span", name="process-data") as span:
    # Propagate version to all child observations
    with propagate_attributes(version="1.0"):
        # All observations created here automatically have version="1.0"
        with span.start_as_current_observation(
            as_type="generation",
            name="guess-countries",
            model="gpt-4o"
        ) as generation:
            # This generation automatically has version="1.0"
            pass

在特定 observation 上设置版本:

python

from langfuse import get_client

langfuse = get_client()

with langfuse.start_as_current_observation(as_type="span", name="process-data", version="1.0") as span:
    # This span has version="1.0"
    pass

将版本传播到某个上下文内的所有 observations:

import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";

await startActiveObservation("process-data", async (span) => {
  // Propagate version to all child observations
  await propagateAttributes(
    {
      version: "1.0",
    },
    async () => {
      // All observations created here automatically have version="1.0"
      const generation = startObservation(
        "guess-countries",
        { model: "gpt-4" },
        { asType: "generation" }
      );
      // This generation automatically has version="1.0"
      generation.end();
    }
  );
});

在特定 observation 上设置版本:

import { startObservation } from "@langfuse/tracing";

const generation = startObservation(
  "guess-countries",
  { model: "gpt-4" },
  { asType: "generation" }
);
generation.update({ version: "1.0" });
generation.end();

python

from langfuse import propagate_attributes
from langfuse.langchain import CallbackHandler

handler = CallbackHandler()

# Propagate version to all observations created within the scope
with propagate_attributes(version="1.0"):
    chain.invoke({"input": "<user_input>"}, config={"callbacks": [handler]})

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

const handler = new CallbackHandler({
  version: "1.0",
});

Langfuse 界面中的 version 参数

单个 generation 上的版本