도입

Shekswess/ai-project-template은 AI, ML, MLOps, LLMOps 프로젝트를 시작할 때 기본 구조를 빠르게 잡기 위한 GitHub 템플릿입니다.

실험 추적, 모델 버전관리, 모니터링, 테스트, CI/CD, 데이터 폴더 구조를 프로젝트 초기에 한 번에 정리하고 싶을 때 유용합니다. 특히 “일단 노트북으로만 실험하다가 나중에 정리하느라 고생하는 상황”을 줄이는 데 초점이 맞춰져 있습니다.

왜 좋은가 / 왜 유명한가

- AI/ML/MLOps/LLMOps 프로젝트에 필요한 기본 뼈대를 한 저장소 안에 모아둔 실전형 템플릿입니다.

- GitHub Actions, pytest, pre-commit, Docker Compose, pyproject.toml 등 실제 협업 프로젝트에서 자주 쓰는 구성 요소를 포함합니다.

- 데이터, 소스코드, 실험 결과, 노트북, 테스트, 인프라 코드 디렉터리를 분리해 프로젝트가 커져도 관리하기 쉽게 설계되어 있습니다.

- MLflow, OpenSearch 같은 서비스를 Docker Compose로 구성할 수 있도록 설계되어 있어 실험 추적과 모니터링 환경을 함께 고려할 수 있습니다.

- 공식 README에서 “모든 요소가 모든 프로젝트에 필요한 것은 아니며, 프로젝트에 맞게 구조와 설정 파일을 조정하라”고 안내합니다. 즉, 고정된 프레임워크라기보다 필요에 따라 덜어내고 바꿔 쓰는 출발점에 가깝습니다.

무엇을 할 수 있나 / 무엇이 들어있나

이 템플릿은 단순한 폴더 묶음이 아니라, AI 프로젝트를 운영 가능한 형태로 만들기 위한 기본 구성을 제공합니다.

- `.github/`

- GitHub 관련 설정과 워크플로를 담는 위치입니다.

- `workflows/`에는 자동 테스트, 빌드, 배포 등을 위한 CI/CD 워크플로 정의를 둘 수 있습니다.

- `dependabot.yaml`을 통해 의존성 자동 업데이트 설정을 관리할 수 있습니다.

- `config/`

- 프로젝트 설정 파일을 모아두는 디렉터리입니다.

- README 예시 기준으로 `config.yaml`에는 하이퍼파라미터, API 키, 환경 변수 관련 설정 등을 둘 수 있습니다.

- `data/`

- 데이터를 단계별로 나눠 관리하는 구조입니다.

- `raw/`: 원천 데이터

- `processed/`: 정제 및 전처리가 끝난 데이터

- `database/`: 로컬 저장소를 사용할 경우 데이터베이스 파일

- `iac/`

- Infrastructure as Code 스크립트를 두는 위치입니다.

- README에서는 AWS CloudFormation, Terraform 같은 클라우드 배포 자동화 예시를 언급합니다.

- `notebooks/`

- Jupyter Notebook 기반 분석과 실험을 위한 디렉터리입니다.

- EDA, 모델 실험, 리포팅에 활용할 수 있습니다.

- README에는 `00_example.ipynb` 예시 노트북이 언급되어 있습니다.

- `results/`

- 실험 결과, 로그, 모델 파일을 저장하는 공간입니다.

- 실험 산출물을 코드와 분리해 관리할 때 유용합니다.

- `src/`

- 실제 프로젝트 소스코드를 넣는 핵심 디렉터리입니다.

- `constants/`: 파일 경로, API 엔드포인트 같은 프로젝트 공통 상수

- `models/`: 머신러닝 모델 관련 스크립트, 클래스, 함수

- `schemas/`: 데이터 스키마와 검증 로직, 예를 들어 Pydantic 모델

- `pipelines/`: 데이터 파이프라인과 모델 파이프라인

- `utils/`: 데이터 로더, 전처리 함수 등 유틸리티

- `main.py`: 프로젝트 메인 실행 스크립트

- `tests/`

- 단위 테스트와 통합 테스트를 관리하는 디렉터리입니다.

- README에서는 `pytest` 사용을 명시하고 있습니다.

