Jupyter 노트북

노트북(notebook)은 AI 엔지니어링(AI engineering)의 실험대입니다. 여기서 프로토타입(prototype)을 만들고, 잘 동작하는 것은 프로덕션 코드(production code)로 옮깁니다.

유형: Build 언어: Python 선수 지식: Phase 0, Lesson 01 예상 시간: 약 30분

학습 목표

• JupyterLab, Jupyter Notebook, VS Code Jupyter 확장(extension) 중 하나를 설치하고 실행합니다.
• %timeit, %%time, %matplotlib inline 같은 매직 명령(magic command)으로 benchmark와 인라인 시각화(inline visualization)를 수행합니다.
• 노트북과 스크립트(script)를 언제 써야 하는지 구분하고 "노트북에서 탐색하고 script로 배포한다"는 workflow를 적용합니다.
• 순서가 뒤섞인 실행(out-of-order execution), 숨은 상태(hidden state), 메모리 누수(memory leak) 같은 노트북 함정을 식별하고 피합니다.

문제

AI 논문(paper), 튜토리얼(tutorial), Kaggle 경진대회(competition)는 거의 모두 Jupyter 노트북을 사용합니다. 노트북은 코드를 조각 단위로 실행하고, 출력을 인라인(inline)으로 보고, 코드와 설명을 섞고, 빠르게 반복할 수 있게 해 줍니다. 노트북 없이 AI를 배우는 것은 연습장(scratch paper) 없이 수학 문제를 푸는 것과 비슷합니다.

하지만 노트북에는 실제 함정이 있습니다. 사람들은 노트북에 맞지 않는 작업까지 모두 노트북으로 하려고 합니다. 노트북을 써야 할 때와 스크립트를 써야 할 때를 구분하면 나중에 디버깅 악몽(debugging nightmare)을 크게 줄일 수 있습니다.

개념

노트북은 셀(cell)의 목록입니다. 각 셀은 코드이거나 텍스트입니다.

graph TD
    A["**Markdown Cell**<br># My Experiment<br>Learning rate 0.01 테스트"] --> B["**Code Cell** ► 실행<br>model.fit(X, y, lr=0.01)<br>---<br>출력: loss = 0.342"]
    B --> C["**Code Cell** ► 실행<br>plt.plot(losses)<br>---<br>출력: inline plot"]

커널(kernel)은 백그라운드(background)에서 실행되는 Python 프로세스(process)입니다. 셀을 실행하면 노트북 UI가 코드를 커널에 보내고, 커널은 실행 결과를 돌려줍니다. 모든 셀은 같은 커널을 공유하므로 변수(variable)가 셀 사이에 남아 있습니다.

graph LR
    A[Notebook UI] <--> B["Kernel<br>Python process"]
    B --> C["변수를 memory에 유지"]
    B --> D["클릭한 순서대로 cell 실행"]
    B --> E["재시작하면 종료됨"]

원하는 순서로 셀을 실행할 수 있다는 점은 강력한 장점이지만, 동시에 가장 흔한 문제의 원인입니다.

직접 만들기

Step 1: 인터페이스(interface) 선택

세 가지 인터페이스가 있고, 모두 같은 .ipynb 파일을 읽고 씁니다.

AI 작업에서는 JupyterLab이 가장 흔합니다. PAI Python 환경에서는 uv를 기본으로 사용합니다.

pip install jupyterlab

# PAI 기준 Python 환경에서는 uv 사용을 우선합니다.
uv pip install jupyterlab
jupyter lab

Step 2: 중요한 키보드 단축키(keyboard shortcut)

노트북에는 두 가지 모드가 있습니다. Escape를 누르면 명령 모드(command mode), Enter를 누르면 편집 모드(edit mode)입니다.

명령 모드에서 많이 쓰는 단축키:

편집 모드:

Shift+Enter는 하루에도 수없이 쓰는 단축키입니다. 먼저 익숙해져야 합니다.

Step 3: 셀의 종류

코드 셀(code cell)은 Python을 실행하고 출력을 보여줍니다.

import numpy as np

data = np.random.randn(1000)
data.mean(), data.std()

출력(Output): (0.0032, 0.9987)

마크다운 셀(markdown cell)은 서식이 적용된 텍스트(formatted text)를 렌더링합니다. 무엇을 하고 왜 하는지 기록할 때 사용합니다. 헤더(header), 굵게(bold), 이탤릭(italic), LaTeX 수식($E = mc^2$), 표(table), 이미지(image)를 지원합니다.

Step 4: 매직 명령(Magic command)

%로 시작하는 라인 매직(line magic)과 %%로 시작하는 셀 매직(cell magic)은 Python이 아니라 Jupyter 전용 명령입니다.

%timeit np.random.randn(10000)

출력(Output): 45.2 us +/- 1.3 us per loop

%timeit은 코드를 여러 번 실행해 평균을 냅니다. 마이크로 벤치마크(microbenchmark)에 적합합니다.

%%time
model.fit(X_train, y_train, epochs=10)

출력(Output): Wall time: 2.34 s

