서론 (Introduction)

Chapter 2 (Evals)에서 우리는 답변의 _품질 (quality)_을 측정했습니다. 이제 Observability (관측 가능성)를 추가하여 동작을 _가시화 (visible)_하겠습니다.

[Evals]
점수를 통해 답변의 정확도를 측정 → 품질 측정 (quality measurement)

...

우리는 오픈 소스 Observability (관측 가능성) 도구인 Langfuse v4를 사용할 것입니다. 이 도구는 무료 클라우드 티어를 제공하며 셀프 호스팅 (self-hosted)도 가능합니다.

참고: Langfuse v4 (2026년 3월 기준)는 API가 크게 변경되었습니다.
langfuse_context, update_current_observation, 그리고 update_current_trace는 더 이상 사용되지 않습니다 (deprecated).
이 튜토리얼은 v4.9+ 버전과 호환됩니다.

Langfuse가 할 수 있는 일

기능	설명
Tracing (트레이싱)	각 RAG/Agent 단계의 실행 시간 및 I/O 기록
...

디렉토리 구조 (Directory Structure)

pgvector-tutorial/
├── existing files
├── evals/
...

1단계: Langfuse 설정 (Step 1: Langfuse Setup)

1-1. 라이브러리 설치 (Install the Library)

pip install langfuse
pip freeze > requirements.txt

1-2. Langfuse 계정 생성 (Create a Langfuse Account)

1. cloud.langfuse.com에 접속합니다.
2. GitHub으로 가입합니다 (무료, 신용카드 불필요).
3. 새 프로젝트를 생성합니다.
4. "Settings" → "API Keys" 메뉴에서 다음을 가져옵니다:
   • LANGFUSE_PUBLIC_KEY (pk-lf-...로 시작)
   • LANGFUSE_SECRET_KEY (sk-lf-...로 시작)

1-3. .env에 추가 (Add to .env)

# 기존 설정
GEMINI_API_KEY=AIza...
DB_HOST=localhost
...

⚠️ 중요: load_dotenv()를 호출하기 전에 get_client()를 호출하지 마세요.
Langfuse는 초기화 시 환경 변수를 읽습니다. 항상 load_dotenv()를 호출한 이후에 get_client()를 호출하십시오.

2단계: 트레이싱이 포함된 RAG — observability/traced_rag.py (Step 2: RAG with Tracing)

트레이스 (traces)를 자동으로 기록하려면 단순히 @observe() 데코레이터 (decorator)를 추가하면 됩니다.

# observability/traced_rag.py
import sys
import os
...

mkdir observability
python observability/traced_rag.py

3단계: 트레이싱이 포함된 Agent — observability/traced_agent.py (Step 3: Agent with Tracing)

⚠️ 주의해야 할 두 가지 사항 (Two common gotchas):

1. load_dotenv() 호출 이후에 get_client()를 호출하세요.
2. agent_step()에서 candidates를 반환하세요 (run_agent()에서 참조됨).

# observability/traced_agent.py
import sys
import os
...

python observability/traced_agent.py

Step 4: 대시보드에서 확인할 수 있는 것

실행 후, cloud.langfuse.com을 열어 다음을 확인하세요:

Agent Trace (실제 표시 화면):

Name	Latency
agent_pipeline	4.40s
...

Langfuse v4 마이그레이션 치트 시트 (v3에서 전환)

v3 (이전)	v4 (신규)
from langfuse.decorators import observe, langfuse_context	from langfuse import get_client, observe
...

일반적인 오류 (Common Errors)

Error	원인 (Cause)	해결 방법 (Fix)
Authentication error: initialized without public_key	get_client()가 load_dotenv() 이전에 호출됨	load_dotenv() 호출 이후에 get_client()를 호출하세요
...

다음 단계 (Next Steps)

• [Chapter 4: Security] — 프롬프트 인젝션 (Prompt injection) 방어 및 가드레일 (guardrail) 설계
• Evals와 통합 — Langfuse의 Scoring API를 통해 트레이스 (traces)에 평가 (Eval) 점수 부착
• 지속적인 모니터링 — 프로덕션 알림 (production alerts) 설정