- pre-commit

- 린팅, 타입 체크, 시크릿 탐지를 위한 설정을 포함합니다.

- Docker Compose

- MLflow, OpenSearch 등의 서비스를 구성할 수 있도록 설계되어 있습니다.

- uv

- 빠른 Python 패키지 및 프로젝트 관리 도구로 소개되어 있습니다.

- pyproject.toml

- 프로젝트 설정, ruff linter, formatter, 타입 체크, 테스트 설정을 관리하는 파일로 설명되어 있습니다.

설치와 사용법

공식 README 원문에 별도의 설치 명령이나 실행 명령은 제공되어 있지 않습니다. 따라서 아래처럼 원문에서 확인된 사실만 기준으로 접근하는 것이 안전합니다.

공식 README 원문에는 설치 명령, clone 명령, uv 실행 명령, Docker Compose 실행 명령이 명시되어 있지 않습니다.
명령어 기반 설치와 실행은 공식 GitHub 저장소의 최신 문서를 확인해 사용해야 합니다.

자료는 GitHub 저장소에서 확인할 수 있습니다.

https://github.com/Shekswess/ai-project-template

실제로 사용할 때는 “내 프로젝트에 필요한 구조만 남기고 조정한다”는 방식이 좋습니다. 공식 README에서도 모든 요소가 모든 프로젝트에 필요한 것은 아니라고 안내합니다.

예를 들어, 작은 모델 실험 프로젝트라면 다음 흐름으로 시작할 수 있습니다.

1. data/raw/에 원본 데이터를 둡니다.
2. notebooks/에서 EDA와 초기 실험을 진행합니다.
3. 전처리 코드는 src/utils/ 또는 src/pipelines/로 옮깁니다.
4. 모델 코드는 src/models/에 정리합니다.
5. 실험 결과와 로그, 모델 파일은 results/에 저장합니다.
6. 반복해서 검증해야 하는 코드는 tests/에 테스트로 추가합니다.

팀 프로젝트나 배포까지 고려하는 프로젝트라면 다음 구성이 특히 중요합니다.

1. config/에 환경별 설정과 하이퍼파라미터를 모읍니다.
2. .github/workflows/에서 테스트, 빌드, 배포 자동화를 관리합니다.
3. pre-commit 설정으로 코드 품질 검사와 시크릿 탐지를 자동화합니다.
4. Docker Compose 구성을 활용해 MLflow, OpenSearch 같은 서비스를 함께 운영할 수 있는 구조를 검토합니다.
5. iac/에 클라우드 배포 자동화 스크립트를 분리해 둡니다.

처음부터 모든 디렉터리를 완벽히 채우려고 하기보다, 아래처럼 단계적으로 적용하는 편이 현실적입니다.

1단계: data, notebooks, src, results만 사용
2단계: tests와 pyproject.toml 기반 품질 관리 추가
3단계: GitHub Actions와 pre-commit으로 협업 자동화 추가
4단계: Docker Compose, MLflow, OpenSearch, iac 등 운영 요소 확장

주의할 점

- 모든 구성이 모든 프로젝트에 필요한 것은 아닙니다. 개인 실험용 프로젝트라면 `iac/`, 복잡한 CI/CD, 모니터링 구성은 처음부터 쓰지 않아도 됩니다.

- `config/`에 API 키나 비밀번호를 직접 저장할 경우 보안 문제가 생길 수 있습니다. README에서는 설정 파일에 API 키나 환경 변수 관련 값을 둘 수 있다고 예시를 들지만, 실제 운영에서는 시크릿 관리 방식을 별도로 정해야 합니다.

- Docker Compose, MLflow, OpenSearch, GitHub Actions, pre-commit, uv를 모두 이해해야만 시작할 수 있는 템플릿은 아닙니다. 다만 팀 프로젝트나 운영 환경으로 갈수록 각 도구의 역할을 구분해서 익혀야 합니다.

출처와 다운로드

공식 저장소: https://github.com/Shekswess/ai-project-template

GitHub에서 원본 README와 최신 파일 구조를 확인할 수 있습니다. 게시글 하단 첨부파일로도 받을 수 있도록 제공됩니다.