Langfuse 트레이싱

Langfuse 트레이싱 (Langfuse)

Langfuse UI로 Haystack 파이프라인을 트레이스하는 방법을 알아볼게요.

출처: Langfuse (공식 문서)

개요 (Overview)

Langfuse UI로 Haystack 파이프라인을 트레이스해요. Langfuse는 파이프라인 실행에 대한 상세 정보 — API 호출, 컨텍스트 데이터, 프롬프트 등 — 를 포착합니다. 토큰 사용량과 비용 같은 모델 성능을 모니터링하고, 개선할 부분을 찾고, 파이프라인 실행에서 데이터셋을 만드는 데 쓸 수 있어요.

설치 (Installation)

langfuse-haystack 패키지를 설치하세요.

pip install langfuse-haystack

사전 요구사항 (Prerequisites)

1. 활성화된 Langfuse 계정.
2. 계정 프로필에서 확인할 수 있는 LANGFUSE_SECRET_KEY와 LANGFUSE_PUBLIC_KEY 환경 변수를 설정하세요.
3. HAYSTACK_CONTENT_TRACING_ENABLED 환경 변수를 true로 설정해 트레이싱을 켜세요.

Usage Notice

제대로 트레이싱하려면 Haystack 컴포넌트를 import하기 전에 항상 환경 변수를 설정하세요. Haystack이 import 중에 내부 트레이싱 컴포넌트를 초기화하기 때문에 이건 아주 중요해요. 더 좋은 방법은 스크립트를 실행하기 전에 셸에서 환경 변수를 설정하는 것입니다.

사용법 (Usage)

파이프라인에 컴포넌트를 추가하지 않고도 LangfuseTracer를 직접 켜서 어떤 Haystack 파이프라인이든 트레이스할 수 있어요.

import os

os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"
os.environ["LANGFUSE_SECRET_KEY"] = "<your-secret-key>"
os.environ["LANGFUSE_PUBLIC_KEY"] = "<your-public-key>"
os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"

from langfuse import Langfuse
from haystack import Pipeline, tracing
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack_integrations.tracing.langfuse import LangfuseTracer

# Enable the Langfuse tracer. The client reads your keys from the environment.
langfuse = Langfuse()
langfuse_tracer = LangfuseTracer(langfuse, name="Chat example")
tracing.enable_tracing(langfuse_tracer)

pipe = Pipeline()
pipe.add_component("prompt_builder", ChatPromptBuilder())
pipe.add_component("llm", OpenAIChatGenerator())
pipe.connect("prompt_builder.prompt", "llm.messages")

messages = [
    ChatMessage.from_system(
        "Always respond in German even if some input data is in other languages.",
    ),
    ChatMessage.from_user("Tell me about {{location}}"),
]

response = pipe.run(
    data={
        "prompt_builder": {
            "template_variables": {"location": "Berlin"},
            "template": messages,
        },
    },
)

print(response["llm"]["replies"][0])

# Flush any pending spans before the program exits
langfuse_tracer.flush()

여기서 LangfuseTracer에 name="Chat example"처럼 이름을 주는 것과, 프로그램 종료 전에 flush()로 대기 중인 span을 비우는 것이 포인트예요.

각 파이프라인 실행은 전체 실행 컨텍스트(프롬프트, 완성(completions), 메타데이터 포함)를 담은 트레이스 하나를 만들고, 그 트레이스를 Langfuse UI에서 볼 수 있어요.

대안: LangfuseConnector 컴포넌트

트레이싱을 파이프라인 정의의 일부로 관리하고 싶다면, LangfuseConnector 컴포넌트를 추가하는 방법도 있어요. 동일한 Langfuse 트레이싱을 켜고, trace_url을 출력으로 노출하며, 고급 span 처리를 위한 커스텀 SpanHandler를 지원합니다.

info

전체 사용 예시와 고급 span 커스터마이징은 LangfuseConnector 문서 페이지를, 완전한 워크스루는 블로그 포스트를 참고하세요.

더 알아보기 (Learn more)

• Langfuse - 공식 문서
• LangfuseConnector
• Tracing