Langfuse 소개 및 설치

0. Langfuse 란?

오늘은 대규모 언어 모델(LLM)을 활용한 애플리케이션 개발과 운영의 복잡성을 해결해 줄 강력한 오픈소스 도구, Langfuse에 대해 알아보려 한다.
LLM을 프로덕션 환경에서 운영하다 보면 예측 불가능한 결과, 디버깅의 어려움, 숨겨진 비용, 성능 저하 등 다양한 문제에 직면하게 된다.

복잡하게 얽힌 체인(Chain), 에이전트(Agent), RAG(Retrieval-Augmented Generation) 파이프라인의 내부 동작을 어떻게 투명하게 들여다볼 수 있을까? 프롬프트 하나를 바꿨을 때 전체 시스템에 어떤 영향을 미치는지 어떻게 체계적으로 측정할 수 있을까? 수많은 사용자로부터 들어오는 피드백을 어떻게 효율적으로 수집하고 제품 개선에 반영할 수 있을까? Langfuse는 바로 이 모든 질문에 대한 현실적인 답을 제공하는 통합 엔지니어링 플랫폼이다.

우선 Langfuse는 "오픈소스 LLM 엔지니어링 플랫폼(Open source LLM engineering platform)"이다.
단순히 로그를 기록하거나 성능을 모니터링하는 도구를 넘어, 개발, 모니터링, 평가, 디버깅 등 LLM 애플리케이션의 전체 생명주기(Lifecycle)를 지원하기 위해 설계되었다.

 

사실 Langfuse 자체는 2023에 release 되어서 발전해 온 오래된 오픈소스인데 이제 와서 옮기게 된 이유는
기존에 간단한 토이 프로젝트들은 Langsmith를 사용해왔는데 회사 프로젝트 등을 하면서
우리의 데이터가 Langsmith로 넘어가는 것이 보안 문제가 있을 수도 있기 때문에 사내서버에 Langfuse를 구축하여 쓰고 싶기도 했고, 가장 중요한 점은 바로 원래는 Lanfuse가 클라우드 설치형이 아닌 셀프 호스팅으로 사용할경우 일부 기능이 제한되었었는데 2025.06부터 모든 기능이 오픈소스로 풀렸다.
그래서 Langsmith와 거의 동일한 기능을 모두 사용할 수 있게 되었다. --> 관련 발표

그래서 오늘은 Langsmith와의 차이점, Docker를 이용한 self-hosting 방법, 그리고 간단한 사용법까지 알아보려 한다.

 

GitHub - langfuse/langfuse: 🪢 Open source LLM engineering platform: LLM Observability, metrics, evals, prompt management, pla

1. Feature

Langfuse는 다음과 같은 기능이 있다.

Tracing

Langfuse의 가장 기본적이면서도 강력한 기능으로, LLM 호출, RAG, 임베딩 생성, 에이전트의 도구 사용 등 애플리케이션 내부에서 일어나는 모든 논리적 흐름을 'Trace'라는 단위로 기록하고 시각화한다.

중첩된(nested) 계층 구조를 지원하기 때문에, 여러 단계로 구성된 복잡한 에이전트 워크플로우나 병렬 처리 로직도 명확하게 파악할 수 있으며, 각 Trace는 비용, 지연 시간(latency), 사용자, 세션, 모델, 프롬프트 버전별로 세분화하여 분석이 가능하므로, 성능 병목 현상이나 예상치 못한 비용 문제를 정확히 찾아낼 수 있다

Prompt Management

프롬프트를 중앙에서 관리하고, 버전을 제어하며, 팀원들과 협업하여 개선할 수 있는 체계적인 환경을 제공하며, Playground라는 탭에서는 다양한 모델과 하이퍼파라미터를 바꿔가며 프롬프트를 즉시 테스트할 수 있다.

Evaluations & Metrics

사용자가 직접 남기는 피드백 수집(SDK/API 활용), LLM을 평가자로 활용하는 LLM-as-a-judge 자동 평가, UI를 통한 운영자의 수동 데이터 라벨링, 그리고 기업의 특정 요구사항에 맞춘 커스텀 평가 파이프라인 연동 등 다양한 평가기능을 제공한다.

1-1. Langsmith와의 차이점

Langsmith는 Langchain 생태계에 있는 프레임워크 중 하나로 위에서 설명한 Langfuse의 모든 기능을 제공하며 더욱 편리하게 사용할 수 있는 것은 사실이다.
다만 Langsmith는 다른 여러 프레임워크들과도 통합을 지원하지만 Langchain과의 연계에 중점을 두고있으며 제일 중요한 것이 온프레미스, 로컬 구축이 아니라 클라우드에 저장된다는 것이다. 이러한 LLM 실험 및 중요한 데이터들이 클라우드에 저장되는 것은 보안상 위험이 있기 때문에 비교적 기능이 단순하고, 설정이 조금 복잡해도 Langfuse처럼 로컬에 구축할 수 있는 시스템이 편한 것 같다.
또한 Langfuse도 계속해서 다양한 프레임워크들과 integrate을 진행하고 있고 Langsmith의 기능들을 참고하여 거의 유사한 기능들을 제공한다.

