pfox1995/pest-detector-runpod

한국어 작물 해충 분류기 — RunPod 배포 번들

WizWix/kor-pest-detector LoRA 어댑터와 RunPod 컨테이너에서 빠르게 서버를 기동하기 위한 모든 배포 스크립트를 한 저장소에 묶었습니다. 파드를 자주 생성·종료하는 운영 패턴에 맞춰 설계되었습니다.

항목	값
검증 정확도 (1,535샘플)	99.48 % (출처: WizWix evaluation)
클래스 수	20 (정상 + 19종 해충)
VRAM (4-bit)	약 8.7 GB
디스크 (베이스 + 어댑터)	약 19 GB
콜드 부트 (모델 캐시 없음)	약 8 ~ 10분
웜 부트 (HF 캐시 보존 시)	약 90초

---

설계 의도

이 번들은 다음 시나리오를 위해 만들어졌습니다:

비용 절감을 위해 RunPod 파드를 자주 켜고 끄는 환경. 파드는 볼륨이 없거나, 컨테이너 디스크가 매번 초기화되는 상황.

따라서 모든 의존성·스크립트·어댑터 가중치를 이 저장소 하나로 풀어서, git clone → bash restart_server.sh 두 줄이면 어디서든 서버가 뜨도록 했습니다.

---

빠른 시작 (RunPod)

1. 파드 사양

항목	권장값
GPU	VRAM 8 GB 이상 (RTX 3060 12GB, 4070, RTX 2000 Ada 등)
컨테이너 디스크	30 GB 이상 (모델 캐시 약 19 GB + 패키지 약 4 GB)
베이스 이미지	PyTorch 2.8 + CUDA 12.8 + Python 3.12 (RunPod 공식 PyTorch 템플릿 권장)
HTTP 포트	8888 (RunPod 의 JupyterLab 기본 포트와 동일하므로 별도 추가 노출 불필요)

⚠ 포트 8888 은 RunPod 컨테이너에서 기본적으로 JupyterLab 이 점유합니다. 본 번들의 restart_server.sh 는 시작 시 JupyterLab 을 종료하고 8888 을 점유합니다. JupyterLab 이 필요하면 다른 포트로 추가 노출하세요.

2. 설치 및 기동 (한 번에)

SSH 또는 웹 터미널에서 단 한 줄:

mkdir -p /workspace/deploy && cd /workspace/deploy && \
  wget -q https://huggingface.co/pfox1995/pest-detector-runpod/resolve/main/restart_server.sh && \
  bash restart_server.sh

이 한 줄이 자동 처리합니다:

• restart_server.sh 만 먼저 받음 (5 KB)
• 스크립트가 huggingface_hub.snapshot_download 으로 나머지 번들 (어댑터 가중치 ~693 MB, 토크나이저 ~20 MB, server.py 등) 을 같은 디렉토리에 받음
• pip 설치 → 베이스 모델 다운로드 → 서버 기동

⚠ git clone 은 권장하지 않습니다. HuggingFace 의 대용량 파일은 Git LFS 를 사용하므로 일반 git clone 은 134 바이트짜리 포인터 파일 만 받아옵니다. 본 스크립트는 이 경우를 자동 감지하고 huggingface_hub 로 다시 받지만, 시간이 두 배로 듭니다. 위의 wget 한 줄이 가장 깔끔합니다.

restart_server.sh 가 자동 처리하는 단계:

단계	소요 시간	내용
1. Python 의존성 설치	~3분	unsloth, peft, fastapi, bitsandbytes, flash-linear-attention 등
2. causal_conv1d 사전빌드 wheel 설치	~30초	torch 2.8 + cu12 + py312 용
3. JupyterLab 종료 + tmux pest 세션 기동	~5초	포트 8888 점유
4. 베이스 모델 다운로드	~4 ~ 5분	unsloth/Qwen3.5-9B 약 19 GB (HF cache 미존재 시)
5. LoRA 어댑터 부착	~5초	번들 내부 파일 직접 사용 (재다운로드 없음)
6. Triton JIT 워밍업	(첫 호출 시 ~10초)	첫 /classify 호출에서만 발생

