jeonghyo.k 54d3a281c6 feat(prediction): CPU 전용 Docker 환경 구축 + 이미지 분석/보고서/항공 UI 개선

2026-03-11 17:30:25 +09:00

9.8 KiB

Raw Blame 히스토리

wing-image-analysis Docker 사용 가이드

드론 영상 기반 유류 오염 분석 FastAPI 서버를 Docker 컨테이너로 빌드하고 실행하는 방법을 설명한다.

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 기준)

# 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 동작 확인

docker run --rm --gpus all nvidia/cuda:12.1-base-ubuntu22.04 nvidia-smi

2. 빠른 시작

# 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 (권장)

# 이미지 빌드만 수행 (실행 안 함)
docker compose build

# 빌드 로그를 상세하게 출력
docker compose build --progress=plain

# 캐시 없이 처음부터 빌드 (의존성 변경 시)
docker compose build --no-cache

docker build (단독)

# 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 (권장)

# 백그라운드 실행
docker compose up -d

# 빌드 후 즉시 실행
docker compose up -d --build

# 포그라운드 실행 (로그 바로 출력)
docker compose up

# 중지
docker compose down

# 중지 + 볼륨 삭제 (데이터 초기화 시)
docker compose down -v

docker run (단독 — 테스트용)

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를 생성한다.

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 전체 분석 파이프라인 실행

curl -X POST http://localhost:5001/run-script/ \
  -F "files=@/path/to/drone_image.jpg" \
  -F "camTy=mx15hdi" \
  -F "fileId=20240310_001"

응답 예시:

{
  "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 메타데이터 조회

curl http://localhost:5001/get-metadata/mx15hdi/20240310_001

7.3 원본 이미지 조회 (Base64)

curl http://localhost:5001/get-original-image/mx15hdi/20240310_001

7.4 GeoTIFF + 좌표 조회

curl http://localhost:5001/get-image/mx15hdi/20240310_001

7.5 이미지 스티칭

curl -X POST http://localhost:5001/stitch \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.jpg" \
  -F "mode=drone"

8. 로그 확인 및 디버깅

# 실시간 로그 출력
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. 컨테이너 관리

# 상태 확인
docker compose ps

# 재시작
docker compose restart

# 중지 (볼륨 유지)
docker compose down

# 이미지 삭제
docker rmi wing-image-analysis:latest

# 사용하지 않는 리소스 정리
docker system prune -f

10. 주의사항

GPU 자동 감지

서버 기동 시 torch.cuda.is_available()로 GPU 유무를 자동 감지한다.
GPU가 있으면 cuda:0, 없으면 cpu로 자동 폴백된다.
환경변수 DEVICE로 device를 명시 지정할 수 있다 (예: DEVICE=cpu, DEVICE=cuda:1).

첫 기동 시간

AI 모델 로드: 약 10~30초 소요 (GPU 메모리에 로딩)
준비 완료 후 로그에 Application startup complete 메시지가 출력된다.

workers=1 고정

GPU 모델은 프로세스 간 공유가 불가하므로 uvicorn workers는 반드시 1로 유지해야 한다.
병렬 처리는 내부 ThreadPoolExecutor(max_workers=4)로 처리된다.

포트 충돌

기본 포트 5001이 다른 서비스와 충돌하면 docker-compose.yml의 ports 항목을 수정한다:
```
ports:
  - "5002:5001"  # 호스트 5002 → 컨테이너 5001
```

11. CPU 전용 환경 실행

GPU(NVIDIA)가 없는 환경에서는 CPU 전용 설정을 사용한다.

사전 요구사항 (CPU 모드)

항목	최소 버전	확인 명령어
Docker Engine	24.0 이상	`docker --version`
Docker Compose	2.20 이상	`docker compose version`
NVIDIA 드라이버	불필요	—

빠른 시작 (CPU)

# prediction/image/ 디렉토리로 이동
cd prediction/image

# 환경변수 파일 준비 (필요 시)
cp .env.example .env

# CPU 이미지 빌드 + 실행
docker compose -f docker-compose.cpu.yml up -d --build

# 서버 상태 확인
curl http://localhost:5001/docs

빌드 명령어 (CPU)

# CPU 이미지만 빌드
docker compose -f docker-compose.cpu.yml build

# 캐시 없이 빌드
docker compose -f docker-compose.cpu.yml build --no-cache

참고: CPU 기반 PyTorch 이미지는 GPU 이미지(~8GB) 대비 약 70% 용량이 절감된다. 단, CPU 추론은 GPU 대비 처리 속도가 느리므로 대용량 이미지 분석 시 시간이 더 소요된다.

실행 명령어 (CPU)

# 백그라운드 실행
docker compose -f docker-compose.cpu.yml up -d

# 포그라운드 실행 (로그 바로 출력)
docker compose -f docker-compose.cpu.yml up

# 중지
docker compose -f docker-compose.cpu.yml down

로컬 직접 실행 (Docker 없이)

# GPU 있으면 자동으로 cuda:0 사용, 없으면 cpu로 폴백
python api.py

# device 강제 지정
DEVICE=cpu python api.py
DEVICE=cuda:1 python api.py

GPU/CPU 모드 확인

서버 기동 로그에서 사용 device를 확인할 수 있다:

[Inference] 사용 device: cpu      ← CPU 모드
[Inference] 사용 device: cuda:0   ← GPU 모드

9.8 KiB Raw Blame 히스토리

wing-image-analysis Docker 사용 가이드

목차

1. 사전 요구사항

nvidia-container-toolkit 설치 (Ubuntu 기준)

GPU 동작 확인

2. 빠른 시작

3. 빌드 명령어

docker compose (권장)

docker build (단독)

4. 실행 명령어

docker compose (권장)

docker run (단독 — 테스트용)

5. 환경변수 설정

6. 볼륨 구조

7. API 엔드포인트 사용 예시

7.1 전체 분석 파이프라인 실행

7.2 메타데이터 조회

7.3 원본 이미지 조회 (Base64)

7.4 GeoTIFF + 좌표 조회

7.5 이미지 스티칭

8. 로그 확인 및 디버깅

9. 컨테이너 관리

10. 주의사항

GPU 자동 감지

첫 기동 시간

workers=1 고정

포트 충돌

11. CPU 전용 환경 실행

사전 요구사항 (CPU 모드)

빠른 시작 (CPU)

빌드 명령어 (CPU)

실행 명령어 (CPU)

로컬 직접 실행 (Docker 없이)

GPU/CPU 모드 확인

9.8 KiB

Raw Blame 히스토리