%%time은 셀을 한 번 실행하고 실제 경과 시간(wall time)을 보여줍니다. 훈련 실행(training run)처럼 긴 작업에 적합합니다.

%matplotlib inline

모든 plt.plot()이나 plt.show() 결과가 노트북 셀 아래에 바로 나타납니다.

노트북을 벗어나지 않고 패키지를 설치할 수도 있습니다.

!pip install scikit-learn

! 접두사(prefix)는 셸 명령을 실행합니다. 다만 PAI Python 환경에서는 노트북 커널이 쓰는 Python에 설치되는지 확인하기 위해 %pip 사용을 우선할 수 있습니다.

%pip install scikit-learn

환경 변수(environment variable)도 확인할 수 있습니다.

!python --version
%env CUDA_VISIBLE_DEVICES

Step 5: 풍부한 출력(rich output)을 인라인으로 표시하기

노트북은 셀의 마지막 표현식(expression)을 자동으로 표시합니다. 하지만 원하는 방식으로 제어할 수도 있습니다.

import pandas as pd

df = pd.DataFrame({
    "model": ["Linear", "Random Forest", "Neural Net"],
    "accuracy": [0.72, 0.89, 0.94],
    "training_time": [0.1, 2.3, 45.6],
})
df

print(df)가 아니라 df를 마지막 줄에 두면 텍스트 덤프(text dump)가 아니라 서식이 적용된 HTML 표(formatted HTML table)로 표시됩니다.

import matplotlib.pyplot as plt

plt.figure(figsize=(8, 4))
plt.plot([1, 2, 3, 4], [1, 4, 2, 3])
plt.title("Inline Plot")
plt.show()

플롯(plot)은 셀 바로 아래에 나타납니다. 이것이 AI 작업에서 노트북이 널리 쓰이는 이유입니다. 데이터, 플롯, 코드를 함께 볼 수 있습니다.

이미지도 인라인으로 표시할 수 있습니다.

from IPython.display import Image, display

display(Image(filename="architecture.png"))

Step 6: Google Colab

Colab은 클라우드에서 실행되는 무료 Jupyter 노트북입니다. GPU, 미리 설치된 라이브러리(pre-installed library), Google Drive 연동(integration)을 제공합니다. 별도 설정(setup)이 필요하지 않습니다.

1. colab.research.google.com에 접속합니다.
2. 이 과정의 .ipynb 파일을 업로드(upload)합니다.
3. Runtime > Change runtime type > T4 GPU를 선택합니다.

Colab은 로컬 Jupyter와 다릅니다.

• 파일은 세션 사이에 유지되지 않습니다. Drive에 저장하거나 다운로드해야 합니다.
• numpy, pandas, matplotlib, torch, tensorflow, sklearn 등이 미리 설치되어 있습니다.
• from google.colab import files로 업로드/다운로드할 수 있습니다.
• from google.colab import drive; drive.mount('/content/drive')로 영속 저장소(persistent storage)를 붙일 수 있습니다.
• 무료 등급(free tier)은 90분 동안 활동이 없으면 세션이 종료될 수 있습니다.

사용해보기

노트북과 스크립트: 언제 무엇을 쓸까

규칙은 간단합니다. 노트북에서 탐색하고 스크립트로 배포합니다.

일반적인 AI 워크플로우는 아래와 같습니다.

1. 노트북에서 데이터를 탐색합니다.
2. 노트북에서 모델을 프로토타입으로 만듭니다.
3. 동작이 확인되면 코드를 .py 파일로 옮깁니다.
4. 그 .py 파일을 노트북에서 임포트(import)해 다음 실험을 이어 갑니다.

흔한 함정

산출물 만들기

이 강의는 노트북 문제를 진단하는 프롬프트를 산출합니다.

• outputs/prompt-notebook-helper.md: 커널 충돌(kernel crash), 메모리 문제(memory issue), 표시 실패(display failure)를 진단하는 프롬프트

code/notebook_tips.py를 실행하면 노트북에서 자주 쓰는 패턴을 스크립트 형태로 확인할 수 있습니다.

python phases/00-setup-and-tooling/05-jupyter-notebooks/code/notebook_tips.py

연습문제

1. JupyterLab을 열고 노트북을 만든 뒤 %timeit으로 리스트 컴프리헨션(list comprehension)과 NumPy가 100,000개 난수 배열(random number array)을 만드는 시간을 비교합니다.
2. 마크다운 셀과 코드 셀을 모두 사용해 CSV를 로드(load)하고 데이터프레임(dataframe)을 표시하고 차트를 그리는 노트북을 만듭니다. Kernel > Restart & Run All로 위에서부터 실행되는지 확인합니다.
3. code/notebook_tips.py의 코드를 Colab 노트북에 붙여 넣고 무료 GPU 런타임에서 실행합니다.

핵심 용어

더 읽을거리

• JupyterLab Documentation — JupyterLab 기능과 확장(extension) 구조를 확인합니다.
• Google Colab FAQ — Colab 세션, GPU, 저장소(storage) 제한을 확인합니다.
• IPython Magic Commands — %timeit, %env, %pip 같은 매직 명령을 확인합니다.