2. Install

Langfuse는 클라우드 버전과 셀프호스팅 모두 제공한다.
셀프호스팅에도 다양한 방법이 존재하는데(Docker, Kubernetes, AWS, Azure, GCP 등) 이번 글에서는 Docker을 이용한 셀프 호스팅에 대해서 알아볼 것이다.

공식가이드

0. Requirements

우선 로컬 개발 환경에 git, docker, 그리고 docker-compose가 설치되어 있어야 한다.

1. Clone repository

다음 명령어를 실행하여 Langfuse의 공식 GitHub 리포지토리를 로컬 환경으로 복제한다.

git clone https://github.com/langfuse/langfuse.git
cd langfuse

2. Docker compose

docker compose up -d

위와 같이 간단하게 호스팅을 할 수 있으며, 정상적으로 컨테이너들이 올라갔다면 http://localhost:3000 에 접속하여 Langfuse 대시보드에 접속이 가능하다.

3. Usage

우선 실제로 사용하기 위해서는 langfuse 대쉬보드에 접속해서 프로젝트를 생성해 보면 친절하게 가이드가 나오는데,
우선 자신이 추적하고자 하는 프로젝트의 .env 에 다음과 같은 설정들을 해줘야 한다.

LANGFUSE_TRACING_ENABLED=true
LANGFUSE_SECRET_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
LANGFUSE_PUBLIC_KEY=pk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
LANGFUSE_HOST=http://{서버ip}:3000

 

secret key와 public key는 자신이 대시보드에서 프로젝트를 생성할 때 발급받을 수 있으며, Host는 자신의 셀프 호스팅한 서버를 적어주면 된다.
또한 추적을 껐다 켰다 할 수도 있다.

너무나도 다양한 기능들이 있기 때문에 초반에는 docs를 참고하며 여러 기능들을 시험해 보는 것을 추천한다.
또한 다양한 프레임워크들과 Integrate 되어있기 때문에 상황에 맞게 사용하면 된다.

일반적으로 대부분의 llm 호출들이 OpenAI API 형식을 지원하기 때문에
대부분 LLM 호출 시에 from openai import OpenAI 를사용하여 클라이언트를 생성하고 baseurl이나 api_key등만 바꿔서 사용할 것이라고 생각한다.(vllm이든 ollama도 마찬가지)

langfuse는 OpenAI와도 integrate 되어있어서 아주 간단하게 tracing을 지원한다

그냥 아래와 같이 import 문만 바꿔주면 된다.

#from openai import OpenAI
from langfuse.openai import OpenAI

 

위와 같이 바꿔주면 해당 호출들이 tracing 되기 시작하고 이것보다 더욱 자세한 추적기능들은 docs를 참고하길 바란다.

 

openai 호출방식 말고도 @observe 데코레이터나 context manager 등으로 다양한 nested형식의 tracing을 커스텀할 수 있으니 

프로젝트에 잘 세팅하면 이후 실험 추적 및 관리에 용이하다

4. Issue

사실상 로컬에서 호스팅 할 때는 위와 같이 clone을 해서 컨테이너만 올려도 아무 문제 없이 사용가능하다.
다만 나의 경우에는 서버에 컨테이너를 올리고 로컬에서 접속해서 사용하는 입장이었다. 사실 이것도 다른 오픈소스들 같은 경우에는 아무 문제없이 사용가능했고,
Langfuse도 정상적으로 사용이 되나 싶었는데 langfuse에 미디어파일(멀티모달)을 올릴 때 문제가 발생했다.

추가설정 없이 컨테이너를 올리면 이미지 등을 langfuse에 올렸을 때 tracing이 안될 것이다. (공식 Langfuse 가이드에도 나와있음)

 

이를 해결하기 위해서는 docker-compose.yaml에서 한 가지 설정을 바꿔줘야 했다.
가이드에 나와있는 대로 blob storage guide를 참고하여,

docker-compose.yaml에서 LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT 부분을 찾아서 자신의 서버 ip로 변경해줘야 한다.

#LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: ${LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT:-http://localhost:9090}
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: ${LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT:-http://서버IP:9090}

나는 당연히 해당 컨테이너 자체를 서버에서 띄운거기 때문에 상관없을 줄 알았는데,
미디어파일의 경우 미디어 파일을 업로드하는 주체가 저 환경변수에 적혀있는 IP를 받아와서 해당 minio에 미디어 파일을 올리는 방식이기 때문에 저기를 외부에서 접속가능한 서버 ip로 변경해 줘야만 제대로 이미지를 Langfuse에서 볼 수 있다. 관련 이슈 , 관련이슈2

(다만 로컬에서 호스팅 하여 사용한 다음 미디어 파일을 올릴 경우 Langfuse에서 바로 이미지가 랜더링 되어서 깔끔하게 보이는데, 이렇게 서버에서 호스팅 해서 사용할 경우에는
이미지가 랜더링 되지 않고 링크가 나오게 되고 해당 링크를 클릭해야 이미지를 볼 수 있다. 이것은 보안정책 때문이라고 한다. -->관련이슈)