3. 동작 확인

설치가 끝나면 RunPod 가 자동으로 공개 프록시 URL 을 부여합니다:

curl https://<POD_ID>-8888.proxy.runpod.net/health
# {"status":"ok","model_loaded":true}

브라우저로 https://<POD_ID>-8888.proxy.runpod.net/ 에 접속하면 한국어 업로드 UI 가 표시됩니다.

---

매번 끄고 켜는 운영 가이드

RunPod 파드의 컨테이너를 재시작·재생성하면:

• ❌ 컨테이너 디스크가 초기화됨 (/workspace 가 볼륨이 아니면 함께 사라짐)
• ❌ 설치된 pip 패키지가 모두 사라짐
• ❌ 모델 캐시 (~/.cache/huggingface) 가 사라짐 ← 이게 콜드 부트의 가장 큰 비용

따라서 매번 위 빠른 시작 2번 절차를 다시 실행하면 됩니다 (git clone 부터).

콜드 부트 비용 줄이기 (선택)

방법	절감 효과	추가 비용
/workspace 에 RunPod 네트워크 볼륨 마운트	콜드 부트 → 약 90초	볼륨 임대료 (월 약 GB당 $0.07, 30 GB ≈ $2.1/월)
사전 빌드 Docker 이미지 사용	pip 단계 생략	이미지 빌드/유지 부담
unsloth/Qwen3.5-9B-bnb-4bit 사용	베이스 다운로드 19 GB → 5 GB	BASE_MODEL 환경변수로 변경 가능, 정확도 동일

가장 비용 대비 효과가 좋은 옵션은 베이스 모델을 4-bit 사전 양자화 버전으로 변경하는 것입니다. 콜드 부트 시간이 약 절반(8분 → 4분)으로 줄고 추가 비용도 없습니다.

---

API

서버는 FastAPI 기반이며 5개 엔드포인트를 제공합니다.

메서드	경로	설명
GET	/health	{"status":"ok","model_loaded":true}
GET	/classes	20개 클래스 목록과 개수
GET	/	브라우저용 한국어 업로드 페이지
POST	/classify	multipart file=... 업로드 → 예측 결과
POST	/classify_b64	JSON {"image":"<base64>"} → 예측 결과

응답 예시

curl -F file=@pest.jpg https://<POD_ID>-8888.proxy.runpod.net/classify
# {"pred":"검거세미밤나방","raw":"검거세미밤나방","elapsed_s":2.3}

파이썬 클라이언트 예시

import requests

resp = requests.post(
    "https://<POD_ID>-8888.proxy.runpod.net/classify",
    files={"file": open("pest.jpg", "rb")},
    timeout=60,
)
print(resp.json()["pred"])  # 한국어 클래스명

---

환경변수

bash restart_server.sh 실행 시 환경변수로 동작을 변경할 수 있습니다.

변수	기본값	설명
PORT	8888	서버 청취 포트 (RunPod 에서 외부 노출되어야 함)
ADAPTER	(자동 감지)	본 번들 디렉토리 안에 adapter_config.json 이 있으면 그 경로, 없으면 pfox1995/pest-detector-runpod HF 저장소
BASE_MODEL	unsloth/Qwen3.5-9B	베이스 VLM. 4-bit 사전 양자화 변형으로 변경하려면 unsloth/Qwen3.5-9B-bnb-4bit
LOAD_IN_4BIT	true	bnb NF4 4-bit 로 로드. false 면 FP16 (VRAM 약 19.5 GB 필요)
HF_TOKEN	(없음)	private 저장소 사용 시에만 필요
PUBLIC_URL	자동 감지	출력용 공개 URL. RunPod 의 RUNPOD_POD_ID 환경변수에서 자동 추론

# 예: FP16 로 띄우기 (VRAM 20 GB 이상 GPU)
LOAD_IN_4BIT=false bash restart_server.sh

