처음 AI 공부를 시작하면 대부분 하나의 파이썬 파일 안에서 코드를 작성한다. 데이터 불러오기, 분석, 모델 학습, 결과 확인까지 모두 한 파일에 넣어도 작은 실습에서는 큰 문제가 없다.

하지만 프로젝트 규모가 커지면 상황이 달라진다. 파일이 길어지고 코드가 복잡해지면서 원하는 부분을 찾기 어려워지고, 수정 과정에서 예상하지 못한 오류가 발생하기도 한다.

AI 개발은 단순히 모델을 만드는 것뿐 아니라 데이터를 관리하고 실험 결과를 기록하며 코드를 유지하는 과정까지 포함한다. 따라서 좋은 프로젝트 구조를 만드는 습관은 개발 효율을 크게 높여준다.

필자도 처음에는 "작동만 하면 된다"는 생각으로 코드를 작성했지만, 시간이 지나 다시 프로젝트를 열었을 때 어디부터 확인해야 할지 어려웠던 경험이 있다. 이후 파일과 기능을 나누는 습관을 들이면서 실험과 수정 과정이 훨씬 편해졌다.

이번 글에서는 AI 프로젝트에서 자주 사용하는 파이썬 파일 구조와 코드 관리 방법을 알아보겠다.

AI 프로젝트 구조가 중요한 이유

AI 프로젝트는 일반 프로그램과 조금 다른 특징을 가진다.

일반 프로그램은 주로 코드 중심으로 구성되지만, AI 프로젝트는 다음 요소들이 함께 관리되어야 한다.

  • 데이터 파일
  • 분석 코드
  • 학습 모델
  • 결과 파일
  • 실험 기록
  • 설정 정보

따라서 처음부터 구조를 잘 정리하면 프로젝트가 커져도 관리하기 쉬워진다.

좋은 프로젝트 구조는 다음과 같은 장점이 있다.

  • 코드 위치를 쉽게 찾을 수 있다.
  • 여러 사람이 협업하기 편하다.
  • 실험 결과를 비교하기 쉽다.
  • 오류 발생 위치를 찾기 쉽다.

기본적인 AI 프로젝트 폴더 구조

AI 프로젝트에서 자주 사용하는 형태는 다음과 같다.

project
│
├── data
│   ├── raw
│   └── processed
│
├── notebooks
│
├── src
│
├── models
│
├── results
│
├── requirements.txt
│
└── README.md

각 폴더는 서로 다른 역할을 가진다.

data 폴더: 데이터를 관리하는 공간

AI 프로젝트에서 데이터는 가장 중요한 요소 중 하나다.

보통 데이터는 두 가지로 나누어 관리한다.

raw 데이터

원본 데이터를 저장하는 공간이다.

예:

  • 처음 수집한 CSV 파일
  • 이미지 원본
  • 로그 데이터

원본 데이터는 가능하면 수정하지 않고 그대로 보관하는 것이 좋다.

processed 데이터

전처리 과정을 거친 데이터를 저장한다.

예:

  • 결측치 처리 완료
  • 불필요한 데이터 제거
  • 형식 변환 완료

이렇게 구분하면 원본과 가공 데이터를 쉽게 비교할 수 있다.

notebooks 폴더: 실험 기록 공간

Jupyter Notebook은 AI 학습 과정에서 많이 활용된다.

노트북 파일에는 다음과 같은 내용을 기록할 수 있다.

  • 데이터 분석 과정
  • 그래프 결과
  • 모델 실험
  • 성능 비교

특히 초기 탐색 단계에서는 매우 유용하다.

예를 들어 다음과 같이 관리할 수 있다.

notebooks

01_data_check.ipynb
02_visualization.ipynb
03_model_test.ipynb

파일 이름만 봐도 어떤 작업을 했는지 알 수 있다.

src 폴더: 실제 코드 관리

프로젝트가 커지면 코드를 기능별로 나누는 것이 좋다.

예:

src

├── data_loader.py
├── preprocessing.py
├── train.py
└── predict.py

각 파일의 역할은 명확하다.

data_loader.py

데이터를 불러오는 기능 담당

preprocessing.py

데이터 정리와 변환 담당

train.py

모델 학습 담당

predict.py

새로운 데이터 예측 담당

이렇게 나누면 수정해야 할 부분을 쉽게 찾을 수 있다.

models 폴더: 학습된 모델 저장

