> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Hugging Face Hub
> Hugging Face Hub를 W&B Weave와 통합하여 머신 러닝 애플리케이션을 추적하고 분석하세요
이 페이지에 표시된 모든 코드 샘플은 Python으로 작성되었습니다.
이 페이지에서는 [Hugging Face Hub](https://huggingface.co/)를 W\&B Weave와 통합하여 머신 러닝 애플리케이션을 추적하고 분석하는 방법을 설명합니다. 모델 Inference를 기록하고, 함수 호출을 모니터링하며, Weave의 트레이싱 및 버전 관리 기능을 사용해 실험을 구성하는 방법을 알아봅니다. 제공된 예제를 따라 하면 유용한 인사이트를 포착하고, 애플리케이션의 버그를 효율적으로 디버깅하며, 서로 다른 모델 설정을 비교할 수 있습니다. 이 모든 작업은 Weave 웹 인터페이스 내에서 수행할 수 있습니다.
**Google Colab에서 Weave로 Hugging Face Hub 사용해 보기**
별도의 설정 없이 Hugging Face Hub와 Weave를 사용해 보고 싶으신가요? 여기 표시된 코드 샘플을 Google Colab의 Jupyter Notebook에서 사용해 볼 수 있습니다.
## Overview
Hugging Face Hub는 제작자와 협업자를 위한 머신 러닝 플랫폼으로, 여러 유형의 프로젝트에 사용할 수 있는 방대한 사전 학습 모델과 데이터셋을 제공합니다.
`huggingface_hub` Python 라이브러리는 Hub에 호스팅된 모델에 대해 여러 서비스 전반에서 Inference를 실행할 수 있는 통합 인터페이스를 제공합니다. [`InferenceClient`](https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client)를 사용해 이러한 모델을 호출할 수 있습니다.
Weave는 `InferenceClient`의 트레이스를 자동으로 수집합니다. 추적을 시작하려면 `weave.init()`를 호출한 다음 평소처럼 라이브러리를 사용하세요.
## 사전 요구 사항
시작하기 전에 필요한 라이브러리를 설치하고 Hugging Face Hub에 대한 액세스를 구성하려면 다음 설정 단계를 완료하세요:
1. Weave에서 `huggingface_hub`를 사용하려면 먼저 필요한 라이브러리를 설치하거나 최신 버전으로 업그레이드해야 합니다. 다음 명령어는 `huggingface_hub`와 `weave`가 이미 설치된 경우 최신 버전으로 업그레이드하고, 설치되어 있지 않은 경우 설치하며, 설치 출력도 최소화합니다.
```python lines theme={null}
pip install -U huggingface_hub weave -qqq
```
2. Hugging Face Hub의 모델에 대해 Inference를 사용하려면 [User Access Token](https://huggingface.co/docs/hub/security-tokens)을 설정하세요. 토큰은 [Hugging Face Hub Settings page](https://huggingface.co/login?next=%2Fsettings%2Ftokens)에서 설정하거나, 프로그래밍 방식으로 설정할 수 있습니다. 다음 코드 예제는 사용자가 `HUGGINGFACE_TOKEN`을 입력하라는 프롬프트를 표시한 뒤, 해당 토큰을 환경 변수로 설정합니다.
```python lines theme={null}
import os
import getpass
os.environ["HUGGINGFACE_TOKEN"] = getpass.getpass("Enter your Hugging Face Hub Token: ")
```
## 기본 트레이싱
개발 및 프로덕션 환경에서는 언어 모델 애플리케이션의 트레이스를 중앙에서 저장하는 것이 중요합니다. 이러한 트레이스는 디버깅에 도움이 되며, 애플리케이션 개선에 활용할 수 있는 데이터셋이기도 합니다.
Weave는 `InferenceClient`의 트레이스를 자동으로 수집합니다. 추적을 시작하려면 `weave.init()`를 호출해 Weave를 초기화한 다음 평소처럼 라이브러리를 사용하세요.
다음 예시는 Weave를 사용해 Hugging Face Hub에 Inference call을 로깅하는 방법을 보여줍니다:
```python lines theme={null}
import weave
from huggingface_hub import InferenceClient
# Weave 초기화
weave.init(project_name="quickstart-huggingface")
# Hugging Face Inference Client 초기화
huggingface_client = InferenceClient(
api_key=os.environ.get("HUGGINGFACE_TOKEN")
)
# Llama-3.2-11B-Vision-Instruct 모델을 사용해 Hugging Face Hub에 chat completion inference call 수행
image_url = "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
response = huggingface_client.chat_completion(
model="meta-llama/Llama-3.2-11B-Vision-Instruct",
messages=[
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": image_url}},
{"type": "text", "text": "Describe this image in one sentence."},
],
}
],
max_tokens=500,
seed=42,
)
```
이전 코드가 실행되면 Weave가 Hugging Face Inference Client를 사용해 이루어진 모든 LLM calls를 추적하고 로깅합니다. 이러한 트레이스는 Weave 웹 인터페이스에서 확인할 수 있습니다.
Weave는 각 Inference call을 로깅하고 입력, 출력, 메타데이터에 대한 세부 정보를 제공합니다.
Weave는 또한 해당 call을 UI에서 채팅 뷰로 표시하여 모델과의 전체 채팅 이력을 보여줍니다.
## 함수를 트레이스하기
애플리케이션에서 데이터가 어떻게 흐르는지 더 깊이 파악하려면 `@weave.op`를 사용해 함수 호출을 추적할 수 있습니다. 이렇게 하면 입력, 출력, 실행 로직이 캡처되어 디버깅과 성능 분석에 도움이 됩니다.
여러 op를 중첩하면 추적된 함수의 구조화된 트리를 만들 수 있습니다. Weave는 코드도 자동으로 버전 관리하므로 Git에 변경 사항을 커밋하기 전, 실험하는 동안의 중간 상태까지 보존합니다.
추적을 시작하려면 추적하려는 함수에 `@weave.op`를 데코레이터로 추가하세요.
다음 예시에서 Weave는 `generate_image`, `check_image_correctness`, `generate_image_and_check_correctness`의 세 함수를 추적합니다. 이 함수들은 이미지를 생성하고, 생성된 이미지가 주어진 프롬프트와 일치하는지 검증합니다.
```python lines theme={null}
import base64
from PIL import Image
def encode_image(pil_image):
import io
buffer = io.BytesIO()
pil_image.save(buffer, format="JPEG")
buffer.seek(0)
encoded_image = base64.b64encode(buffer.read()).decode("utf-8")
return f"data:image/jpeg;base64,{encoded_image}"
@weave.op
def generate_image(prompt: str):
return huggingface_client.text_to_image(
prompt=prompt,
model="black-forest-labs/FLUX.1-schnell",
num_inference_steps=4,
)
@weave.op
def check_image_correctness(image: Image.Image, image_generation_prompt: str):
return huggingface_client.chat_completion(
model="meta-llama/Llama-3.2-11B-Vision-Instruct",
messages=[
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": encode_image(image)}},
{
"type": "text",
"text": f"Is this image correct for the prompt: {image_generation_prompt}? Answer with only one word: yes or no",
},
],
}
],
max_tokens=500,
seed=42,
).choices[0].message.content
@weave.op
def generate_image_and_check_correctness(prompt: str):
image = generate_image(prompt)
return {
"image": image,
"is_correct": check_image_correctness(image, prompt),
}
response = generate_image_and_check_correctness("A cute puppy")
```
Weave는 이제 `@weave.op`로 감싼 모든 함수 호출을 로깅하므로 Weave UI에서 실행 세부 사항을 분석할 수 있습니다.
또한 Weave는 함수 실행을 포착해 시각화하여 애플리케이션 내 데이터 흐름과 로직을 이해하는 데 도움을 줍니다.
## 실험에 `Model` 활용하기
여러 컴포넌트가 얽힌 LLM 실험은 관리하기가 까다로울 수 있습니다. Weave [`Model`](../core-types/models) 클래스는 시스템 프롬프트와 모델 설정 같은 실험 세부 정보를 기록하고 정리해, 서로 다른 반복 버전을 비교할 수 있게 해줍니다.
코드를 버전 관리하고 입력과 출력을 기록하는 것 외에도, `Model`은 애플리케이션 동작을 제어하는 구조화된 매개변수를 저장합니다. 따라서 어떤 설정이 가장 좋은 결과를 냈는지 추적할 수 있습니다. 또한 Weave `Model`을 Weave [서빙](../tools/serve) 및 [Evaluations](../evaluation/scorers)와 통합해 더 많은 인사이트를 얻을 수 있습니다.
다음 예시에서는 여행 추천용 `CityVisitRecommender` 모델을 정의합니다. 매개변수를 수정할 때마다 새 버전이 생성되어 반복적인 실험을 지원합니다.
```python lines theme={null}
import rich
class CityVisitRecommender(weave.Model):
model: str
temperature: float = 0.7
max_tokens: int = 500
seed: int = 42
@weave.op()
def predict(self, city: str) -> str:
return huggingface_client.chat_completion(
model=self.model,
messages=[
{
"role": "system",
"content": "You are a helpful assistant meant to suggest places to visit in a city",
},
{"role": "user", "content": city},
],
max_tokens=self.max_tokens,
temperature=self.temperature,
seed=self.seed,
).choices[0].message.content
city_visit_recommender = CityVisitRecommender(
model="meta-llama/Llama-3.2-11B-Vision-Instruct",
temperature=0.7,
max_tokens=500,
seed=42,
)
rich.print(city_visit_recommender.predict("New York City"))
rich.print(city_visit_recommender.predict("Paris"))
```
Weave는 모델을 자동으로 로깅하고 여러 버전을 추적하므로 성능과 실험 이력을 분석할 수 있습니다.
