01. PyCaret + Jupyter Lab 환경 구축 가이드 — 소설처럼 읽는 머신러닝

개요

PyCaret은 머신러닝 워크플로우를 자동화하는 Python 라이브러리로, 초보자도 쉽게 머신러닝 모델을 구축할 수 있습니다. Jupyter Lab과 함께 사용하면 대화형 환경에서 데이터 분석과 모델 학습을 효율적으로 수행할 수 있습니다.

시스템 요구사항

필수 소프트웨어

Python 3.10 이상
uv (Python 패키지 관리자)
최소 4GB RAM (8GB 권장)
최소 2GB 여유 디스크 공간

지원 운영체제

macOS 10.15 이상
Windows 10 이상
Linux (Ubuntu 20.04 이상)

uv 설치

uv는 빠르고 안정적인 Python 패키지 관리 도구입니다.

macOS / Linux

# Homebrew를 통한 설치 (권장)brew install uv# 또는 공식 설치 스크립트curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

# PowerShell에서 실행
irm https://astral.sh/uv/install.ps1 | iex

설치 확인

uv --version# 예상 출력: uv 0.x.x

프로젝트 생성 및 환경 구축

1. 프로젝트 디렉토리 생성

# 프로젝트 디렉토리 생성mkdir ml-pycaret# 프로젝트 디렉토리로 이동cd ml-pycaret

2. 가상환경 생성

# Python 3.10 기반 가상환경 생성uv venv -p 3.10

3. 프로젝트 초기화

# uv 프로젝트 초기화 (pyproject.toml 생성)uv init

4. 필수 패키지 설치

# 머신러닝 및 데이터 분석 패키지 설치# PyCaret 3.3.2 버전을 명시적으로 설치하여 최신 기능을 활용합니다.uv add scikit-learn pandas matplotlib seaborn "pycaret==3.3.2" jupyterlab# 설치 완료 확인uv pip list | grep -E "(pycaret|jupyterlab)"

주요 패키지 설명:

pycaret: 머신러닝 워크플로우 자동화 라이브러리
jupyterlab: 대화형 노트북 환경
scikit-learn: 머신러닝 알고리즘 라이브러리
pandas: 데이터 분석 라이브러리
matplotlib, seaborn: 데이터 시각화 라이브러리

5. 프로젝트 구조 설정

# 디렉토리 생성mkdir -p data/{raw,processed} notebooks models scripts

기본 구조: ml-pycaret/ ├── .venv/ # 가상환경 ├── pyproject.toml # 프로젝트 설정 ├── data/ # 데이터 파일 ├── notebooks/ # Jupyter 노트북 ├── models/ # 학습된 모델 └── scripts/ # Python 스크립트

Jupyter Lab 실행

기본 실행

# Jupyter Lab 서버 시작uv run jupyter lab# 자동으로 브라우저가 열리며 http://localhost:8888 접속

백그라운드 실행

# 백그라운드에서 실행 (터미널 종료 후에도 유지)nohup uv run jupyter lab --no-browser &# 실행 중인 Jupyter Lab 확인ps aux | grep jupyter# 종료pkill -f jupyter

특정 포트 지정

# 포트 8889로 실행uv run jupyter lab --port=8889# 외부 접속 허용 (주의: 보안 위험)uv run jupyter lab --ip=0.0.0.0

한글 폰트 설정 (Matplotlib)

matplotlib에서 한글이 깨짐 없이 표시하려면 시스템에 한글 폰트가 설치되어 있어야 하며, matplotlib에 해당 폰트를 사용하도록 설정해야 합니다.

1. 운영체제별 한글 폰트 확인 및 설치

Windows: 맑은 고딕(Malgun Gothic)이 기본적으로 설치되어 있습니다.
macOS: AppleGothic이 기본적으로 설치되어 있습니다.

Linux (Ubuntu): 나눔 폰트를 설치해야 합니다.

# 터미널에서 나눔 폰트 설치sudo apt-get updatesudo apt-get install -y "fonts-nanum*"

2. Jupyter 노트북에서 한글 폰트 설정

Jupyter 노트북 상단에 다음 코드를 추가하여 실행하면, 현재 운영체제에 맞는 한글 폰트를 자동으로 설정합니다.

import matplotlib.pyplot as pltimport platformimport os# 운영체제별 글꼴 설정if platform.system() == 'Windows':    # 윈도우    plt.rc('font', family='Malgun Gothic')elif platform.system() == 'Darwin':    # Mac    plt.rc('font', family='AppleGothic')else:    # 리눅스    # 나눔 폰트가 설치되어 있는지 확인    font_path = '/usr/share/fonts/truetype/nanum/NanumGothic.ttf'    if os.path.exists(font_path):        plt.rc('font', family='NanumGothic')    else:        print(f"나눔 폰트가 설치되어 있지 않습니다: '{font_path}'")        print("터미널에서 'sudo apt-get install \"fonts-nanum*\"' 명령어로 설치해주세요.")# 마이너스 폰트 깨짐 방지plt.rc('axes', unicode_minus=False)print("한글 폰트 설정이 완료되었습니다.")

