jeonghyo.k
3946ff6a25
- prediction/image/ FastAPI 서버 Docker 환경 구성 - Dockerfile: PyTorch 2.1 + CUDA 12.1 기반 GPU 이미지 - docker-compose.yml: GPU 할당 + 데이터 볼륨 마운트 - requirements.txt: 서버 의존성 목록 - .env.example: 환경변수 템플릿 - DOCKER_USAGE.md: 빌드/실행/API 사용법 문서 - Dockerfile에 .dockerignore 제외 폴더 mkdir -p 추가 - .gitignore: prediction/image 결과물 및 모델 가중치(.pth) 제외 추가 - dbInsert_csv.py, dbInsert_shp.py 삭제 (미사용 DB 로직) - api.py: dbInsert import 및 주석 처리된 DB 호출 코드 제거 - aerialRouter.ts: req.params 타입 오류 수정
300 lines
8.0 KiB
Markdown
300 lines
8.0 KiB
Markdown
# wing-image-analysis Docker 사용 가이드
|
|
|
|
드론 영상 기반 유류 오염 분석 FastAPI 서버를 Docker 컨테이너로 빌드하고 실행하는 방법을 설명한다.
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [사전 요구사항](#1-사전-요구사항)
|
|
2. [빠른 시작](#2-빠른-시작)
|
|
3. [빌드 명령어](#3-빌드-명령어)
|
|
4. [실행 명령어](#4-실행-명령어)
|
|
5. [환경변수 설정](#5-환경변수-설정)
|
|
6. [볼륨 구조](#6-볼륨-구조)
|
|
7. [API 엔드포인트 사용 예시](#7-api-엔드포인트-사용-예시)
|
|
8. [로그 확인 및 디버깅](#8-로그-확인-및-디버깅)
|
|
9. [컨테이너 관리](#9-컨테이너-관리)
|
|
10. [주의사항](#10-주의사항)
|
|
|
|
---
|
|
|
|
## 1. 사전 요구사항
|
|
|
|
| 항목 | 최소 버전 | 확인 명령어 |
|
|
|------|----------|-------------|
|
|
| Docker Engine | 24.0 이상 | `docker --version` |
|
|
| Docker Compose | 2.20 이상 | `docker compose version` |
|
|
| NVIDIA 드라이버 | 525 이상 (CUDA 12.1 지원) | `nvidia-smi` |
|
|
| nvidia-container-toolkit | 최신 | `nvidia-ctk --version` |
|
|
|
|
### nvidia-container-toolkit 설치 (Ubuntu 기준)
|
|
|
|
```bash
|
|
# GPG 키 및 저장소 추가
|
|
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
|
|
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
|
|
|
|
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
|
|
| sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
|
|
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
|
|
|
|
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
|
|
|
|
# Docker 런타임 설정 및 재시작
|
|
sudo nvidia-ctk runtime configure --runtime=docker
|
|
sudo systemctl restart docker
|
|
```
|
|
|
|
### GPU 동작 확인
|
|
|
|
```bash
|
|
docker run --rm --gpus all nvidia/cuda:12.1-base-ubuntu22.04 nvidia-smi
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 빠른 시작
|
|
|
|
```bash
|
|
# 1. prediction/image/ 디렉토리로 이동
|
|
cd prediction/image
|
|
|
|
# 2. 환경변수 파일 준비 (필요 시)
|
|
cp .env.example .env
|
|
|
|
# 3. 빌드 + 실행 (백그라운드)
|
|
docker compose up -d --build
|
|
|
|
# 4. 서버 상태 확인
|
|
curl http://localhost:5001/docs
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 빌드 명령어
|
|
|
|
### docker compose (권장)
|
|
|
|
```bash
|
|
# 이미지 빌드만 수행 (실행 안 함)
|
|
docker compose build
|
|
|
|
# 빌드 로그를 상세하게 출력
|
|
docker compose build --progress=plain
|
|
|
|
# 캐시 없이 처음부터 빌드 (의존성 변경 시)
|
|
docker compose build --no-cache
|
|
```
|
|
|
|
### docker build (단독)
|
|
|
|
```bash
|
|
# prediction/image/ 디렉토리에서 실행
|
|
docker build -t wing-image-analysis:latest .
|
|
|
|
# 빌드 태그 지정
|
|
docker build -t wing-image-analysis:1.0.0 .
|
|
|
|
# 캐시 없이 빌드
|
|
docker build --no-cache -t wing-image-analysis:latest .
|
|
```
|
|
|
|
> **참고**: 첫 빌드는 PyTorch base 이미지(약 8GB) + GDAL/Python 패키지 설치로 **30~60분** 소요될 수 있다.
|
|
> 이후 빌드는 레이어 캐시로 수 분 내 완료된다.
|
|
|
|
---
|
|
|
|
## 4. 실행 명령어
|
|
|
|
### docker compose (권장)
|
|
|
|
```bash
|
|
# 백그라운드 실행
|
|
docker compose up -d
|
|
|
|
# 빌드 후 즉시 실행
|
|
docker compose up -d --build
|
|
|
|
# 포그라운드 실행 (로그 바로 출력)
|
|
docker compose up
|
|
|
|
# 중지
|
|
docker compose down
|
|
|
|
# 중지 + 볼륨 삭제 (데이터 초기화 시)
|
|
docker compose down -v
|
|
```
|
|
|
|
### docker run (단독 — 테스트용)
|
|
|
|
```bash
|
|
docker run --rm \
|
|
--gpus all \
|
|
-p 5001:5001 \
|
|
--env-file .env \
|
|
-v "$(pwd)/mx15hdi/Metadata/Image/Original_Images:/app/mx15hdi/Metadata/Image/Original_Images" \
|
|
wing-image-analysis:latest
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 환경변수 설정
|
|
|
|
`.env.example`을 복사하여 `.env`를 생성한다.
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
| 변수 | 설명 | 기본값 |
|
|
|------|------|--------|
|
|
| `API_HOST` | 서버 바인드 주소 | `0.0.0.0` |
|
|
| `API_PORT` | 서버 포트 | `5001` |
|
|
|
|
---
|
|
|
|
## 6. 볼륨 구조
|
|
|
|
컨테이너 내부 경로와 호스트 경로의 매핑이다. 이미지/결과 데이터는 컨테이너 외부에 저장되어 컨테이너를 재시작해도 유지된다.
|
|
|
|
```
|
|
호스트 (prediction/image/) 컨테이너 (/app/)
|
|
─────────────────────────────────────────────────────────────────────
|
|
mx15hdi/Metadata/Image/Original_Images/ → mx15hdi/Metadata/Image/Original_Images/ ← 원본 이미지 입력
|
|
mx15hdi/Metadata/CSV/ → mx15hdi/Metadata/CSV/ ← 메타데이터 출력
|
|
mx15hdi/Georeference/Tif/ → mx15hdi/Georeference/Tif/ ← GeoTIFF 출력
|
|
mx15hdi/Georeference/Mask_Tif/ → mx15hdi/Georeference/Mask_Tif/ ← 마스크 GeoTIFF
|
|
mx15hdi/Polygon/Shp/ → mx15hdi/Polygon/Shp/ ← Shapefile 출력
|
|
mx15hdi/Detect/result/ → mx15hdi/Detect/result/ ← 블렌딩 결과
|
|
mx15hdi/Detect/Mask_result/ → mx15hdi/Detect/Mask_result/ ← 마스크 결과
|
|
starsafire/Metadata/Image/Original_Images → starsafire/Metadata/Image/Original_Images ← 열화상 입력
|
|
starsafire/{기타}/ → starsafire/{기타}/ ← 열화상 출력
|
|
stitch/ → stitch/ ← 스티칭 결과
|
|
```
|
|
|
|
---
|
|
|
|
## 7. API 엔드포인트 사용 예시
|
|
|
|
서버 기동 후 `http://localhost:5001/docs`에서 Swagger UI로 전체 API를 확인할 수 있다.
|
|
|
|
### 7.1 전체 분석 파이프라인 실행
|
|
|
|
```bash
|
|
curl -X POST http://localhost:5001/run-script/ \
|
|
-F "files=@/path/to/drone_image.jpg" \
|
|
-F "camTy=mx15hdi" \
|
|
-F "fileId=20240310_001"
|
|
```
|
|
|
|
**응답 예시**:
|
|
```json
|
|
{
|
|
"meta": "drone_image.jpg,37,30,0,126,55,0,...",
|
|
"data": [
|
|
{
|
|
"classId": 2,
|
|
"area": 1234.56,
|
|
"volume": 0.1234,
|
|
"note": "갈색",
|
|
"thickness": 0.0001,
|
|
"wkt": "POLYGON((...))"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 7.2 메타데이터 조회
|
|
|
|
```bash
|
|
curl http://localhost:5001/get-metadata/mx15hdi/20240310_001
|
|
```
|
|
|
|
### 7.3 원본 이미지 조회 (Base64)
|
|
|
|
```bash
|
|
curl http://localhost:5001/get-original-image/mx15hdi/20240310_001
|
|
```
|
|
|
|
### 7.4 GeoTIFF + 좌표 조회
|
|
|
|
```bash
|
|
curl http://localhost:5001/get-image/mx15hdi/20240310_001
|
|
```
|
|
|
|
### 7.5 이미지 스티칭
|
|
|
|
```bash
|
|
curl -X POST http://localhost:5001/stitch \
|
|
-F "files=@photo1.jpg" \
|
|
-F "files=@photo2.jpg" \
|
|
-F "mode=drone"
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 로그 확인 및 디버깅
|
|
|
|
```bash
|
|
# 실시간 로그 출력
|
|
docker logs wing-image-analysis -f
|
|
|
|
# 최근 100줄만 출력
|
|
docker logs wing-image-analysis --tail 100
|
|
|
|
# 컨테이너 내부 쉘 접속
|
|
docker exec -it wing-image-analysis bash
|
|
|
|
# GPU 사용 현황 확인 (컨테이너 내부)
|
|
docker exec wing-image-analysis nvidia-smi
|
|
|
|
# Python 패키지 목록 확인
|
|
docker exec wing-image-analysis pip list
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 컨테이너 관리
|
|
|
|
```bash
|
|
# 상태 확인
|
|
docker compose ps
|
|
|
|
# 재시작
|
|
docker compose restart
|
|
|
|
# 중지 (볼륨 유지)
|
|
docker compose down
|
|
|
|
# 이미지 삭제
|
|
docker rmi wing-image-analysis:latest
|
|
|
|
# 사용하지 않는 리소스 정리
|
|
docker system prune -f
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 주의사항
|
|
|
|
### GPU 필수
|
|
- AI 모델(`epoch_165.pth`)은 `cuda:0` 디바이스로 로드된다.
|
|
- GPU 없이 실행하면 서버 기동 시 오류가 발생한다.
|
|
- CPU 전용 환경에서 테스트하려면 `Inference.py`의 `device='cuda:0'`을 `device='cpu'`로 수정해야 한다.
|
|
|
|
### 첫 기동 시간
|
|
- AI 모델 로드: 약 **10~30초** 소요 (GPU 메모리에 로딩)
|
|
- 준비 완료 후 로그에 `Application startup complete` 메시지가 출력된다.
|
|
|
|
### workers=1 고정
|
|
- GPU 모델은 프로세스 간 공유가 불가하므로 uvicorn workers는 반드시 `1`로 유지해야 한다.
|
|
- 병렬 처리는 내부 `ThreadPoolExecutor`(max_workers=4)로 처리된다.
|
|
|
|
### 포트 충돌
|
|
- 기본 포트 `5001`이 다른 서비스와 충돌하면 `docker-compose.yml`의 `ports` 항목을 수정한다:
|
|
```yaml
|
|
ports:
|
|
- "5002:5001" # 호스트 5002 → 컨테이너 5001
|
|
```
|