文档 / 环境(Environments)

环境(Environments)

环境(Environments)让你能够组织来自不同上下文(如生产、预发或开发)的 traces、observations 和 scores。它帮助你:

在使用同一个项目的同时,将开发数据和生产数据分开
按环境过滤和分析数据
跨环境复用数据集和提示词

你可以通过设置 LANGFUSE_TRACING_ENVIRONMENT 环境变量(推荐)或在客户端初始化时使用 environment 参数来配置环境。如果两者都指定,初始化参数优先。如果都未指定,默认环境为 default。

在 Python SDK 中,你还可以用 propagate_attributes(environment="...") 为特定的 trace 作用域设置环境。当环境属于传入的请求而非服务进程本身时,这非常有用,例如一个共享的 LLM 代理同时处理来自开发、预发、QA 和生产的请求。使用 as_baggage=True 可以跨服务边界传播该环境。

数据模型

environment 属性可用于 Langfuse 中的所有事件:

Traces
Observations(spans、events、generations)
Scores
Sessions

更多细节参见数据模型。

environment 必须是符合此正则模式的字符串:^(?!langfuse)[a-z0-9-_]+$,最多 40 个字符。

这意味着:

不能以 "langfuse" 开头
只能包含小写字母、数字、连字符和下划线

用法

python

from langfuse import get_client, observe, propagate_attributes
import os

# Set the environment variable
# Alternatively, set via .env file and load via dotenv
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"

# Get the client (will use environment variable)
langfuse = get_client()

# All operations will now be associated with the "production" environment
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Your code here
    pass

@observe
def main():
    return "Hello"

main()

# For request-scoped environments, propagate the environment explicitly.
# This maps to the first-class langfuse.environment field.
with langfuse.start_as_current_observation(as_type="span", name="proxy-request"):
    with propagate_attributes(environment="staging"):
        # All child observations created here are associated with staging.
        pass

通过环境变量设置 Langfuse 环境:

bash

export LANGFUSE_TRACING_ENVIRONMENT=production

使用 OpenTelemetry 时,你可以使用以下任意属性设置环境:

langfuse.environment
deployment.environment.name
deployment.environment

要全局设置环境属性,可以使用资源属性:os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "langfuse.environment=staging"。

或者,你可以按 span 单独设置环境:

python

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_observation("my-operation") as span:
    # Set environment using Langfuse-specific attribute
    span.set_attribute("langfuse.environment", "staging")

    # Or using OpenTelemetry convention
    span.set_attribute("deployment.environment.name", "staging")

使用 Python SDK 时,无论你使用哪个 Langfuse 维护的集成,客户端初始化时提供的环境都会应用于所有事件的输入和输出。

使用 OpenAI SDK 集成时:

python

from langfuse import Langfuse
from langfuse.openai import openai

# Either set the environment variable or configure the Langfuse client
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"

langfuse = Langfuse(environment="production")

# the integration will use the instantiated client under the hood
completion = openai.chat.completions.create(
  model="gpt-3.5-turbo",
  messages=[
    {"role": "system", "content": "You are a calculator."},
    {"role": "user", "content": "1 + 1 = "}],
)

bash.env

LANGFUSE_TRACING_ENVIRONMENT=production

import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";

const openai = observeOpenAI(new OpenAI());

更多细节参见 OpenAI 集成 (JS/TS)。

python

from langfuse.langchain import CallbackHandler

# Set the environment via environment variable before initializing the client
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
handler = CallbackHandler()

环境配置在 LangfuseSpanProcessor 上(或通过 LANGFUSE_TRACING_ENVIRONMENT 环境变量)——由 CallbackHandler 创建的 LangChain spans 会自动流经它:

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { CallbackHandler } from "@langfuse/langchain";

const sdk = new NodeSDK({
  spanProcessors: [
    new LangfuseSpanProcessor({
      environment: "production",
    }),
  ],
});
sdk.start();

const handler = new CallbackHandler();

更多细节参见 Langchain 集成 (JS/TS)。

使用 Vercel AI SDK 集成时:

tsinstrumentation.ts

import { registerOTel } from "@vercel/otel";
import { LangfuseSpanProcessor } from "@langfuse/otel";

export function register() {
  registerOTel({
    serviceName: "langfuse-vercel-ai-nextjs-example",
    spanProcessors: [new LangfuseSpanProcessor({ environment: "production" })],
  });
}

过滤

在 Langfuse UI 中,你可以使用导航栏中的环境过滤器按环境过滤事件。此过滤器适用于 Langfuse 中的所有视图。

关于如何在 API 上按环境过滤,参见我们的 API 参考。

管理环境

环境在首次以某个 environment 值接入数据时创建,并且是持久的。目前无法通过 UI 删除或重命名。

关于如何跨项目和阶段组织、隔离和使用多个环境的指导,参见 FAQ:管理不同环境。

最佳实践

一致的环境名称:在整个应用中使用一致的环境名称,让过滤和分析更容易。
按环境分析:使用环境在不同部署阶段之间分析和对比指标。
测试:使用独立的环境进行测试,避免污染生产数据。