환경 테스트

Jupyter Lab에서 새 노트북을 생성하고 다음 코드를 실행하여 환경을 테스트합니다.

1. 패키지 Import 테스트

# 필수 패키지 Importimport pandas as pdimport numpy as npimport matplotlib.pyplot as pltimport seaborn as snsfrom pycaret.classification import *

2. PyCaret 버전 확인

# PyCaret 버전 및 설정 확인import pycaretprint(f"PyCaret 버전: {pycaret.__version__}")

3. 간단한 데이터 분석 테스트

# 샘플 데이터 생성data = {    'feature1': [1, 2, 3, 4, 5],    'feature2': [2, 4, 6, 8, 10],    'target': [0, 1, 0, 1, 0]}df = pd.DataFrame(data)# 데이터 확인print(df.head())print(f"\n데이터 형태: {df.shape}")# 간단한 시각화plt.figure(figsize=(8, 4))plt.scatter(df['feature1'], df['feature2'], c=df['target'], cmap='viridis')plt.xlabel('Feature 1')plt.ylabel('Feature 2')plt.title('Sample Data Visualization')plt.colorbar(label='Target')plt.show()

4. 한글 폰트 테스트

위에서 한글 폰트 설정을 완료한 후, 다음 코드를 실행하여 그래프에 한글이 정상적으로 표시되는지 확인합니다.

import matplotlib.pyplot as pltimport platformimport os# 운영체제별 글꼴 설정if platform.system() == 'Windows':    plt.rc('font', family='Malgun Gothic')elif platform.system() == 'Darwin':    plt.rc('font', family='AppleGothic')else:    plt.rc('font', family='NanumGothic')plt.rc('axes', unicode_minus=False)# 한글 테스트 그래프plt.figure(figsize=(10, 5))plt.plot([-1, 0, 1, 2], [1, 4, 2, 3], marker='o')plt.title('한글 제목 테스트')plt.xlabel('X축 레이블')plt.ylabel('Y축 레이블')plt.legend(['테스트 데이터'])plt.grid(True)plt.show()

문제 해결

1. 패키지 설치 오류

# 캐시 삭제 후 재설치uv cache cleanuv add pycaret jupyterlab

2. Jupyter Lab 실행 오류

# Jupyter 재설치uv remove jupyterlabuv add jupyterlab# 설정 초기화jupyter lab --generate-config

3. Python 버전 불일치

# 현재 Python 버전 확인python --version# uv가 사용하는 Python 확인uv python list# 올바른 버전으로 가상환경 재생성rm -rf .venvuv venv -p 3.10uv add scikit-learn pandas matplotlib seaborn pycaret jupyterlab

4. 메모리 부족 오류

PyCaret은 많은 메모리를 사용할 수 있습니다. 메모리 부족 시:

# PyCaret 설정에서 메모리 사용량 제한from pycaret.classification import setupexp = setup(    data=df,    target='target',    verbose=False,    use_gpu=False,  # GPU 비활성화    n_jobs=1        # 병렬 처리 제한)

부록: 프로젝트 템플릿 참고 자료

.gitignore 샘플

Git에서 제외할 파일 목록입니다.

위치: .gitignore

# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv

# JupyterLab
.ipynb_checkpoints/

# Data files
*.csv
*.xlsx
*.json
!sample.csv

# Model files
*.pkl
*.joblib
*.h5
*.model

# OS files
.DS_Store
Thumbs.db

주요 제외 항목:

Python 캐시: __pycache__/, *.pyc
가상환경: .venv
Jupyter 체크포인트: .ipynb_checkpoints/
데이터 파일: 용량이 큰 CSV, Excel 파일
모델 파일: 학습된 모델 (용량 문제)

주의: !sample.csv는 예외로 포함

샘플 노트북 기본 구조

위치: notebooks/template.ipynb

기본 구조:

# 1. 라이브러리 Importimport pandas as pdimport numpy as npimport matplotlib.pyplot as pltimport seaborn as snsfrom pycaret.classification import *# 2. 데이터 로드train = pd.read_csv('../data/raw/train.csv')# 3. 데이터 탐색train.head()train.info()train.describe()# 4. PyCaret 설정exp = setup(    data=train,    target='target_column',    session_id=123,    verbose=False)# 5. 모델 비교best = compare_models()# 6. 모델 평가evaluate_model(best)# 7. 예측predictions = predict_model(best, data=test_data)# 8. 모델 저장save_model(best, '../models/best_model')

개요