서울시 AI 기반 포트홀 위험 예측 및 신고 플랫폼의 AI 서버 (FastAPI).
서울시 도로의 포트홀 보수 이력, 강우량, 교통량, 도로굴착 정보, 시민 신고 사진을 AI로 분석해 포트홀 위험 구간을 예측하고, 신고 판별 · 관할 안내 · 보수 우선순위 추천을 자동화한다.
상세 문서는 docs/ 폴더에 있다.
| 문서 | 내용 |
|---|---|
| docs/overview.md | 프로젝트 개요, 문제 정의, 핵심 아이디어 |
| docs/architecture.md | 폴더 구조, 레이어 책임, 기술 스택 |
| docs/api.md | API 엔드포인트 명세 (현재 / 계획) |
| docs/risk-score.md | 위험 점수 산식과 가중치 |
| docs/data-sources.md | 활용 공공데이터 목록 · 링크 · 사용 목적 |
| docs/deployment.md | 로컬 실행, Docker, 환경변수 |
| docs/roadmap.md | MVP 범위, 개발 순서, 차별점 |
| 기능 | 설명 | 엔드포인트 |
|---|---|---|
| 포트홀 위험지도 | 서울시 도로별 위험 점수 조회 | GET /api/v1/risk/zones |
| 위험 점수 조회 | 좌표 기준 위험 점수 | GET /api/v1/risk/score |
| 시민 신고 | 사진 + 위치 업로드 | POST /api/v1/reports |
| AI 사진 판별 | 신고 사진의 포트홀 여부 판별 | POST /api/v1/images/classify |
| 관할기관 안내 | 위치 기준 담당 기관 조회 | GET /api/v1/jurisdiction |
| 관리자 대시보드 | 보수 우선순위 정렬 | GET /api/v1/admin/priorities |
AI-server/
├── app/ # FastAPI 애플리케이션
│ ├── main.py # 진입점, 라우터 등록
│ ├── config.py # 환경설정 (pydantic-settings)
│ ├── api/ # HTTP 엔드포인트
│ │ ├── router.py # api_router 집계
│ │ ├── health.py # 헬스체크
│ │ ├── risk.py # 위험지도/점수
│ │ ├── reports.py # 시민 신고
│ │ ├── images.py # AI 이미지 판별
│ │ ├── admin.py # 관리자 대시보드
│ │ └── jurisdiction.py # 관할기관 안내
│ ├── schemas/ # Pydantic 요청/응답 모델
│ │ ├── common.py # Location 등 공통 타입
│ │ ├── risk.py
│ │ ├── report.py
│ │ ├── image.py
│ │ └── admin.py
│ ├── services/ # 비즈니스 로직
│ │ ├── risk_service.py # 위험 점수 산식
│ │ ├── report_service.py # 신고 처리
│ │ ├── image_service.py # 이미지 추론 호출
│ │ ├── jurisdiction_service.py
│ │ └── storage_service.py # 업로드 파일 저장
│ ├── ml/ # ML 모델 래퍼
│ │ ├── risk_model.py # XGBoost/RandomForest 추론
│ │ ├── pothole_detector.py # YOLO 추론
│ │ └── features.py # 피처 엔지니어링
│ ├── data_sources/ # 서울시 공공데이터 클라이언트
│ │ ├── seoul_open_api.py
│ │ └── loaders.py
│ └── core/ # 로깅 · 예외 등 공통
│ ├── logging.py
│ └── exceptions.py
├── data/ # 데이터 저장소 (gitignored)
│ ├── raw/ # 공공데이터 원본
│ ├── processed/ # 전처리 결과
│ └── uploads/ # 시민 신고 사진
├── models/ # 학습된 ML 모델 파일 (gitignored)
├── notebooks/ # 분석 · 실험 노트북
├── scripts/ # 데이터 수집 / 학습 스크립트
│ ├── fetch_pothole_history.py
│ ├── fetch_rainfall.py
│ ├── fetch_traffic.py
│ └── train_risk_model.py
├── tests/ # pytest
│ ├── test_health.py
│ ├── test_risk.py
│ ├── test_reports.py
│ └── test_images.py
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.md
| 항목 | 비중 |
|---|---|
| 과거 포트홀 발생 이력 | 35% |
| 최근 72시간 강우량 | 25% |
| 교통량 | 15% |
| 도로굴착 공사 여부 | 15% |
| 하수관거 취약도 | 10% |
# 의존성 설치
uv sync
# 환경변수 설정
cp .env.example .env
# 개발 서버
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
# 테스트
uv run pytest서버 실행 후 http://localhost:8001/docs 에서 Swagger UI 확인.
- Framework: FastAPI, Uvicorn
- AI 모델: RandomForest / XGBoost (위험 예측), YOLO (이미지 판별)
- 데이터: pandas, numpy
- 검증: pydantic v2
- 테스트: pytest, httpx