Apppublic

chansung/hf-open-source-ai-lab

sourceHugging Faceupdated 5mo agoView on Hugging Face

1likes

App README

🤗 Open Model Playground

Hugging Face 오픈소스 AI 실습 랩

강의: "Hugging Face 기술을 통해 AI 분야에서 오픈소스 활동하는 방법"

학습 목표

이 실습을 통해 다음을 학습합니다:

1.오픈소스 AI 모델 이해: Hugging Face Hub에서 텍스트 생성 및 이미지 생성 모델을 탐색하고 사용하는 방법
2.Transformers & Diffusers: transformers 라이브러리로 텍스트 생성, diffusers 라이브러리로 이미지 생성
3.Gradio 앱 개발: Gradio Blocks를 사용하여 인터랙티브 AI 데모 앱 구축
4.Hugging Face Space 배포: 로컬에서 개발한 앱을 Hugging Face Space에 배포
5.API 검증: Gradio Client를 통해 배포된 앱의 API 엔드포인트 테스트

앱 기능

탭	기능	사용 모델
텍스트 생성	한국어/영어 텍스트 생성 (Thinking 모드 지원)	`Qwen/Qwen3-4B`
이미지 생성	텍스트→이미지 생성	`FLUX.2-dev`

필수 환경

—Python 3.10+
—macOS (M1/M2/M3) 또는 CUDA GPU 또는 CPU
—Hugging Face 계정 (Space 배포용)
—최소 8GB RAM (권장 16GB+)

로컬 실행

1. 패키지 설치

bash

pip install -r requirements.txt

2. 환경 확인

bash

python scripts/check_env.py

3. 앱 실행

bash

python app.py
# 또는
python scripts/run_local_server.py

브라우저에서 http://127.0.0.1:7860을 열면 앱이 실행됩니다.

4. 로컬 API 테스트

bash

# 서버 실행 후 다른 터미널에서
python scripts/api_smoke_test.py --target http://127.0.0.1:7860

Hugging Face Space 배포

사전 준비

bash

# Hugging Face CLI 로그인
huggingface-cli login

# 로그인 확인
python -c "from huggingface_hub import whoami; print(whoami()['name'])"

배포 실행

bash

python scripts/deploy_space.py --space-name hf-open-source-ai-lab

ZeroGPU 설정 (PRO 사용자)

Space 생성 후 Hugging Face 웹에서:

1.Space 설정(Settings) → Hardware → ZeroGPU 선택
2.requirements.txt에 spaces 패키지가 포함되어 있는지 확인

배포된 Space API 검증

bash

# 텍스트 생성 API만 테스트
python scripts/api_smoke_test.py --target <username>/hf-open-source-ai-lab

# 이미지 생성 API 포함 테스트
python scripts/api_smoke_test.py --target <username>/hf-open-source-ai-lab --include-image

프로젝트 구조

hf-open-source-ai-lab/
├── app.py                    # Gradio 앱 (Space 배포용)
├── requirements.txt          # 의존성 패키지
├── README.md                 # 이 파일 (Space 메타데이터 포함)
├── lecture_lab.ipynb          # 3차시 실습 노트북
├── scripts/
│   ├── check_env.py          # 환경 확인 스크립트
│   ├── local_smoke_test.py   # 로컬 스모크 테스트
│   ├── run_local_server.py   # 로컬 서버 실행
│   ├── api_smoke_test.py     # API 엔드포인트 테스트
│   └── deploy_space.py       # Space 배포 스크립트
├── docs/
│   ├── instructor_script_ko.md     # 강사 대본
│   ├── theory_slide_outline_ko.md  # 이론 강의 슬라이드 개요
│   ├── troubleshooting_ko.md       # 트러블슈팅 가이드
│   └── recording_checklist_ko.md   # 촬영 체크리스트
├── tests/
│   └── test_app.py           # 단위 테스트
├── .gitignore
├── .env.example
├── pyproject.toml
└── Makefile

모델 선택 이유

모델	선택 여부	이유
Qwen3-4B	선택 (텍스트)	최신 모델, 한국어 지원, Thinking 모드 지원, Apache 2.0
FLUX.2-dev	선택 (이미지)	최신 고품질 이미지 생성, ZeroGPU 환경에서 구동
Qwen2.5-0.5B-Instruct	미선택	구버전 모델
SD v1.5	미선택	구버전 모델, 품질 낮음

트러블슈팅

자세한 내용은 `docs/troubleshooting_ko.md`를 참조하세요.

자주 발생하는 문제:

—MPS 오류: PYTORCH_ENABLE_MPS_FALLBACK=1 python app.py
—모델 다운로드 느림: HF_HUB_ENABLE_HF_TRANSFER=1 환경변수 설정
—HF 토큰 없음: huggingface-cli login 실행
—Space 빌드 실패: requirements.txt 버전 확인

라이선스

이 실습 자료는 교육 목적으로 자유롭게 사용할 수 있습니다.

사용된 오픈소스 모델:

—Qwen3-4B (Apache 2.0)
—FLUX.2-dev (FLUX.2 Community License)