Langfuse 추적

이 문서는 LibreChat과 Langfuse 추적을 통합하여 AI 대화에 대한 전체적인 관측 가능성을 확보하는 방법을 설명합니다.

Langfuse는 LLM 애플리케이션을 추적, 모니터링 및 디버깅하는 데 도움을 주는 오픈 소스 LLM 관측성 플랫폼입니다. Langfuse를 LibreChat과 통합하면 AI 대화에 대한 전체적인 가시성을 확보할 수 있습니다.

필수 조건

시작하기 전에 다음 사항을 준비했는지 확인하세요:

실행 중인 LibreChat 인스턴스 ( 빠른 시작 참조)
Langfuse 계정 (무료 가입)
프로젝트 설정에서 가져온 Langfuse API 키

설정

LibreChat 설치 디렉토리의 .env 파일에 다음 Langfuse 관련 환경 변수를 추가하세요:

Key	Type	Description	Example
LANGFUSE_PUBLIC_KEY	string	Langfuse 공개 키.	LANGFUSE_PUBLIC_KEY=pk-lf-***
LANGFUSE_SECRET_KEY	string	Langfuse 비밀 키입니다.	LANGFUSE_SECRET_KEY=sk-lf-***
LANGFUSE_BASE_URL	string	Langfuse API 기본 URL.	LANGFUSE_BASE_URL=https://cloud.langfuse.com

설정 예시

# Langfuse Configuration
LANGFUSE_PUBLIC_KEY=pk-lf-***
LANGFUSE_SECRET_KEY=sk-lf-***

# 🇪🇺 EU Data Region
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# 🇺🇸 US Data Region
# LANGFUSE_BASE_URL=https://us.cloud.langfuse.com

자체 호스팅 Langfuse

자체 호스팅된 Langfuse 인스턴스의 경우, LANGFUSE_BASE_URL을 사용자 지정 URL(예: 로컬 개발 환경의 경우 http://localhost:3000)로 설정하세요.

LibreChat 재시작

환경 변수를 추가한 후, 변경 사항을 적용하려면 LibreChat 인스턴스를 재시작하세요:

docker compose down
docker compose up -d

Langfuse에서 추적(Traces) 확인하기

Langfuse가 구성된 상태로 LibreChat을 다시 시작하면, Langfuse UI에서 모든 채팅 메시지 응답에 대한 새로운 추적(trace)을 확인할 수 있습니다:

LibreChat 예시 추적

Langfuse UI에서 추적 링크 보기

Langfuse 추적(tracing)이 구성되면, LibreChat은 메시지 피드백을 일치하는 추적에 대한 user-feedback BOOLEAN 점수로 Langfuse에 전송합니다. 좋아요(thumbs-up) 평가는 1로, 싫어요(thumbs-down) 평가는 0으로 전송되며, 선택된 피드백 태그나 댓글은 점수에 포함됩니다. 피드백을 삭제하면 해당 점수도 삭제됩니다.

피드백 점수에는 사용 가능한 경우 메시지 ID, 부모 메시지 ID, 대화/세션 ID, 사용자 ID, endpoint, 발신자, isCreatedByUser, 토큰 수, 평점 및 피드백 태그를 포함한 메시지 컨텍스트 메타데이터가 포함됩니다. 점수가 전송되기 전에 비어 있는 메타데이터 값은 생략됩니다.

피드백 점수는 추적(tracing)과 동일한 Langfuse 자격 증명 및 기본 URL을 사용합니다. 또한 LANGFUSE_TRACING_ENABLED=false, LANGFUSE_SAMPLE_RATE=0, LANGFUSE_TRACING_ENVIRONMENT 설정을 따릅니다. 점수 전송은 최선형(best-effort) 방식으로 이루어지므로, Langfuse를 일시적으로 사용할 수 없는 경우에도 피드백 UI가 차단되지 않습니다.