LLM 애플리케이션을 운영에 올리고 나면 꼭 받는 질문이 비슷하다. 이번 달 토큰값이 왜 이렇게 나왔냐, 저 요청은 왜 8초나 걸렸냐, 프롬프트 바꾸고 나서 품질이 좋아진 건 맞냐. 로그를 grep으로 뒤지다 보면 이게 사람 할 짓이 아니라는 생각이 든다. Langfuse를 직접 올려두면 이 질문들에 대시보드로 답할 수 있다.
결론부터 말하자면, Langfuse v3는 Docker Compose 하나로 ClickHouse, Postgres, Redis, MinIO까지 같이 띄워 셀프호스팅한다. 애플리케이션 코드에는 OpenTelemetry로 트레이스를 쏘면 되고, 토큰과 비용, 지연은 자동으로 집계된다. 데이터가 외부로 나가지 않으니 사내 데이터 규정이 빡빡한 곳에서도 쓴다.
1. v3가 ClickHouse를 끌고 온 이유
Langfuse v2까지는 Postgres 한 통에 다 넣었다. 트레이스가 수백만 건 쌓이면서 집계 쿼리가 느려지는 문제가 생겼고, v3부터 저장소를 둘로 쪼갰다. 설정이나 사용자, 프로젝트 같은 트랜잭션 데이터는 Postgres에 남기고, 트레이스와 관측 이벤트처럼 대량으로 쌓이고 집계가 많은 데이터는 ClickHouse라는 컬럼 지향 분석 DB로 옮겼다.
여기에 비동기 적재를 위한 Redis 큐, 트레이스에 딸린 입출력 페이로드와 미디어를 담는 S3 호환 저장소가 붙는다. 셀프호스팅에서는 이 S3 자리에 MinIO를 띄워 쓴다. 그래서 컨테이너가 여러 개로 늘어난 것이고, 겉보기엔 복잡해도 Compose 파일에 다 들어 있다.
OpenTelemetry는 애플리케이션에서 트레이스와 메트릭을 수집해 표준 형식으로 내보내는 관측 프레임워크다. Langfuse v3는 OTLP(OpenTelemetry Protocol) 수신 엔드포인트를 열어두기 때문에, LangChain이나 OpenAI SDK용 계측 라이브러리가 뱉는 트레이스를 그대로 받는다. 특정 SDK에 종속되지 않는다는 뜻이다.
2. Compose로 올리기
저장소를 받아서 바로 띄운다. 로컬이나 내부망 테스트라면 이 정도로 끝난다.
git clone https://github.com/langfuse/langfuse.git cd langfuse docker compose up -d
처음 올리면 ClickHouse 마이그레이션이 돌아가느라 langfuse-web 컨테이너가 몇 번 재시작할 수 있다. 정상이다. docker compose ps로 상태를 보면 어떤 서비스가 뜨는지 한눈에 들어온다.
$ docker compose ps NAME SERVICE STATUS PORTS langfuse-web-1 langfuse-web running 0.0.0.0:3000->3000/tcp langfuse-worker-1 langfuse-worker running 127.0.0.1:3030->3030/tcp langfuse-postgres-1 postgres running (healthy) langfuse-clickhouse-1 clickhouse running (healthy) langfuse-redis-1 redis running (healthy) langfuse-minio-1 minio running (healthy) 0.0.0.0:9090->9000/tcp
웹 UI는 3000번 포트, 워커는 3030(localhost 전용), MinIO는 9090으로 나온다. 데이터베이스들은 외부로 노출하지 않는다.
개발용으로 한번 돌려보는 거라면 넘어가도 되지만, 어디든 노출되는 환경이라면 Compose 파일 안의 기본 시크릿을 반드시 갈아야 한다. 기본값에는 # CHANGEME 주석이 붙어 있으니 먼저 위치부터 확인한다.
grep -n CHANGEME docker-compose.yml
최소한 바꿔야 하는 값은 세 종류다. NEXTAUTH_SECRET은 로그인 세션 쿠키 검증에, SALT은 API 키 해시에 쓰이고, 둘 다 256비트 이상 엔트로피를 요구한다. ENCRYPTION_KEY는 저장되는 민감 데이터 암호화에 쓰이며 반드시 64자리 16진수여야 한다. 포맷을 틀리면 워커가 부팅하다 죽는다.
$ openssl rand -base64 32 # NEXTAUTH_SECRET, SALT 용 PzVq8s2... (생략) $ openssl rand -hex 32 # ENCRYPTION_KEY 용 (64자 hex) 3f8a1c7b9e2d4a6f0b5c8e1d7a3f9c2e6b4d8a0f1c5e9b3d7a2f4c6e8b0d2f4a
여기에 더해 POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH, MinIO의 루트 비밀번호도 같이 바꾼다. 이 값들은 Compose 파일 안에서 각 DB 컨테이너와 langfuse-web, langfuse-worker 양쪽에 함께 들어가므로, 한쪽만 고치면 연결이 안 된다. 다 고쳤으면 docker compose up -d로 다시 올린다.
3. 로그인과 API 키
Langfuse에는 기본 관리자 계정이 없다. 브라우저로 http://서버주소:3000에 들어가면 가입 화면이 나오고, 첫 번째로 가입하는 사용자가 그대로 첫 조직의 주인이 된다. 외부에 열린 서버라면 가입 후 환경변수 AUTH_DISABLE_SIGNUP=true로 추가 가입을 막아둔다.
로그인하면 조직과 프로젝트를 만들고, 프로젝트 설정의 API Keys에서 공개 키(pk-lf-...)와 비밀 키(sk-lf-...)를 발급한다. 이 둘이 트레이스를 쏠 때 인증에 쓰인다.
4. OpenTelemetry로 트레이스 쏘기
Langfuse v3는 v3.22.0부터 로컬 OTLP 엔드포인트 http://localhost:3000/api/public/otel을 받는다. 인증은 공개 키와 비밀 키를 콜론으로 이어 base64로 인코딩한 베이직 인증을 쓴다. 먼저 인증 문자열을 만든다.
$ echo -n "pk-lf-1234567890:sk-lf-abcdef" | base64 -w 0 cGstbGYtMTIzNDU2Nzg5MDpzay1sZi1hYmNkZWY=
키가 길어 줄바꿈이 끼면 인증이 깨지므로 GNU 환경에서는 -w 0을 붙인다. 이렇게 나온 값을 OTEL 환경변수에 넣는다.
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3000/api/public/otel" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic cGstbGYtMTIzNDU2Nzg5MDpzay1sZi1hYmNkZWY="
이제 애플리케이션에서 OpenTelemetry 계측 라이브러리를 켜면 LLM 호출마다 트레이스가 올라간다. 파이썬에서 OpenAI SDK를 OpenLLMetry로 계측한 예다.
pip install traceloop-sdk openai
from traceloop.sdk import Traceloop
from openai import OpenAI
Traceloop.init(app_name="my-llm-app")
client = OpenAI()
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "안녕"}],
)
print(resp.choices[0].message.content)
한 번 호출하고 UI의 Tracing 화면으로 가면 방금 요청이 뜬다. 입력과 출력 메시지, 모델명, 입출력 토큰 수, 지연 시간이 한 줄에 다 찍힌다. 비용은 모델별 단가 표를 Langfuse가 들고 있어 토큰 수에서 자동 계산한다. 자체 파인튜닝 모델처럼 단가가 없는 경우는 프로젝트 설정의 Models에서 직접 등록한다.
처음 쏠 때 트레이스가 바로 안 보여도 당황할 필요 없다. v3는 Redis 큐를 거쳐 ClickHouse로 비동기 적재하기 때문에 몇 초 지연이 생긴다. 1분 넘게 안 보이면 워커 로그부터 본다.
docker compose logs -f langfuse-worker
5. 프롬프트를 버전으로 관리하기
프롬프트를 코드에 하드코딩해두면 문구 하나 고칠 때마다 배포를 다시 해야 한다. Langfuse의 Prompt Management는 프롬프트를 서버에 두고 버전으로 관리한다. UI의 Prompts에서 프롬프트를 만들면 저장할 때마다 버전 번호가 올라가고, production이나 latest 같은 라벨을 특정 버전에 붙인다.
애플리케이션은 SDK로 라벨을 지정해 프롬프트를 당겨 쓴다. 운영에서 쓰는 버전을 바꾸고 싶으면 코드 배포 없이 production 라벨만 다른 버전으로 옮기면 된다.
from langfuse import Langfuse
langfuse = Langfuse()
prompt = langfuse.get_prompt("support-reply", label="production")
compiled = prompt.compile(question="환불 되나요")
프롬프트를 당겨 쓴 호출은 트레이스에 어느 프롬프트 몇 번 버전을 썼는지 같이 기록된다. 그래서 버전을 바꾼 뒤 지연이나 토큰이 어떻게 달라졌는지 버전별로 비교할 수 있다.
6. LLM-as-judge로 품질 점수 매기기
토큰과 지연은 숫자라 저절로 모이지만, 응답 품질은 누가 채점해줘야 한다. Langfuse의 Evaluations는 LLM을 심판으로 세워 트레이스마다 점수를 매기는 LLM-as-judge 방식을 지원한다. 올라오는 트레이스의 입력과 출력을 심판 모델에게 보내 환각 여부나 유용성 같은 기준으로 평가하게 한다.
셀프호스팅에서 먼저 할 일은 심판이 쓸 LLM 키를 등록하는 것이다. 프로젝트 설정의 LLM Connections에서 OpenAI나 Anthropic 같은 제공자의 API 키를 넣는다. 평가 자체도 LLM 호출이라 별도 키가 있어야 돌아간다.
그다음 Evaluators에서 평가 템플릿을 고르거나 직접 쓴다. 내장 템플릿에는 환각, 유용성, 관련성 같은 기준이 있고, 채점 프롬프트와 출력 스코어 범위를 커스텀할 수 있다. 템플릿을 만든 뒤에는 어떤 트레이스에 적용할지 범위를 정한다. 전체 트레이스에 걸면 평가 비용이 그만큼 나가니, 운영에서는 샘플링 비율을 낮춰 일부에만 거는 쪽을 택한다.
평가가 돌면 트레이스마다 점수가 붙고, 대시보드에서 시간에 따른 평균 점수를 그래프로 본다. 프롬프트를 새 버전으로 바꾼 뒤 이 점수가 올랐는지 내렸는지가 버전 관리와 맞물려 한 화면에서 드러난다.
7. 운영에 올리기 전에
Compose 한 방으로 올라가지만, 실제 서비스에 붙일 거라면 앞단에 Nginx를 두고 TLS를 끊어 3000번을 직접 노출하지 않는다. MinIO 데이터와 Postgres, ClickHouse 볼륨은 백업 대상에 넣어야 트레이스 기록이 날아가지 않는다. 트래픽이 커지면 ClickHouse와 Postgres를 Compose 밖의 관리형으로 빼고 langfuse-web, langfuse-worker만 컨테이너로 두는 구성으로 넘어가는 게 다음 단계다.