> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.
# Langfuse
**LLM Observability(관측) 플랫폼**입니다. LLM 애플리케이션의 동작을 추적하고 분석할 수 있습니다.
## 어디에 쓰이나요?
* **트레이싱**: LLM 호출의 입력, 출력, 소요 시간, 비용을 기록하고 시각화
* **디버깅**: RAG 파이프라인에서 어떤 문서가 검색되었는지, 프롬프트가 어떻게 구성되었는지 단계별로 추적
* **프롬프트 관리**: 프롬프트 템플릿의 버전 관리 및 배포
* **평가(Evaluation)**: LLM 응답의 품질을 자동/수동으로 평가하고 점수 관리
* **비용 분석**: 모델별, 기능별 API 호출 비용 추적
LLM 애플리케이션은 프롬프트, 검색 결과, 모델 응답 등 여러 단계를 거쳐 최종 결과를 생성합니다. 문제가 발생했을 때 어떤 단계에서 잘못되었는지 파악하기 어려운데, Langfuse를 사용하면 각 단계를 **트레이스**(Trace)로 기록하고 웹 UI에서 확인할 수 있습니다.
## Docker Compose
Langfuse v3는 PostgreSQL, ClickHouse, Redis, MinIO(S3 호환 스토리지)를 함께 사용합니다.
```yaml docker-compose.yml theme={null}
services:
langfuse-web:
image: langfuse/langfuse:3
container_name: langfuse-web
restart: always
ports:
- "3000:3000"
environment:
- DATABASE_URL=postgresql://postgres:changeme@langfuse-db:5432/langfuse
- NEXTAUTH_URL=http://localhost:3000
- NEXTAUTH_SECRET=changeme
- SALT=changeme
- ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
- CLICKHOUSE_URL=http://langfuse-clickhouse:8123
- CLICKHOUSE_USER=default
- CLICKHOUSE_PASSWORD=changeme
- REDIS_CONNECTION_STRING=redis://:changeme@langfuse-redis:6379/0
- LANGFUSE_S3_BUCKET_NAME=langfuse
- LANGFUSE_S3_ENDPOINT=http://langfuse-minio:9000
- LANGFUSE_S3_ACCESS_KEY_ID=minioadmin
- LANGFUSE_S3_SECRET_ACCESS_KEY=changeme
- LANGFUSE_S3_REGION=auto
depends_on:
langfuse-db:
condition: service_healthy
langfuse-clickhouse:
condition: service_healthy
langfuse-minio:
condition: service_healthy
langfuse-redis:
condition: service_healthy
langfuse-worker:
image: langfuse/langfuse:3
container_name: langfuse-worker
restart: always
command: ["node", "packages/worker/dist/app.js"]
environment:
- DATABASE_URL=postgresql://postgres:changeme@langfuse-db:5432/langfuse
- NEXTAUTH_URL=http://localhost:3000
- NEXTAUTH_SECRET=changeme
- SALT=changeme
- ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
- CLICKHOUSE_URL=http://langfuse-clickhouse:8123
- CLICKHOUSE_USER=default
- CLICKHOUSE_PASSWORD=changeme
- REDIS_CONNECTION_STRING=redis://:changeme@langfuse-redis:6379/0
- LANGFUSE_S3_BUCKET_NAME=langfuse
- LANGFUSE_S3_ENDPOINT=http://langfuse-minio:9000
- LANGFUSE_S3_ACCESS_KEY_ID=minioadmin
- LANGFUSE_S3_SECRET_ACCESS_KEY=changeme
- LANGFUSE_S3_REGION=auto
depends_on:
langfuse-db:
condition: service_healthy
langfuse-clickhouse:
condition: service_healthy
langfuse-minio:
condition: service_healthy
langfuse-redis:
condition: service_healthy
langfuse-db:
image: postgres:17-alpine
container_name: langfuse-db
restart: always
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=changeme
- POSTGRES_DB=langfuse
ports:
- "127.0.0.1:5432:5432"
volumes:
- langfuse_db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 3s
timeout: 3s
retries: 10
langfuse-redis:
image: redis:7
container_name: langfuse-redis
restart: always
command: ["redis-server", "--requirepass", "changeme"]
ports:
- "127.0.0.1:6379:6379"
langfuse-clickhouse:
image: clickhouse/clickhouse-server:24
container_name: langfuse-clickhouse
restart: always
environment:
- CLICKHOUSE_USER=default
- CLICKHOUSE_PASSWORD=changeme
ports:
- "127.0.0.1:8123:8123"
volumes:
- langfuse_clickhouse_data:/var/lib/clickhouse
- langfuse_clickhouse_logs:/var/log/clickhouse-server
healthcheck:
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8123/ping"]
interval: 3s
timeout: 3s
retries: 10
langfuse-minio:
image: minio/minio
container_name: langfuse-minio
restart: always
command: server /data --console-address ":9090"
environment:
- MINIO_ROOT_USER=minioadmin
- MINIO_ROOT_PASSWORD=changeme
ports:
- "9090:9090"
- "127.0.0.1:9000:9000"
volumes:
- langfuse_minio_data:/data
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 3s
timeout: 3s
retries: 10
volumes:
langfuse_db_data:
langfuse_clickhouse_data:
langfuse_clickhouse_logs:
langfuse_minio_data:
```
위 설정의 `NEXTAUTH_SECRET`, `SALT`, `ENCRYPTION_KEY`, 각 서비스의 비밀번호는 반드시 변경 후 사용합니다. `ENCRYPTION_KEY`는 64자 hex 문자열이어야 합니다.
## 실행
```bash theme={null}
docker compose up -d
```
초기 기동 시 2\~3분 정도 소요될 수 있습니다.
## 접속 확인
브라우저에서 `http://localhost:3000`으로 접속합니다. 초기 접속 시 회원가입 화면이 표시됩니다.
```bash theme={null}
# 로그 확인
docker compose logs -f langfuse-web
```
## 조직 생성부터 API 키 발급까지
컨테이너 실행 후 아래 순서로 초기 설정을 진행합니다.
### 1) 조직 생성
조직 이름을 입력하고 **Create**를 클릭합니다.
### 2) 멤버 초대
**Invite members** 단계에서 팀원을 초대합니다. 나중에 추가해도 됩니다.
### 3) 프로젝트 생성
프로젝트 이름을 입력하고 **Create**를 클릭합니다.
### 4) API 키 발급 화면으로 이동
프로젝트 홈의 **Get started** 섹션에서 **Create new API key**를 클릭합니다.
### 5) API 키 발급 완료
`Secret Key`와 `Public Key`를 발급받고 안전한 위치에 저장합니다.
API 키는 비밀번호처럼 관리합니다. 문서, 코드, 채팅에 원문 키를 그대로 공유하지 마세요.
## 기본 정보
| 항목 | 값 |
| ---------------- | ----------------------- |
| 웹 UI 포트 | 3000 |
| MinIO Console 포트 | 9090 |
| 데이터베이스 | PostgreSQL + ClickHouse |
| 캐시 | Redis |
| 오브젝트 스토리지 | MinIO |
## 포함된 서비스
| 서비스 | 역할 |
| ------------------- | --------------------- |
| langfuse-web | 웹 UI / API 서버 |
| langfuse-worker | 비동기 작업 처리 |
| langfuse-db | PostgreSQL (메타데이터) |
| langfuse-clickhouse | ClickHouse (트레이스 데이터) |
| langfuse-redis | Redis (캐시, 큐) |
| langfuse-minio | MinIO (미디어 스토리지) |
## 환경 변수
| 변수 | 설명 |
| ------------------------- | ----------------- |
| `DATABASE_URL` | PostgreSQL 연결 문자열 |
| `NEXTAUTH_SECRET` | NextAuth 세션 암호화 키 |
| `NEXTAUTH_URL` | 외부 접속 URL |
| `SALT` | 해시 솔트 |
| `ENCRYPTION_KEY` | 암호화 키 (64자 hex) |
| `CLICKHOUSE_URL` | ClickHouse 연결 URL |
| `REDIS_CONNECTION_STRING` | Redis 연결 문자열 |
| `LANGFUSE_S3_*` | MinIO/S3 스토리지 설정 |
## SDK 연동
Langfuse에서 프로젝트를 생성하고 API 키를 발급받아 SDK에서 사용합니다.
```python theme={null}
from langfuse import Langfuse
langfuse = Langfuse(
public_key="pk-...",
secret_key="sk-...",
host="http://localhost:3000"
)
```
## 라이선스
| 구분 | 내용 |
| ------ | ------------------------------------------------------ |
| 라이선스 | MIT (core), Elastic License 2.0 (일부 기능) |
| 개인 사용 | 자유롭게 사용 가능 |
| 상업적 사용 | 사내 사용은 자유. Langfuse를 관리형 서비스(SaaS)로 제공하는 것은 ELv2 제한 대상 |
## 참고
* [Langfuse Docker Compose 가이드](https://langfuse.com/self-hosting/deployment/docker-compose)
* [Langfuse GitHub](https://github.com/langfuse/langfuse)
## 설치 점검 목록
* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.
## 문제 해결 가이드
* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.
## 관련 문서
운영체제별 설치 흐름을 다시 확인합니다.
다음 설치 단계를 이어서 진행합니다.