Spaces에서 Langfuse 사용하기

Spaces에서 Langfuse 사용하기

이 가이드는 Hugging Face Spaces에 Langfuse를 배포하고 LLM 애플리케이션을 관측 가능성(observability)을 위해 계측하는 방법을 보여줘요. 이 통합으로 Hugging Face Hub에서 LLM API를 실험하고, 프롬프트를 한 곳에서 관리하고, 모델 출력을 평가할 수 있어요.

출처: 문서

본문

Langfuse란?

Langfuse는 팀이 LLM 애플리케이션을 협업적으로 디버깅·평가·반복할 수 있게 돕는 오픈소스 LLM 엔지니어링 플랫폼이에요.

Langfuse의 핵심 기능에는 애플리케이션 실행 흐름의 전체 맥락을 포착하는 LLM 트레이싱, 중앙화·협업적 프롬프트 반복을 위한 프롬프트 관리, 출력 품질 평가 지표, 테스트·벤치마킹용 데이터셋 생성, 프롬프트와 모델 구성을 실험하는 플레이그라운드가 있어요.

왜 LLM 관측 가능성인가?

  • 언어 모델이 보편화되면서 그 동작과 성능을 이해하는 것이 중요해졌어요.
  • LLM 관측 가능성은 출력을 통해 LLM 애플리케이션의 내부 상태를 모니터링하고 이해하는 것을 포함해요.
  • 다음 같은 문제를 해결하는 데 필수적이에요:
    • 반복·연쇄 호출이 있는 복잡한 제어 흐름으로 디버깅이 어려움.
    • 비결정적 출력이 일관된 품질 평가를 어렵게 함.
    • 다양한 사용자 의도가 사용자 경험 향상을 위한 깊은 이해를 요구함.
  • LLM 애플리케이션 구축은 복잡한 워크플로를 수반하며, 관측 가능성이 이 복잡성을 관리하는 데 도와줘요.

1단계: Spaces에서 Langfuse 설정하기

Langfuse Hugging Face Space는 몇 번의 클릭만으로 배포된 Langfuse 버전을 바로 실행할 수 있게 해줘요.

시작하려면 위 버튼을 클릭하거나 다음 단계를 따르세요:

  1. 새 Hugging Face Space를 만든다
  2. Space SDK로 Docker를 선택한다
  3. Space 템플릿으로 Langfuse를 선택한다
  4. 재시작 후에도 Langfuse 데이터가 유지되도록 **Storage Bucket**을 연결한다
  5. Langfuse API/SDK가 앱에 접근할 수 있게 Space를 public으로 설정한다(자세한 내용은 아래 참고)
  6. [선택 사항이지만 권장] 안전한 배포를 위해 환경 변수의 기본값을 바꾼다:
    • NEXTAUTH_SECRET: 로그인 세션 쿠키 검증에 사용. openssl rand -base64 32로 256 이상 엔트로피의 시크릿 생성.
    • SALT: 해시된 API 키에 솔트로 사용. openssl rand -base64 32로 256 이상 엔트로피의 시크릿 생성.
    • ENCRYPTION_KEY: 민감한 데이터 암호화에 사용. 256비트, hex 형식 64문자여야 함. openssl rand -hex 32로 생성.
  7. Create Space를 클릭한다!

사용자 접근

Langfuse Space는 안전한 인증을 위해 Hugging Face OAuth로 사전 구성돼 있어요. 첫 로그인 시 팝업 지침에 따라 Hugging Face 계정에 read 접근을 승인해야 해요.

앱 안에서는 기본 Langfuse 기능으로 Organizations, Projects, Users를 관리할 수 있어요.

Langfuse Space는 Langfuse API/SDK가 앱에 닿도록 반드시 public이어야 해요. 즉 기본적으로 모든 로그인한 Hugging Face 사용자가 Langfuse Space에 접근할 수 있어요.

두 가지 방법으로 새 사용자의 가입·접근을 막을 수 있어요:

1. (권장) Hugging Face 네이티브 조직 수준 OAuth 제한

특정 조직의 멤버로만 접근을 제한하려면 Space의 README.md에 hf_oauth_authorized_org 메타데이터 필드를 설정하면 돼요(여기 참고).

구성하면 지정된 조직의 멤버인 사용자만 Space에 접근할 수 있어요.

2. 수동 접근 제어

AUTH_DISABLE_SIGNUP 환경 변수를 true로 설정해 사용자별로 접근을 제한할 수도 있어요. 이 변수를 설정하기 전에 먼저 Space에 로그인·인증했는지 확인하세요. 아니면 자신의 사용자 프로필도 인증할 수 없게 돼요.

[!TIP] AUTH_DISABLE_SIGNUP 환경 변수를 true로 설정해 접근을 제한했고 새 사용자에게 접근을 허용하려면, 먼저 false로 되돌리고(재빌드 완료 대기), 사용자를 추가하고 OAuth로 인증하게 한 다음, 다시 true로 설정해야 해요.

2단계: Langfuse 사용하기

Langfuse가 실행되고 있으니 LLM 애플리케이션을 계측해 트레이스를 포착하고 프롬프트를 관리할 수 있어요.

모든 애플리케이션 모니터링

Langfuse는 모델에 구애받지 않으며 어떤 애플리케이션이든 트레이스할 수 있어요. Langfuse 문서의 get-started 가이드를 따라 코드를 계측하는 방법을 보세요.

Langfuse는 Langchain, LlamaIndex, OpenAI 등 인기 LLM 프레임워크와 네이티브 통합을 유지하며, 코드 계측용 Python·JS/TS SDK를 제공해요. Langfuse는 데이터 수집용 다양한 API 엔드포인트도 제공하며, Langflow, Dify, Haystack 같은 다른 오픈소스 프로젝트에도 통합되었어요.

예제 1: 추론 프로바이더 호출 트레이스

간단한 예로, Langfuse Python SDK로 Inference Providers에 대한 LLM 호출을 트레이스하는 방법이에요.

먼저 LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY 환경 변수를 구성하고 Hugging Face 계정으로 인증했는지 확인하세요.

from langfuse.openai import openai
from huggingface_hub import get_token

client = openai.OpenAI(
    base_url="https://router.huggingface.co/hf-inference/models/meta-llama/Llama-3.3-70B-Instruct/v1",
    api_key=get_token(),
)

messages = [{"role": "user", "content": "What is observability for LLMs?"}]

response = client.chat.completions.create(
    model="meta-llama/Llama-3.3-70B-Instruct",
    messages=messages,
    max_tokens=100,
)

예제 2: Gradio 애플리케이션 모니터링

Hugging Face 모델로 간단한 채팅 애플리케이션을 만들고 Langfuse에서 모델 호출과 사용자 피드백을 트레이스하는 방법을 보여주는 Gradio 템플릿 Space를 만들었어요 — Hugging Face를 떠나지 않고요.

시작하려면 이 Gradio 템플릿 Space를 복제하고 README의 지침을 따르세요.

3단계: Langfuse에서 트레이스 보기

애플리케이션을 계측하고 트레이스나 사용자 피드백을 Langfuse에 수집했다면, Langfuse에서 트레이스를 볼 수 있어요.

더 알아보기 (Learn more)