Hub documentation
Spaces의 Langfuse
Spaces의 Langfuse
이 가이드는 Hugging Face Spaces에 Langfuse를 배포하고 LLM 애플리케이션의 관측 가능성을 위해 계측을 시작하는 방법을 보여줍니다. 이 통합을 통해 Hugging Face Hub에서 LLM API를 실험하고, 프롬프트를 한 곳에서 관리하며, 모델 출력을 평가할 수 있습니다.
Langfuse란 무엇인가요?
Langfuse는 LLM 애플리케이션의 디버깅, 평가 및 반복 개발을 팀이 협업하여 수행할 수 있도록 지원하는 오픈소스 LLM 엔지니어링 플랫폼입니다.
Langfuse의 주요 기능에는 애플리케이션 실행 흐름의 전체 컨텍스트를 캡처하는 LLM 트레이싱, 중앙 집중식 및 협업형 프롬프트 반복을 위한 프롬프트 관리, 출력 품질을 평가하는 평가 지표, 테스트 및 벤치마킹을 위한 데이터셋 생성, 그리고 프롬프트 및 모델 구성을 실험할 수 있는 플레이그라운드가 있습니다.
이 영상은 Langfuse 기능을 10분간 소개하는 내용입니다:
왜 LLM Observability인가?
- 언어 모델이 점점 더 널리 사용됨에 따라, 그 동작과 성능을 이해하는 것이 중요합니다.
- LLM observability는 LLM 애플리케이션의 출력을 통해 내부 상태를 모니터링하고 이해하는 것을 의미합니다.
- 다음과 같은 문제를 해결하는 데 필수적입니다:
- 반복되거나 체인된 호출을 포함하는 복잡한 제어 흐름으로 인해 디버깅이 어려워집니다.
- 결정론적이지 않은 출력으로 인해 일관된 품질 평가에 복잡성이 추가됩니다.
- 다양한 사용자 의도는 사용자 경험을 개선하기 위해 심층적인 이해가 필요합니다.
- LLM 애플리케이션 구축에는 복잡한 워크플로가 수반되며, 관측 가능성(Observability)은 이러한 복잡성을 관리하는 데 도움이 됩니다.
1단계: Spaces에서 Langfuse 설정하기
Langfuse Hugging Face Space를 사용하면 몇 번의 클릭만으로 배포된 Langfuse 버전을 바로 실행할 수 있습니다.
시작하려면 위의 버튼을 클릭하거나 다음 단계를 따르세요:
- 새로운 Hugging Face Space를 만듭니다
- Space SDK로 Docker를 선택
- Space 템플릿으로 Langfuse를 선택합니다
- 재시작 후에도 Langfuse 데이터가 유지되도록 Storage Bucket을 연결하세요
- Langfuse API/SDK가 앱에 액세스할 수 있도록 스페이스의 가시성이 public으로 설정되어 있는지 확인하세요 (자세한 내용은 아래 참고 사항을 참조하세요)
- [선택 사항이지만 권장됩니다] 안전한 배포를 위해 기본값을 다음 환경 변수로 변경하세요:
NEXTAUTH_SECRET: 로그인 세션 쿠키를 검증하는 데 사용되며,openssl rand -base64 32를 사용하여 최소 256 엔트로피의 시크릿을 생성합니다.SALT: 해시된 API 키에 솔팅을 적용하는 데 사용되며,openssl rand -base64 32를 사용하여 엔트로피가 최소 256인 시크릿을 생성합니다.ENCRYPTION_KEY: 민감한 데이터를 암호화하는 데 사용됩니다. 256비트, 16진수 형식의 64자 문자열이어야 하며,openssl rand -hex 32를 통해 생성합니다.
- Space 만들기를 클릭하세요!
사용자 액세스
Langfuse Space는 안전한 인증을 위해 Hugging Face OAuth가 사전 구성되어 있으므로, 첫 로그인 시 팝업의 지시에 따라 Hugging Face 계정에 대한 read 액세스를 승인해야 합니다.
앱에 진입한 후에는 네이티브 Langfuse 기능을 사용하여 Organizations, Projects, Users를 관리할 수 있습니다.
Langfuse space는 반드시 public 가시성으로 설정되어야 합니다. 이렇게 해야 Langfuse API/SDK가 앱에 접근할 수 있습니다. 이는 기본적으로 모든 로그인된 Hugging Face 사용자가 Langfuse space에 접근할 수 있음을 의미합니다.
새 사용자가 가입하고 스페이스에 액세스하는 것을 방지하려면 두 가지 다른 방법을 사용할 수 있습니다:
1. (권장) Hugging Face 네이티브 조직 수준 OAuth 제한
지정한 조직의 멤버만 액세스할 수 있도록 제한하려면, 여기에 표시된 대로 Space의 README.md 파일에 hf_oauth_authorized_org 메타데이터 필드를 설정하면 됩니다.
구성된 후에는 지정된 조직의 멤버만 해당 space에 액세스할 수 있습니다.
2. 수동 액세스 제어
AUTH_DISABLE_SIGNUP 환경 변수를 true로 설정하여 사용자별로 액세스를 제한할 수도 있습니다. 이 변수를 설정하기 전에 먼저 해당 space에 로그인 & 인증을 완료했는지 확인하세요. 그렇지 않으면 사용자 본인의 프로필이 인증할 수 없습니다.
참고:
AUTH_DISABLE_SIGNUP환경 변수를true로 설정하여 액세스를 제한한 경우, 새 사용자에게 space에 대한 액세스 권한을 부여하려면 먼저 해당 변수를false로 되돌려야 합니다(재빌드가 완료될 때까지 대기). 그런 다음 사용자를 추가하고 OAuth로 인증하도록 한 뒤, 다시true로 설정합니다.
2단계: Langfuse 사용
이제 Langfuse가 실행 중이므로, LLM 애플리케이션에 계측을 적용하여 트레이스를 캡처하고 프롬프트를 관리할 수 있습니다. 방법을 살펴보겠습니다!
모든 애플리케이션 모니터링
Langfuse는 모델에 종속적이지 않으며 어떤 애플리케이션의 트레이싱에도 사용할 수 있습니다. Langfuse 문서의 시작 가이드를 참고하여 코드를 계측하는 방법을 확인해 보세요.
Langfuse는 Langchain, LlamaIndex, OpenAI를 포함한 다양한 인기 LLM 프레임워크와 네이티브 통합을 제공하며, 코드를 계측하기 위한 Python 및 JS/TS SDK를 제공합니다. 또한 데이터를 수집하기 위한 다양한 API 엔드포인트를 제공하며, Langflow, Dify, Haystack와 같은 다른 오픈 소스 프로젝트에서도 통합되어 있습니다.
예제 1: 추론 제공자 호출 추적
간단한 예시로, Langfuse Python SDK를 사용하여 Inference Providers에 대한 LLM 호출을 추적하는 방법을 살펴보겠습니다.
먼저 LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY 환경 변수를 설정하고, Hugging Face 계정으로 인증했는지 확인하세요.
from langfuse.openai import openai
from huggingface_hub import get_token
client = openai.OpenAI(
base_url="https://huggingface.co/proxy/router.huggingface.co/hf-inference/models/meta-llama/Llama-3.3-70B-Instruct/v1",
api_key=get_token(),
)
messages = [{"role": "user", "content": "What is observability for LLMs?"}]
response = client.chat.completions.create(
model="meta-llama/Llama-3.3-70B-Instruct",
messages=messages,
max_tokens=100,
)예제 2: Gradio 애플리케이션 모니터링
Hugging Face 모델을 사용하여 간단한 채팅 애플리케이션을 만들고 Langfuse에서 모델 호출 및 사용자 피드백을 추적하는 방법을 보여주는 Gradio 템플릿 스페이스를 만들었습니다. Hugging Face를 벗어나지 않고도 가능합니다.
시작하려면 이 Gradio 템플릿 스페이스를 복제하고 README의 지침을 따르세요.
3단계: Langfuse에서 트레이스 보기
애플리케이션에 계측을 적용하고 Langfuse로 트레이스 또는 사용자 피드백을 수집한 후에는 Langfuse에서 트레이스를 확인할 수 있습니다.
추가 리소스 및 지원
추가 도움이 필요하면 GitHub discussions에서 지원 스레드를 열거나 이슈를 등록하세요.
Update on GitHub