AI 모델은 학습 후 파일 형태로 저장할 수 있다.

예:

models

model_v1.pkl
model_v2.pkl

버전을 구분하면 여러 실험 결과를 비교하기 쉽다.

특히 모델 성능을 개선하는 과정에서는 이전 모델을 보관하는 것이 중요하다.

requirements.txt의 역할

AI 프로젝트는 다양한 라이브러리를 사용한다.

예:

  • numpy
  • pandas
  • scikit-learn
  • tensorflow
  • torch

다른 컴퓨터에서 같은 프로젝트를 실행하려면 동일한 환경이 필요하다.

이때 사용하는 파일이 requirements.txt다.

예:

numpy
pandas
scikit-learn
matplotlib

필요한 라이브러리를 기록해 두면 새로운 환경에서도 쉽게 설치할 수 있다.

README.md 작성하기

README 파일은 프로젝트 설명서 역할을 한다.

보통 다음 내용을 포함한다.

  • 프로젝트 목적
  • 실행 방법
  • 필요한 환경
  • 데이터 설명
  • 결과 요약

시간이 지나 다시 프로젝트를 확인할 때 가장 먼저 보는 파일이기도 하다.

Git으로 코드 관리하기

AI 프로젝트에서는 Git 사용도 매우 중요하다.

Git은 코드 변경 내용을 기록하고 관리하는 도구다.

예를 들어:

  • 언제 코드를 수정했는지
  • 어떤 부분이 변경되었는지
  • 이전 버전으로 돌아갈 수 있는지

를 확인할 수 있다.

특히 여러 모델을 실험하는 AI 프로젝트에서는 Git 관리가 큰 도움이 된다.

AI 프로젝트에서 기록이 중요한 이유

AI 개발은 한 번에 완벽한 결과가 나오는 경우가 드물다.

보통 다음과 같은 과정을 반복한다.

  1. 데이터 변경
  2. 모델 학습
  3. 결과 확인
  4. 수정
  5. 다시 실험

이 과정에서 어떤 변경을 했는지 기록하지 않으면 어떤 방법이 효과가 있었는지 알기 어렵다.

따라서 다음 내용을 기록하는 습관이 좋다.

  • 사용한 데이터
  • 모델 종류
  • 설정값
  • 성능 결과
  • 변경 사항

초보자가 만들기 좋은 간단한 구조

처음부터 복잡한 구조를 만들 필요는 없다.

입문 프로젝트라면 다음 정도로도 충분하다.

my_ai_project

├── data
├── main.py
├── model.py
├── train.py
└── README.md

중요한 것은 규모보다 역할을 구분하는 습관이다.

프로젝트가 성장하면서 필요한 부분을 추가하면 된다.

마무리

AI 프로젝트에서는 좋은 모델을 만드는 것만큼 코드를 관리하는 능력도 중요하다. 데이터, 코드, 모델, 결과 파일을 목적에 맞게 분리하면 프로젝트가 커져도 안정적으로 관리할 수 있다.

처음에는 파일을 나누는 과정이 번거롭게 느껴질 수 있지만, 시간이 지나면 오히려 개발 시간을 줄여주는 중요한 습관이 된다.

AI 개발자는 단순히 코드를 작성하는 사람이 아니라 데이터를 관리하고 실험 과정을 설계하는 사람이다. 체계적인 프로젝트 구조를 만드는 능력은 앞으로 더 복잡한 AI 기술을 다룰 때 큰 기반이 된다.

다음 글에서는 AI 모델 학습 과정에서 자주 발생하는 오류와 해결 방법을 알아보겠다.

FAQ

Q1. AI 프로젝트는 처음부터 복잡한 폴더 구조를 만들어야 하나요?

아니다. 작은 프로젝트는 간단하게 시작해도 된다. 중요한 것은 데이터, 코드, 결과물을 구분하는 습관을 갖는 것이다.

Q2. Jupyter Notebook만 사용해도 괜찮나요?

학습과 실험 단계에서는 매우 유용하다. 하지만 프로젝트가 커지면 실제 코드는 별도 파일로 관리하는 것이 좋다.

Q3. Git은 AI 초보자에게도 필요한가요?

필수는 아니지만 매우 도움이 된다. 코드 변경 내용을 기록하고 실험 과정을 관리하는 데 유용하기 때문에 일찍 익혀두면 좋다.