hf_processor_vscode/README.md

Hugging Face Processor Practice

이 프로젝트는 Hugging Face Tokenizer, ImageProcessor, Processor 실습 코드를 VS Code에서 실행하기 좋게 정리한 예제입니다.

참고 페이지: https://ds31x.github.io/wiki/hf/hf_processor/

구성

hf_processor_vscode/
├── README.md
├── requirements.txt
├── pyproject.toml
├── scripts/
│   ├── 00_check_environment.py
│   ├── 01_tokenizer.py
│   ├── 02_image_processor.py
│   ├── 03_processor_clip.py
│   ├── 04_custom_image_processor_roundtrip.py
│   └── run_all.py
├── src/
│   └── hf_processor_practice/
│       ├── image_processing_simple_vision.py
│       └── utils.py
├── notebooks/
│   └── hf_processor_practice.ipynb
├── reports/
│   ├── result_analysis.md
│   └── agent_log.md
├── data/
└── outputs/

환경 만들기

방법 1: venv

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

pip install -U pip
pip install -r requirements.txt
pip install -e .

방법 2: conda

conda create -n hfprocessor python=3.11 -y
conda activate hfprocessor
pip install -r requirements.txt
pip install -e .

실행 방법

전체 실행:

python scripts/run_all.py

개별 실행:

python scripts/00_check_environment.py
python scripts/01_tokenizer.py
python scripts/02_image_processor.py
python scripts/03_processor_clip.py
python scripts/04_custom_image_processor_roundtrip.py

인터넷이 없을 때

기본적으로는 Hugging Face Hub에서 bert-base-uncased, google/vit-base-patch16-224, openai/clip-vit-base-patch32를 불러오려고 시도합니다.

인터넷이 없거나 모델 다운로드가 실패하면 다음 fallback이 자동으로 동작합니다.

• Tokenizer: 로컬 tiny BERT tokenizer 생성
• ImageProcessor: 로컬 ViTImageProcessor 생성
• Processor: 로컬 CLIPProcessor 구성
• 이미지 파일: 다운로드 실패 시 placeholder 이미지 생성

오프라인 모드로 명확히 실행하려면:

# macOS/Linux
TRANSFORMERS_OFFLINE=1 HF_HUB_OFFLINE=1 python scripts/run_all.py

# Windows PowerShell
$env:TRANSFORMERS_OFFLINE="1"
$env:HF_HUB_OFFLINE="1"
python scripts/run_all.py

실습 내용

01. Tokenizer

• AutoTokenizer.from_pretrained() 사용
• 문장을 input_ids, token_type_ids, attention_mask로 변환
• batch_decode()로 토큰화 결과 확인
• save_pretrained() / from_pretrained() 저장 및 복원

02. ImageProcessor

• AutoImageProcessor.from_pretrained() 사용
• PIL 이미지를 pixel_values 텐서로 변환
• 출력 shape 확인: 일반적으로 (batch, channel, height, width)
• preprocessor_config.json 저장 및 복원

03. Processor / CLIP

• AutoProcessor 또는 CLIPProcessor 사용
• 텍스트와 이미지를 동시에 전처리
• 출력 key: pixel_values, input_ids, attention_mask 등
• Processor 저장 및 복원

04. Custom ImageProcessor

• ImageProcessingMixin 기반 커스텀 이미지 프로세서 구현
• resize, normalize, tensor 변환 수행
• save_pretrained() / from_pretrained() round-trip 확인
• 환경에 따라 AutoImageProcessor(..., trust_remote_code=True) 로드도 시도

테스트 메모

이 프로젝트는 다음을 확인했습니다.

• 모든 .py 파일 문법 검사 통과
• 인터넷이 없는 환경에서 fallback 모드로 python scripts/run_all.py 실행 성공
• 테스트 로그: outputs/logs/run_all_test.log

일부 환경, 특히 Python 3.13 + torchvision 조합에서는 torchvision::nms 관련 오류가 날 수 있습니다. 그런 경우 Python 3.10 또는 3.11 환경을 권장합니다.