## 소개
해상운임 머신러닝 수업을 준비하다 보니, 예측 모델의 점수만 확인하는 실습은 어딘가 빠져 있다는 생각이 들었습니다. 결측과 중복을 어떻게 걸러낼지, 예측 당시에는 알 수 없던 정보가 섞이지 않았는지, 나온 숫자를 물류 업무의 언어로 어떻게 설명할지까지 다뤄야 했습니다.
이번에는 모델 하나를 더 만드는 대신 교육생이 혼자 시작해 결과를 해석하는 지점까지 따라갈 수 있는 학습 흐름을 만들었습니다. 2025년 1년치 교육용 합성 해상운임 데이터로 10단계 Google Colab 실습을 구성하고, 노트북·CSV·가이드를 한곳에서 받을 수 있는 정적 학습 포털도 Vercel에 배포했습니다.
- 배포 페이지: https://ocean-freight-ml-colab-lab.vercel.app/
- 대상: Python과 Colab 기초가 있는 물류·SCM 교육생
- 난이도와 시간: 초급~중급, 약 5시간 35분
[이미지 1 삽입: 배포 페이지 첫 화면. 대체텍스트: 해상운임 ML 10단계 Colab 실습 메인 화면]
## 진행 방법
### 1. 모델링보다 앞에 놓아야 할 것부터 정했습니다
교육생이 곧바로 모델링부터 시작하지 않도록 순서를 잡았습니다.
- 1~3단계: 문제와 스키마 이해, 데이터 품질 진단, EDA와 파생변수
- 4~6단계: 데이터 누출 실험, 시간순 70/15/15 분할, 업무 중앙값 기준선
- 7~8단계: Ridge·Random Forest 비교, 5개 운임 시나리오의 조건부 추정
- 9~10단계: 3일 이상 선적 지연 분류, B/L OCR 검증과 통관보류 분류
원본은 1,669행×23열입니다. 모든 값은 난수시드 20260722로 만든 교육용 가상 데이터이며 실제 회사·고객·선사·계약을 나타내지 않습니다. 실제 견적, 투자, 계약, 통관 판정에도 사용할 수 없습니다.
[이미지 2 삽입: 10단계 학습 로드맵. 대체텍스트: 데이터 진단부터 통관보류까지 이어지는 10단계 카드]
### 2. 도구마다 역할을 나눴습니다
- AI 코딩 에이전트: 요구사항 정리, Python·HTML 코드 초안, 반복 검토
- Python, pandas, NumPy: 교육용 합성 데이터와 10개 CSV 생성
- scikit-learn, Matplotlib: 기준선·Ridge·Random Forest·MLP 실습과 시각화
- Google Colab: 교육생이 별도 설치 없이 실행하는 실습 환경
- HTML, CSS, Vanilla JavaScript: 안내와 다운로드를 맡는 정적 사이트
- Vercel: 정적 사이트와 공개 파일 배포
아래 내용은 당시 대화 로그를 그대로 옮긴 프롬프트가 아닙니다. 같은 결과를 다시 만들 수 있게 핵심 요구사항을 한 번에 정리한 재현용 프롬프트입니다.
```text
해상운임 머신러닝 교육생용 Google Colab 실습 패키지를 설계해줘.
조건
- 2025년 1년치 교육용 합성 데이터, 난수시드 20260722
- 데이터 이해→품질→EDA→누출→시간순 분할→기준선→회귀→시나리오→지연 분류→통관·OCR의 10단계
- 교육생용 노트북에는 TODO를 두고, 강사용 정답 노트북과 분리
- 같은 날짜가 서로 다른 구간에 걸치지 않는 시간순 70/15/15 분할
- 견적 시점 이후 정보와 목표 파생 컬럼은 누출 블랙리스트로 관리
- Validation에서 기준선, Ridge, Random Forest를 비교한 뒤 모델을 고정하고 Test는 마지막에 1회만 평가
- MLP는 선택 실습으로 두되 작은 표 데이터에서 우위가 보장된다고 쓰지 않기
- 회귀는 MAPE·RMSE·R²·WAPE, 분류는 Precision·Recall·F1·PR-AUC·혼동행렬로 평가
- 결과는 관찰·한계·행동의 3문장으로 보고
- 교육생용 ZIP, PDF 가이드, 데이터사전, 과정개요, 루브릭, requirements, SHA-256 체크섬 생성
- 강사용 정답과 내부 검증자료는 공개 패키지에서 제외
```
배포 페이지의 요구사항은 이렇게 묶었습니다.
```text
위 Colab 실습을 교육생이 혼자 시작할 수 있는 정적 배포 페이지를 만들어줘.
첫 화면에서 교육생용 노트북을 바로 받고 Colab을 열 수 있게 하고,
시작 방법→10단계 로드맵→Test 1회 원칙→딥러닝 선택 실습→결과 해석→다운로드→FAQ 순서로 구성해줘.
모바일 대응, 키보드 포커스, 이미지 대체텍스트, 모션 감소 설정을 반영하고,
모든 자료가 교육용 가상 데이터라는 주의문을 눈에 띄게 표시해줘.
```
### 3. 데이터와 노트북도 다시 만들 수 있게 했습니다
build_practice_data.py는 10개 실습 CSV를 만들고, build_colab_notebooks.py는 교육생용 노트북과 정답 포함 노트북을 생성합니다. 교육생용에는 10단계 TODO를 넣었습니다. 앞 셀을 건너뛰면 마지막 Checks 셀이 빠진 변수를 알려주며, 미완성 상태에서는 최종 보고서를 만들지 않습니다.
Colab이 데이터 폴더를 찾지 못할 때는 전체 ZIP을 압축하지 않은 채 업로드하면 됩니다. Setup 셀이 자동으로 압축을 풉니다. 파일 경로 하나 때문에 실습이 멈추는 일을 줄이려고 넣은 장치입니다.
### 4. 제가 가장 강조한 문장은 “Test는 딱 1회”였습니다
좋은 점수보다 믿을 수 있는 점수가 먼저였습니다.
```python
assert LEAKAGE_BLACKLIST.isdisjoint(FEATURES)
assert train[date_column].max() < valid[date_column].min() < test[date_column].min()
# 모델과 규칙은 Validation에서 확정하고 Test는 마지막에 한 번만 평가
```
무작위 분할과 시간순 분할을 비교하고, ML이 이겨야 할 업무 중앙값 기준선부터 만듭니다. 지연과 통관보류처럼 양성이 적은 문제는 정확도만 보지 않았습니다. Recall, PR-AUC, 혼동행렬과 FN/FP의 업무 비용을 함께 읽도록 했습니다.
5개 운임 시나리오는 인과효과가 아닌, 학습 데이터의 관계에 따른 조건부 추정입니다. HS코드 역시 확정 판정이 아니라 전문가가 확인할 후보로만 다뤘습니다.
[이미지 3 삽입: Train→Validation→Lock→Test×1 흐름. 대체텍스트: 모델 선택 후 Test를 한 번만 평가하는 절차]
### 5. 흩어진 실습 자료를 다운로드 허브로 묶었습니다
사이트는 별도 백엔드나 API가 없는 단일 HTML·CSS·JavaScript 기반의 정적 페이지입니다. 교육생용 노트북, 10개 CSV, 약 1.35MB의 전체 ZIP, A4 9쪽 가이드, 데이터사전, 과정개요, 루브릭, 패키지 목록과 SHA-256 체크섬을 공개했습니다. 강사용 정답과 내부 검증자료는 공개 자산에서 뺐습니다.
배포한 뒤에는 홈페이지와 노트북·ZIP·PDF·CSV의 주요 다운로드 링크가 모두 HTTP 200으로 응답하는지 확인했습니다.
[이미지 4 삽입: 다운로드 센터. 대체텍스트: 노트북, ZIP, PDF, 데이터사전 다운로드 카드]
## 결과와 배운 점
완성된 결과물은 실시간 해상운임 예측 서비스가 아니라 교육생용 정적 학습 포털입니다. 교육생은 한 페이지에서 실습의 전체 흐름을 읽고, 필요한 파일을 받은 뒤 Colab에서 순서대로 실행할 수 있습니다.
가장 크게 배운 점은 교육 자료의 완성도가 모델 코드만으로 결정되지 않는다는 사실입니다. 실행 순서와 파일명, 업로드 방법, 오류 안내, 공개·비공개 자료 구분, 데이터 사용 제한까지 챙겨야 교육생이 혼자 끝까지 따라갈 수 있었습니다.
모델보다 실행 흐름을 더 많이 손봤습니다.
- 데이터 폴더를 찾지 못하면 ZIP을 그대로 업로드하고 Setup 셀이 압축을 풀게 했습니다.
- 앞 셀을 건너뛰면 Checks 셀이 미완료 TODO와 변수를 알려주고 보고서 생성을 멈춥니다.
- Validation에서 결정을 마친 뒤 Test를 1회만 여는 흐름을 페이지와 노트북에 함께 표시했습니다.
- 공개 파일은 영문 이름으로 제공하고 CSV는 UTF-8-SIG로 저장해 한글 환경의 호환 문제를 줄였습니다.
- 강사용 정답과 내부 검증자료는 공개 패키지에서 분리했습니다.
또 하나의 교훈도 얻었습니다. 성능이 지나치게 좋다면 새 알고리즘을 칭찬하기 전에 데이터 누출부터 의심해야 합니다. 실제 업무에서는 예측 시점과 검증 방법을 지키는 일이 최신 알고리즘보다 중요할 수 있습니다. 작은 표 데이터에서 딥러닝이 늘 앞서는 것도 아니어서, MLP는 구조와 학습곡선을 이해하는 선택 실습으로 두었습니다.
다음 버전에는 노트북을 바로 여는 Open in Colab 링크, 버전과 체크섬 자동 갱신, 교육생 제출물 점검 기능을 넣고 싶습니다. 사내 데이터를 연결할 때는 공개 교육 데이터와 완전히 분리하고, 개인정보와 고객정보가 Colab이나 공개 사이트에 올라가지 않도록 운영 기준도 함께 만들 계획입니다.
돌아보면 이번에 만든 것은 예측 모델 하나가 아니었습니다. 교육생이 시작→실습→검증→해석까지 혼자 이어갈 수 있도록 교육 경험 전체를 하나의 배포물로 묶은 작업이었습니다.