# 예: 다른 포트로
PORT=9000 bash restart_server.sh

# 예: 다른 어댑터로 (호환되는 경우만)
ADAPTER=다른계정/다른어댑터 bash restart_server.sh

---

클래스 목록 (20개)

정상 을 포함한 20개 한국어 클래스:

정상, 검거세미밤나방, 꽃노랑총채벌레, 담배가루이, 담배거세미나방,
담배나방, 도둑나방, 먹노린재, 목화바둑명나방, 무잎벌,
배추좀나방, 배추흰나비, 벼룩잎벌레, 복숭아혹진딧물, 썩덩나무노린재,
열대거세미나방, 큰28점박이무당벌레, 톱다리개미허리노린재, 파밤나방, 홍비단노린재

/classes 엔드포인트가 항상 캐노니컬 정렬된 목록을 반환합니다 (정렬은 한글 사전순, 정상 은 클래스 어휘 안에서는 알파벳 순서대로 들어감).

---

트러블슈팅

서버가 안 뜸 / /health 가 200 안 보냄

# tmux 세션 로그 확인
tmux capture-pane -t pest -p | tail -50
# 또는
tail -100 /workspace/pest_server.log

/classify 가 adgeadge... 같은 쓰레기 텍스트를 반환

merge_and_unload() 를 호출했거나 transformers.AutoModelForImageTextToText 로 베이스를 로드한 경우 발생합니다. 반드시 unsloth.FastVisionModel.from_pretrained + peft.PeftModel.from_pretrained 런타임 훅 으로만 로드하세요. 본 번들의 server.py 는 이미 올바르게 설정되어 있습니다.

CUDA OOM

LOAD_IN_4BIT=true 로 다시 띄우세요 (기본값). 그래도 부족하면 GPU 를 더 큰 것으로 변경해야 합니다 (FP16 은 약 20 GB, 4-bit 은 약 9 GB 필요).

첫 호출이 너무 오래 걸림 (10초+)

정상입니다. Triton JIT 가 Gated DeltaNet 커널을 컴파일합니다. 두 번째 호출부터는 약 2초입니다. JIT 캐시는 컨테이너 재시작 시 사라집니다.

causal_conv1d 빌드 실패

사전 빌드된 wheel 이 있으니 restart_server.sh 에서 자동 설치합니다. 만약 직접 빌드하면 9개 GPU 아키텍처 컴파일로 OOM 이 발생합니다.

---

GGUF / Ollama / llama.cpp 로 배포 불가

본 어댑터는 Qwen3.5 의 Gated DeltaNet 모듈 (linear_attn.in_proj_*) 을 학습 대상으로 포함합니다. convert_hf_to_gguf.py 의 V-row 순열이 LoRA 델타와 호환되지 않아, GGUF 변환 후 출력이 토큰 붕괴 (adgeadge...) 됩니다.

상세 원인 분석은 llama.cpp#21125 참고. 본 번들은 PEFT 런타임 훅 방식만 사용합니다.

---

출처 및 라이선스

구성	출처	라이선스
LoRA 어댑터 가중치	WizWix/kor-pest-detector	Apache-2.0 (베이스 모델 기준)
베이스 VLM	unsloth/Qwen3.5-9B	Apache-2.0
학습 데이터셋	Himedia-AI-01/pest-detection-korean	데이터셋 페이지 약관 따름
배포 스크립트 (server.py, inference.py, restart_server.sh, requirements.txt)	본 저장소 작성자 (@pfox1995)	MIT

본 저장소는 학습 자체는 WizWix 가 수행한 어댑터를 RunPod 배포에 최적화하여 재포장한 번들입니다. 어댑터 자체에 대한 학습 세부 정보·평가 메트릭·confusion matrix 등은 WizWix/kor-pest-detector 의 evaluation 디렉토리를 참고하세요.

---

변경 이력

• v1.0 (최초): WizWix/kor-pest-detector v(time of bundling) + RunPod 배포 스크립트 번들