deeptool

📖 문서 · English

주피터 노트북에서 PyTorch 모델을 객체지향으로 다루기 위한 얇은 보조 라이브러리.

모델은 유저가 PyTorch로 직접 작성한다. 이 라이브러리는 그 주변만 담당한다 — 하이퍼파라미터 자동 저장, 셀 간 메서드 추가, 학습 중 손실 곡선 라이브 렌더링, 디바이스 자동 선택, 학습 기록 영속화, 체크포인트.

설치

uv add deeptool     # uv 프로젝트에
pip install deeptool

import deeptool as dt

이 저장소에서 직접 개발하려면:

uv sync

퀵스타트

import torch
from torch import nn
from torch.nn import functional as F

import deeptool as dt


class SyntheticRegression(dt.DataModule):
    def __init__(self, n=200, batch_size=32):
        super().__init__()
        self.save_hyperparameters()
        torch.manual_seed(0)
        self.X = torch.randn(n, 2)
        self.y = self.X @ torch.tensor([[2.0], [-3.4]]) + 4.2

    def get_dataloader(self, train):
        idx = slice(0, 160) if train else slice(160, None)
        return self.get_tensorloader((self.X, self.y), train, idx)


class LinearRegression(dt.Module):
    def __init__(self, lr=0.03):
        super().__init__()
        self.save_hyperparameters()
        self.net = nn.LazyLinear(1)

다음 셀에서 메서드를 덧붙인다. 클래스를 다시 정의할 필요가 없다.

@dt.add_to_class(LinearRegression)
def loss(self, y_hat, y):
    return F.mse_loss(y_hat, y)


@dt.add_to_class(LinearRegression)
def configure_optimizers(self):
    return torch.optim.SGD(self.parameters(), lr=self.lr)

학습을 돌리면 손실 곡선이 셀 출력에 실시간으로 갱신된다.

trainer = dt.Trainer(max_epochs=20)
trainer.fit(LinearRegression(), SyntheticRegression())

trainer.save_checkpoint("linreg.pt")

전체 예제는 examples/quickstart.ipynb 참고.

학습 기록과 실행 비교

log_dir을 주면 메타데이터와 완료된 에폭을 즉시 디스크에 남긴다.

trainer = dt.Trainer(max_epochs=50, plot=False, log_dir="runs/exp1")
trainer.fit(model, data)

모델 안의 사용자 지표는 이름을 그대로 쓴다. 같은 에폭에서 여러 번 부르면 평균 한 점이 된다.

self.log("iou", value)

실행마다 meta.json과 append-only history.jsonl이 생긴다. 스크립트에서는 log_dir을 준 경우에만 에폭당 한 줄도 출력한다. 기록 중이거나 중간에 멈춘 실행도 완료된 줄까지 읽고 비교할 수 있다.

runs = dt.load_runs("runs")
figures = dt.plot_runs(runs)

plot_runs는 지표마다 Figure 하나를 만들고 그 지표가 있는 실행만 겹쳐 그린다. 모델마다 지표 이름이 달라도 별도 스키마가 필요 없다.

학습률 스케줄러

에폭 기반 scheduler는 optimizer와 함께 반환한다.

def configure_optimizers(self):
    optim = torch.optim.Adam(self.parameters(), lr=self.lr)
    scheduler = torch.optim.lr_scheduler.StepLR(optim, step_size=10, gamma=0.1)
    return optim, scheduler

일반 scheduler는 에폭 뒤 step(), ReduceLROnPlateau는 검증 뒤 step(val_loss)로 호출된다. 매 배치 호출이 필요한 OneCycleLR와 AMP는 아직 지원하지 않는다.

조기 종료와 최적 가중치

개선이 멈출 때까지 돌리고 가장 좋았던 가중치를 쓴다.

trainer = dt.Trainer(max_epochs=100, patience=5)
trainer.fit(model, data)

len(trainer.history["val_loss"])             # 24 — 100까지 안 감
trainer.best_epoch, trainer.best_val_loss    # (18, 0.2913)

trainer.restore_best()                       # 18 을 반환

fit() 은 가중치를 자동으로 되돌리지 않는다. restore_best() 를 부르기 전까지는 마지막 epoch 상태이므로 두 시점의 성능을 비교할 수 있다.

기본은 메모리 스냅샷이다. 파일로 남기려면:

dt.Trainer(max_epochs=100, patience=5, best_path="best.pt")

파일에는 모델 가중치만 들어간다. optimizer 상태는 restore_best() 가 읽지 않는데 Adam 기준 모델의 2배라 매 epoch 쓰면 낭비다. 최저점부터 학습을 재개할 계획이면 best_with_optim=True 로 전체 체크포인트를 남긴다.

학습 후 평가

p = trainer.predict(data)        # 검증셋 전체 추론

p.accuracy                       # 0.8837
p.preds                          # 샘플별 예측 클래스
p.confidence                     # 예측 확신도
p.correct                        # 맞췄는지 여부 (bool 텐서)

p = trainer.predict(data, keep_inputs=True)
p.inputs[~p.correct]             # 틀린 샘플의 입력 — 시각화에 쓴다

preds·probs·confidence·correct·accuracy 는 분류 전용이다. 회귀 모델이면 p.outputs 를 직접 쓴다.

API

개발

uv run pytest

라이센스

MIT. LICENSE 참고.

설계는 d2l-ai/d2l-en의 d2l/torch.py를 참고했다. 해당 샘플 코드는 modified MIT(LICENSE-SAMPLECODE)로 배포된다.