文档 / 采样(Sampling)

采样(Sampling)

采样可用于控制 Langfuse 收集的 traces 量。采样在客户端处理。

你可以通过设置 LANGFUSE_SAMPLE_RATE 环境变量或使用 sample_rate/sampleRate 构造函数参数来配置采样率。该值必须介于 0 和 1 之间。

默认值为 1,意味着收集所有 traces。值为 0.2 意味着只收集 20% 的 traces。SDK 在 trace 级别采样,意味着如果一个 trace 被采样,该 trace 内的所有 observations 和 scores 也会被采样。

使用 Python SDK 时,你可以在初始化客户端时配置采样:

python

from langfuse import Langfuse, get_client
import os

# Method 1: Set environment variable
os.environ["LANGFUSE_SAMPLE_RATE"] = "0.5"  # As string in env var
langfuse = get_client()

# Method 2: Initialize with constructor parameter then get client
Langfuse(sample_rate=0.5)  # 50% of traces will be sampled
langfuse = get_client()

使用 @observe() 装饰器时:

python

from langfuse import observe, Langfuse, get_client

# Initialize the client with sampling
Langfuse(sample_rate=0.3)  # 30% of traces will be sampled

@observe()
def process_data():
    # Only ~30% of calls to this function will generate traces
    # The decision is made at the trace level (first span)
    pass

如果一个 trace 未被采样,它的任何 observations(spans 或 generations)或关联的 scores 都不会发送到 Langfuse,这可以显著减少高流量应用的数据量。

Langfuse 遵循 OpenTelemetry 的采样决策。你可以在 OTEL SDK 中配置采样器,以控制哪些 traces 发送到 Langfuse。这对于在高流量应用中管理成本和减少噪声很有用。

下面是如何配置 TraceIdRatioBasedSampler 以仅发送 20% traces 的示例:

tsinstrumentation.ts

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

const sdk = new NodeSDK({
  // Sample 20% of all traces
  sampler: new TraceIdRatioBasedSampler(0.2),
  spanProcessors: [new LangfuseSpanProcessor()],
});

更多细节参见 JS/TS SDK 文档。

下面是如何配置 TraceIdRatioBasedSampler 以仅发送 20% traces 的示例:

tsinstrumentation.ts

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

const sdk = new NodeSDK({
  // Sample 20% of all traces
  sampler: new TraceIdRatioBasedSampler(0.2),
  spanProcessors: [new LangfuseSpanProcessor()],
});

照常初始化 OpenAI 集成:

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

const openai = observeOpenAI(new OpenAI());

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

Langfuse 对 Langchain(JS/TS)同样遵循 OpenTelemetry 的采样决策。先在 OTEL SDK 中配置采样,然后初始化回调 handler。

tsinstrumentation.ts

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

const sdk = new NodeSDK({
  // Sample 20% of all traces
  sampler: new TraceIdRatioBasedSampler(0.2),
  spanProcessors: [new LangfuseSpanProcessor()],
});

设置好追踪和采样后,照常初始化 Langchain 回调 handler:

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

const handler = new CallbackHandler();

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

使用 Vercel AI SDK 集成时:

tsinstrumentation.ts

import { registerOTel } from "@vercel/otel";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

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