hf_processor_vscode/README.md

# Hugging Face Processor Practice

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

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

## 구성

```text
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

```bash
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

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

## 실행 방법

전체 실행:

```bash
python scripts/run_all.py
```

개별 실행:

```bash
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 이미지 생성

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

```bash
# 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 환경을 권장합니다.