ByteHouse 全托管 Langfuse 基于社区版 Langfuse 4.56.0 开发。用户从自建 Langfuse V3 升级到 ByteHouse 全托管 Langfuse 时，需要将 SDK 升级至本文要求的版本。

Langfuse Python SDK 样例 #

安装依赖 #

示例使用 Langfuse Python SDK v4.18.0。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'langfuse==4.18.0' python-dotenv

配置凭据 #

请参见《Langfuse》的创建 API Key章节，在 ByteHouse 控制台的项目管理中为目标项目创建 API Key。请在创建成功后、关闭弹窗前保存 Public Key 和完整 Secret Key，也可下载 CSV 文件保存。已创建 API Key 时，请使用创建时保存的完整 Secret Key。

在 .env 中配置以下环境变量。LANGFUSE_BASE_URL 填写分配给你的服务根地址，端口号以部署时指定的值为准，默认端口为 3000。以下示例使用默认端口，请根据实际服务地址调整。

LANGFUSE_BASE_URL="https://your-langfuse.example.com:3000"
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."

上报示例 #

from dotenv import load_dotenv
from langfuse import Langfuse, propagate_attributes

load_dotenv("<your .env>")
lf = Langfuse(additional_headers={"x-langfuse-ingestion-version": "4"})
# 自动读取 .env 中的地址和项目密钥。

with lf.start_as_current_observation(
    name="chat", as_type="span", input={"message": "hi"}
) as root:
    with propagate_attributes(
        user_id="demo-user",
        session_id="demo-session",
        trace_name="chat",
        tags=["demo", "v4"],
        metadata={"channel": "web"},
        version="1.0.0",
        environment="staging",
    ):
        with lf.start_as_current_observation(
            name="llm", as_type="generation", model="demo-model",
            input={"message": "hi"},
        ) as generation:
            generation.update(output={"message": "hello"})
        root.update(output={"message": "hello"})

lf.flush()

OpenTelemetry SDK 样例 #

安装依赖 #

python3 -m venv .venv
source .venv/bin/activate
python -m pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http python-dotenv

配置凭据 #

认证使用目标项目的 Public Key 和 Secret Key。API Key 的创建流程请参见《Langfuse》的创建 API Key章节。请在创建成功后、关闭弹窗前保存完整 Secret Key，也可下载 CSV 文件保存。已创建 API Key 时，请使用创建时保存的完整 Secret Key。

在 .env.otel 中配置 traces 完整地址和 Basic Auth 请求头。服务地址中的端口号以部署时指定的值为准，默认端口为 3000，并保留 /api/public/otel/v1/traces 路径。以下示例使用默认端口，请根据实际服务地址调整。

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://your-langfuse.example.com:3000/api/public/otel/v1/traces"
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Basic <PK:SK 的 Base64 编码>,x-langfuse-ingestion-version=4"

将占位符替换为该项目 Public Key:Secret Key 的 Base64 编码。获取方式：

printf '%s' "${LANGFUSE_PUBLIC_KEY}:${LANGFUSE_SECRET_KEY}" | base64 | tr -d '\r\n'

上报示例 #

import json

from dotenv import load_dotenv
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

load_dotenv("<your .env.otel>")
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
tracer = provider.get_tracer("demo.native-otel")

common = {
    "langfuse.user.id": "demo-user",
    "langfuse.session.id": "demo-session",
    "langfuse.trace.name": "chat",
    "langfuse.trace.tags": ["demo", "v4"],
    "langfuse.trace.metadata.channel": "web",
    "langfuse.version": "1.0.0",
    "langfuse.release": "demo-2026.10",
    "langfuse.environment": "staging",
}

try:
    with tracer.start_as_current_span("chat", attributes=common) as root:
        root.set_attribute("langfuse.observation.type", "span")
        root.set_attribute("langfuse.observation.input", json.dumps({"message": "hi"}))
        with tracer.start_as_current_span("llm", attributes=common) as generation:
            generation.set_attribute("langfuse.observation.type", "generation")
            generation.set_attribute("langfuse.observation.model.name", "demo-model")
            generation.set_attribute("langfuse.observation.input", json.dumps({"message": "hi"}))
            generation.set_attribute("langfuse.observation.output", json.dumps({"message": "hello"}))
        root.set_attribute("langfuse.observation.output", json.dumps({"message": "hello"}))
finally:
    provider.force_flush()
    provider.shutdown()

Python SDK 凭据配置

Python SDK v4 使用与迁移

原生 OTel 接入

OTel 适配 Langfuse V4

sdk兼容矩阵