HuggingFace — 학습 허브

01

HuggingFace 개요 & 설치

HuggingFace 개요 & InferenceClient 설치

HuggingFace — 전 세계 AI 연구자가 만든 모델·데이터셋·데모 무료 공유 플랫폼
코드 몇 줄로 GPT급 LLM·이미지 생성 AI 즉시 사용

주요 기능

• Models — LLM·이미지 생성·번역·분류 등 수십만 개 모델 무료 제공
• Datasets — 학습용 데이터셋 저장소
• Spaces — Gradio/Streamlit 앱 데모 호스팅
• InferenceClient — API 한 줄로 모델 호출

설치 명령어

pip install huggingface_hub   # HuggingFace 공식 SDK → InferenceClient·model_info·login 등 일체 제공

InferenceClient 초기화

from huggingface_hub import InferenceClient  # 추론 전용 HTTP 클라이언트 임포트 → 모델 호출 한 줄로 처리

# provider="auto" : 가장 빠른 무료 서버 자동 선택 → 왜: 모델마다 호스팅 서버 다름, 수동 지정 번거로움
client = InferenceClient(provider="auto")  # 클라이언트 인스턴스 생성 → 이후 client.chat_completion() 등 호출 가능

사용 가능한 모델 예시

deepseek-ai/DeepSeek-V3.2 meta-llama/Llama-3 black-forest-labs/FLUX.1-dev stabilityai/stable-diffusion

02

LLM 채팅

LLM 채팅 구현

파일: v17_01_llm.py

InferenceClient로 DeepSeek-V3.2 호출 → 사용자 질문 답변 생성
ChatGPT 동일 chat.completions 패턴

전체 코드

from huggingface_hub import InferenceClient

# 1단계 → 왜: 매 요청마다 인증·라우팅 반복 불필요. 어떻게: 클라이언트 1회 생성 후 재사용
client = InferenceClient(provider="auto")  # auto → 무료 서버 자동 선택

# 2단계 → 왜: 모델 입력은 문자열 필수. 어떻게: input()으로 콘솔 1줄 수집
answer = input("질문을 입력해주세요. : ")

# 3단계 → 왜: LLM은 단일 질문 아닌 "대화 이력" 입력 받음. 어떻게: messages 리스트로 역할-내용 페어 전달
completion = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V3.2:novita",  # :novita → novita.ai 무료 라우팅
    messages=[
        {
            "role": "user",       # 발화자 구분 (user/assistant/system)
            "content": answer     # 실제 질문 본문
        }
    ],
)

# 4단계 → 왜: API는 후보 답변 N개 반환 가능. 어떻게: choices[0]로 첫 응답 추출
print(completion.choices[0].message)

핵심 개념

• chat.completions.create() — OpenAI API 동일 인터페이스
• messages 리스트 — role(user/assistant/system) + content 구성
• choices[0].message — 모델 생성 답변 텍스트
• :novita — novita.ai 서버 경유 무료 호출 경로

03

이미지 생성 (TTI)

Text-to-Image 이미지 생성

파일: v17_02_tti.py

텍스트 설명 → FLUX.1-dev 고품질 이미지 생성
PIL Image 객체 반환 → 파일 저장

전체 코드

from huggingface_hub import InferenceClient

client = InferenceClient(provider="auto")

# 1단계 → 이미지 설명 입력
answer = input("생성할 이미지를 설명해주세요. : ")

# 2단계 → 왜: 텍스트는 픽셀 아님, 모델이 의미 해석 후 픽셀 합성 필요
#         어떻게: text_to_image() 호출 → PIL.Image 객체 반환
image = client.text_to_image(
    answer,
    model="black-forest-labs/FLUX.1-dev",
)

# 3단계 → PIL.Image.save() 호출, 확장자로 포맷 자동 결정
image.save("tti_result.jpg")

print("전체 코드가 잘 실행됐습니다.")

프롬프트 팁

• 영어 작성 시 품질 향상
• 스타일 키워드: digital art, photorealistic, watercolor, anime style
• 품질 키워드: high quality, 4K, detailed, sharp
• 예시: "cute cat sitting on a rooftop, sunset, anime style, high quality"

FLUX.1-dev 특징

• Meta·Black Forest Labs 공동 개발
• 1회 실행 1~3분 (무료 서버 기준)
• 최대 1024×1024 해상도

04

허깅페이스 탐구

허깅페이스 자율 탐구 — 사이트 둘러보고 원하는 모델 직접 구현
예시: 아바타 생성 모델 선택 → Streamlit 웹앱화

앱 핵심 흐름

① 이름·설명 입력 → ② 귀여운 스타일 프롬프트 자동 생성 → ③ FLUX 이미지 생성 → ④ JPG·CSV 저장 → ⑤ 갤러리 확인·다운로드

프롬프트 자동 생성 로직

# 사용자 설명을 귀여운 스타일 프롬프트로 자동 변환
# 왜: 모델은 영문 키워드 조합에 강함, 한글 짧은 입력만으론 품질 낮음
cute_prompt = (
    f"Cute adorable character illustration, "
    f"lovely kawaii style: {user_description}. "
    f"Bright colors, friendly expression, "
    f"digital art, high quality"
)

# FLUX로 이미지 생성 → PIL.Image 객체 반환
image = client.text_to_image(
    cute_prompt,
    model="black-forest-labs/FLUX.1-dev",
)

이미지 & 기록 저장

# JPG 저장 → PIL.save() 호출, 확장자로 포맷 자동 결정
image_path = f"avatar_records/avatar_{timestamp}_{user_name}.jpg"
image.save(image_path, "JPEG")

# CSV 메타데이터 저장
# 왜: 이미지만으론 누가·언제·왜 생성됐는지 추적 불가 → 갤러리 검색·필터링용 메타 동반 저장
new_record = {
    "생성일시": timestamp,
    "이름": user_name,
    "설명": user_description,
    "이미지파일": image_path,
}
df = pd.concat([df, pd.DataFrame([new_record])])
df.to_csv("avatar_records/avatar_records.csv", index=False)

실행 방법

pip install streamlit huggingface_hub pillow pandas   # 의존성 일괄 설치
streamlit run v17_03_avatar_generator.py   # 브라우저 자동 오픈 → http://localhost:8501