# Spaces의 Langfuse

이 가이드는 Hugging Face Spaces에 Langfuse를 배포하고 LLM 애플리케이션의 관측 가능성을 위해 계측을 시작하는 방법을 보여줍니다. 이 통합을 통해 Hugging Face Hub에서 LLM API를 실험하고, 프롬프트를 한 곳에서 관리하며, 모델 출력을 평가할 수 있습니다.

## Langfuse란 무엇인가요?

[Langfuse](https://langfuse.com)는 LLM 애플리케이션의 디버깅, 평가 및 반복 개발을 팀이 협업하여 수행할 수 있도록 지원하는 오픈소스 LLM 엔지니어링 플랫폼입니다.

Langfuse의 주요 기능에는 애플리케이션 실행 흐름의 전체 컨텍스트를 캡처하는 LLM 트레이싱, 중앙 집중식 및 협업형 프롬프트 반복을 위한 프롬프트 관리, 출력 품질을 평가하는 평가 지표, 테스트 및 벤치마킹을 위한 데이터셋 생성, 그리고 프롬프트 및 모델 구성을 실험할 수 있는 플레이그라운드가 있습니다.

_이 영상은 Langfuse 기능을 10분간 소개하는 내용입니다:_

## 왜 LLM Observability인가?

- 언어 모델이 점점 더 널리 사용됨에 따라, 그 동작과 성능을 이해하는 것이 중요합니다.
- **LLM observability**는 LLM 애플리케이션의 출력을 통해 내부 상태를 모니터링하고 이해하는 것을 의미합니다.
- 다음과 같은 문제를 해결하는 데 필수적입니다:
  - 반복되거나 체인된 호출을 포함하는 **복잡한 제어 흐름**으로 인해 디버깅이 어려워집니다.
  - **결정론적이지 않은 출력**으로 인해 일관된 품질 평가에 복잡성이 추가됩니다.
  - **다양한 사용자 의도**는 사용자 경험을 개선하기 위해 심층적인 이해가 필요합니다.
- LLM 애플리케이션 구축에는 복잡한 워크플로가 수반되며, 관측 가능성(Observability)은 이러한 복잡성을 관리하는 데 도움이 됩니다.

## 1단계: Spaces에서 Langfuse 설정하기

Langfuse Hugging Face Space를 사용하면 몇 번의 클릭만으로 배포된 Langfuse 버전을 바로 실행할 수 있습니다.

    

시작하려면 위의 버튼을 클릭하거나 다음 단계를 따르세요:

1. [**새로운 Hugging Face Space**](https://huggingface.co/new-space)를 만듭니다
2. Space SDK로 **Docker**를 선택
3. Space 템플릿으로 **Langfuse**를 선택합니다
4. 재시작 후에도 Langfuse 데이터가 유지되도록 **[Storage Bucket](https://huggingface.co/docs/hub/storage-buckets)**을 연결하세요
5. Langfuse API/SDK가 앱에 액세스할 수 있도록 스페이스의 가시성이 **public**으로 설정되어 있는지 확인하세요 (자세한 내용은 아래 참고 사항을 참조하세요)
6. [선택 사항이지만 권장 사항] 안전한 배포를 위해 **환경 변수**의 기본값을 변경하세요:
   - `NEXTAUTH_SECRET`: 로그인 세션 쿠키를 검증하는 데 사용되며, `openssl rand -base64 32`를 사용하여 최소 256 엔트로피의 시크릿을 생성합니다.
   - `SALT`: 해시된 API 키에 솔팅을 적용하는 데 사용되며, `openssl rand -base64 32`를 사용하여 엔트로피가 최소 256인 시크릿을 생성합니다.
   - `ENCRYPTION_KEY`: 민감한 데이터를 암호화하는 데 사용됩니다. 256비트, 16진수 형식의 64자 문자열이어야 하며, `openssl rand -hex 32`를 통해 생성합니다.
7. **Space 만들기**를 클릭하세요!

![Clone the Langfuse Space](https://langfuse.com/images/cookbook/huggingface/huggingface-space-setup.png)

### 사용자 액세스

Langfuse Space는 안전한 인증을 위해 Hugging Face OAuth가 사전 구성되어 있으므로, 첫 로그인 시 팝업의 지시에 따라 Hugging Face 계정에 대한 `read` 액세스 권한을 승인해야 합니다.

앱에 진입한 후에는 [네이티브 Langfuse 기능](https://langfuse.com/docs/rbac)을 사용하여 Organizations, Projects, Users를 관리할 수 있습니다.

Langfuse space는 _반드시_ **public** 가시성으로 설정되어야 합니다. 이렇게 해야 Langfuse API/SDK가 앱에 접근할 수 있습니다. 이는 기본적으로 _모든_ 로그인된 Hugging Face 사용자가 Langfuse space에 접근할 수 있음을 의미합니다.

새 사용자가 가입하고 스페이스에 액세스하는 것을 방지하려면 두 가지 다른 방법을 사용할 수 있습니다:

#### 1. (권장) Hugging Face 네이티브 조직 수준 OAuth 제한

지정한 조직의 멤버만 액세스할 수 있도록 제한하려면, [여기](https://huggingface.co/docs/hub/spaces-oauth#create-an-oauth-app)에 표시된 대로 Space의 `README.md` 파일에 `hf_oauth_authorized_org` 메타데이터 필드를 설정하면 됩니다.

구성된 후에는 지정된 조직의 멤버만 해당 space에 액세스할 수 있습니다.

#### 2. 수동 액세스 제어

`AUTH_DISABLE_SIGNUP` 환경 변수를 `true`로 설정하여 사용자별로 액세스를 제한할 수도 있습니다. 이 변수를 설정하기 전에 먼저 해당 space에 로그인 & 인증을 완료했는지 확인하세요. 그렇지 않으면 사용자 본인의 프로필이 인증할 수 없습니다.

> [!TIP]
> **참고:** `AUTH_DISABLE_SIGNUP` 환경 변수를 `true`로 설정하여 액세스를 제한한 경우, 새 사용자에게 space에 대한 액세스 권한을 부여하려면 먼저 해당 변수를 `false`로 되돌려야 합니다(재빌드가 완료될 때까지 대기). 그런 다음 사용자를 추가하고 OAuth로 인증하도록 한 뒤, 다시 `true`로 설정합니다.

## 2단계: Langfuse 사용

이제 Langfuse가 실행 중이므로, LLM 애플리케이션에 계측을 적용하여 트레이스를 캡처하고 프롬프트를 관리할 수 있습니다. 방법을 살펴보겠습니다!

### 모든 애플리케이션 모니터링 

Langfuse는 모델에 종속적이지 않으며 어떤 애플리케이션의 트레이싱에도 사용할 수 있습니다. Langfuse 문서의 [시작 가이드](https://langfuse.com/docs)를 참고하여 코드를 계측하는 방법을 확인해 보세요.

Langfuse는 [Langchain](https://langfuse.com/docs/integrations/langchain/tracing), [LlamaIndex](https://langfuse.com/docs/integrations/llama-index/get-started), [OpenAI](https://langfuse.com/docs/integrations/openai/python/get-started)를 포함한 다양한 인기 LLM 프레임워크와 네이티브 통합을 제공하며, 코드를 계측하기 위한 Python 및 JS/TS SDK를 제공합니다. 또한 데이터를 수집하기 위한 다양한 API 엔드포인트를 제공하며, [Langflow](https://langfuse.com/docs/integrations/langflow), [Dify](https://langfuse.com/docs/integrations/dify), [Haystack](https://langfuse.com/docs/integrations/haystack/get-started)와 같은 다른 오픈 소스 프로젝트에서도 통합되어 있습니다.

### 예제 1: 추론 제공자 호출 추적

간단한 예시로, Langfuse Python SDK를 사용하여 [Inference Providers](https://huggingface.co/docs/inference-providers/en/index)에 대한 LLM 호출을 추적하는 방법을 살펴보겠습니다.

먼저 `LANGFUSE_HOST`, `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` 환경 변수를 설정하고, [Hugging Face 계정으로 인증](https://huggingface.co/docs/huggingface_hub/en/quick-start#authentication)했는지 확인하세요.

```python
from langfuse.openai import openai
from huggingface_hub import get_token

client = openai.OpenAI(
    base_url="https://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 템플릿 스페이스를 복제](https://huggingface.co/spaces/langfuse/langfuse-gradio-example-template?duplicate=true)하고 [README](https://huggingface.co/spaces/langfuse/langfuse-gradio-example-template/blob/main/README.md)의 지침을 따르세요.

## 3단계: Langfuse에서 트레이스 보기

애플리케이션에 계측을 적용하고 Langfuse로 트레이스 또는 사용자 피드백을 수집한 후에는 Langfuse에서 트레이스를 확인할 수 있습니다.

![Example trace with Gradio](https://langfuse.com/images/cookbook/huggingface/huggingface-gradio-example-trace.png)

_[Langfuse UI의 예시 trace](https://langfuse-langfuse-template-space.hf.space/project/cm4r1ajtn000a4co550swodxv/traces/9cdc12fb-71bf-4074-ab0b-0b8d212d839f?timestamp=2024-12-20T12%3A12%3A50.089Z&view=preview)_

## 추가 리소스 및 지원

- [Langfuse 문서](https://langfuse.com/docs)
- [Langfuse GitHub 저장소](https://github.com/langfuse/langfuse)
- [Langfuse Discord](https://langfuse.com/discord)
- [Langfuse 템플릿 Space](https://huggingface.co/spaces/langfuse/langfuse-template-space)

추가 도움이 필요하면 [GitHub discussions](https://langfuse.com/discussions)에서 지원 스레드를 열거나 [이슈를 등록](https://github.com/langfuse/langfuse/issues)하세요.