preview

🧠 NeuralForge — 모듈형 딥러닝 실험 프레임워크

PyTorch 연구 파이프라인을 위한 프로덕션 지향 오케스트레이션 레이어이며, Hydra의 설정 철학을 기반으로 구축되었습니다.

NeuralForge는 재현성(reproducibility)을 원하지만 경직성을 피하고 싶은 팀과 개인 연구자를 위한 구조화된 실험 프레임워크입니다. NeuralForge는 학습 스크립트를 일회용 아티팩트로 취급하는 대신, 모든 실험을 계약(contract)으로 간주합니다: 선언된 입력값, 버전 관리되는 설정(configs), 결정론적 시드(deterministic seeds), 그리고 잘 가공된 부품처럼 결합되는 플러그형 모듈들입니다.

이 레포지토리는 미니멀리스트한 보일러플레이트 전통에서 영감을 받은 독립적인 재구상된 진화물입니다. 이는 “그냥 PyTorch + Hydra”의 정신을 유지하면서도, 실제 프로젝트가 결국 필요로 하는 구조화된 로깅(structured logging), 체크포인트 계보(checkpoint lineage), 메트릭 라우팅(metric routing), 그리고 구성되어 오버라이드되고 비교될 수 있는 설정 그래프(configuration graph)와 같은 스캐폴딩을 추가합니다.

🌌 Vision & Philosophy (비전 및 철학)

대부분의 딥러닝 레포지토리는 단일 train.py로 시작하여 주석 처리된 플래그들의 무덤으로 끝납니다. NeuralForge는 그 무덤이 시작될 곳, 즉 무엇이 실험인지와 그것이 어떻게 실행되는지를 의도적으로 분리하는 곳에서 시작합니다.

우리는 훈련 실행을 지휘자가 교향곡을 생각하는 방식에 비유합니다: 악보(설정 파일)가 권위적이고, 오케스트라(모듈)는 교체 가능하며, 연주(실행 결과물)는 나중에 연구하기 위해 기록됩니다. 아무것도 암묵적이거나 변경 가능한 전역 변수에 숨겨진 것이 없습니다. 모든 결정은 설정 노드에서 추적할 수 있습니다.

설계를 안내하는 세 가지 원칙이 있습니다:

명세적(Declarative) 방식 > 명령형(Imperative) 방식 — Hydra 설정을 실험 정의의 주체로 삼습니다.
조합 가능(Composable) 방식 > 단일 구조(Monolithic) 방식 — 데이터셋, 모델, 최적화기(optimizer), 콜백은 독립적인 레지스트리입니다.
관찰 가능(Observable) 방식 > 불투명(Opaque) 방식 — 모든 실행은 비교(diff), 플로팅 및 감사(audit)할 수 있는 구조화된 결과물을 방출합니다.

🚀 NeuralForge가 존재하는 이유

기존의 기본 틀(boilerplate)은 작은 문제를 우아하게 해결했습니다: PyTorch와 Hydra를 마찰 없이 작동하게 하는 것입니다. 하지만 NeuralForge는 더 큰 질문을 던집니다: 수십 개의 실험, 여러 협업자, 그리고 몇 달에 걸친 반복 과정을 거치면서 그 대화가 어떤 모습일까요?

그 답에는 다음이 포함됩니다:

연구 질문을 반영하는 설정 상속 트리(Config inheritance trees).
과거의 모든 실험을 비트 단위로 재현할 수 있게 하는 실행 레지스트리(Run registries).
결과를 로컬 파일, 대시보드 또는 원격 관찰 가능 스택으로 전송하는 메트릭 라우터(Metric routers).
ResNet을 ViT로 교체하는 것을 한 줄의 변경으로 만드는 모듈 계약(Module contracts).

만약 유망한 체크포인트 뒤에 숨겨진 정확한 하이퍼파라미터를 잃어버린 적이 있다면, NeuralForge는 당신을 위해 만들어졌습니다.

✨ 주요 기능 하이라이트

🧩 **Hydra 기반 설정 그래프(configuration graph)**를 통해 계층적 구성 및 오버라이드 해상도를 지원합니다.
🔁 시드 스냅샷과 환경 지문 인식(environment fingerprinting)을 사용한 결정론적 실행 재현(Deterministic run replay) 기능을 제공합니다.
📦 모델, 데이터셋, 손실 함수(losses), 옵티마이저(optimizers), 스케줄러(schedulers)를 위한 **플러그인 모듈 레지스트리(Pluggable module registry)**를 갖추고 있습니다.
📊 로컬 CSV, JSONL 및 플러그인 싱크(sinks)를 지원하는 **메트릭 라우팅 레이어(Metric routing layer)**가 탑재되어 있습니다.
🗂️ 가중치와 해당 가중치를 생성한 설정 간의 연결을 추적하는 체크포인트 계보 추적(Checkpoint lineage tracking) 기능을 제공합니다.
🌍 CLI 메시지 및 생성된 보고서에 대한 다국어 지원을 합니다 (지역화 인식 템플릿, locale-aware templates).
📱 데스크톱, 태블릿, 모바일 뷰포트에 적응하는 **반응형 대시보드 UI(Responsive dashboard UI)**를 제공합니다.
🕒 엔터프라이즈 및 연구팀을 위한 24/7 고객 지원 채널 라우팅 기능을 갖추고 있습니다.
🔒 라이브러리 버전, 하드웨어, RNG 상태를 포착하는 **재현성 매니페스트(Reproducibility manifests)**를 생성합니다.
🧪 설정과 메트릭 공간에 걸쳐 두 실행을 비교할 수 있는 실험 차이 분석(Experiment diffing) 기능을 제공합니다.
🧭 JSON 및 사람이 읽기 쉬운 모드(human-readable modes)의 **구조화된 로깅(Structured logging)**을 지원합니다.
🛠️ 핵심 로직을 포크(forking)하지 않고도 사용자 정의 콜백(callbacks)을 위한 **확장 가능한 후크(Extensible hooks)**를 제공합니다.

🏗️ 아키텍처 개요 (Architecture Overview)

NeuralForge는 네 가지 협력하는 레이어로 구성되어 있습니다:

1. 설정 레이어 (Configuration Layer)

Hydra는 YAML 조각(fragments) 트리로부터 최종 설정을 구성합니다. 각 조각은 결정 표면(decision surface)—데이터, 모델, 옵티마이저, 학습 루프, 로깅—을 나타냅니다. 구성된 설정은 런타임에 불변(immutable)이며 식별을 위해 해시화됩니다.

2. 레지스트리 레이어 (Registry Layer)

경량의 레지스트리는 문자열 키를 Python 객체에 매핑합니다. 설정에서 model: resnet50이라고 지정하면, 레지스트리가 이를 해석(resolve)합니다. 프레임워크 내부 코드를 건드리지 않고도 자체 클래스를 등록할 수 있습니다.

3. 실행 레이어 (Execution Layer)

트레이너는 구성된 설정과 해석된 객체를 소비하며, 정의된 생명 주기 지점(on_start, on_epoch_end, on_checkpoint, on_complete)에 콜백을 주입하여 학습 루프를 실행합니다.

4. Artifact Layer

모든 실행은 해결된 설정(resolved config), 환경 매니페스트(environment manifest), 메트릭 로그(metric logs) 및 선택적 체크포인트가 포함된 디렉터리를 생성합니다. 이 디렉터리가 실험의 표준 기록입니다.

⚙️ 설정 시스템 (Configuration System)

설정 시스템은 NeuralForge의 핵심입니다. 하이퍼파라미터를 코드 곳곳에 분산시키는 대신, 모든 것이 조합 가능한 YAML 조각(composable YAML fragments) 안에 존재합니다.

구성 그룹의 예시 구조:

configs/data/ — 데이터셋 정의
configs/model/ — 아키텍처 정의
configs/optim/ — 옵티마이저 및 스케줄러 정의
configs/trainer/ — 루프 동작, 에포크(epochs), 정밀도(precision)
configs/logger/ — 메트릭 싱크(metric sinks) 및 상세 수준(verbosity)

사용자는 실행 시 조각들을 이름으로 지정하여 조합을 선택합니다. 오버라이드(Overrides)는 명시적이며 기록됩니다. 아무것도 조용히 변경되지 않습니다.

🗂️ 프로젝트 레이아웃 (Project Layout)

일반적인 NeuralForge 프로젝트는 다음과 같은 형태를 채택합니다:

src/neuralforge/ — 프레임워크 코어
src/neuralforge/registry/ — 모듈 레지스트리(module registries)
src/neuralforge/trainer/ — 학습 루프 및 콜백(callbacks)
src/neuralforge/artifacts/ — 실행 아티팩트 작성기(run artifact writers)
configs/ — Hydra 설정 트리
experiments/ — 사용자 정의 실험 진입점(user-defined experiment entry points)
reports/ — 생성된 대시보드 및 요약본
tests/ — 단위 및 통합 테스트(unit and integration tests)

프레임워크 코드와 실험 코드를 분리한 것은 의도적입니다. 연구를 다시 작성하지 않고도 프레임워크만 업그레이드할 수 있습니다.

🏁 빠른 시작 (Quick Start)

첫 번째 실행을 진행하려면 세 가지 개념적인 단계를 거쳐야 합니다:

설정 조각들을 선택하여 실험을 설명합니다.
레지스트리 키를 클래스에 연결하여 모듈을 해결합니다.
실행을 시작하고 생성된 아티팩트 디렉터리를 검사합니다.

NeuralForge는 사용자의 환경에 대해 프레임워크 독립적(framework-agnostic)이기 때문에, 컨테이너 내부, 베어 메탈(bare metal), 또는 관리형 컴퓨팅 환경에서 실행할 수 있습니다. 이 프레임워크는 패키징을 규정하는 것이 아니라 구조를 규정합니다.

Download

🔄 실험 생명 주기 (Experiment Lifecycle)

모든 NeuralForge 실행은 예측 가능한 수명 주기(lifecycle)를 거칩니다:

Compose — Hydra가 최종 설정을 조립합니다.
Validate — 스키마 검사(schema checks)를 통해 필수 키의 존재 여부를 확인합니다.
Resolve — 레지스트리(registry)가 키를 실제 객체에 매핑합니다.
Fingerprint — 환경 및 난수 생성기(RNG) 상태가 기록됩니다.
Train — 콜백(callbacks)이 발생하는 루프가 실행됩니다.
Emit — 메트릭, 체크포인트, 그리고 매니페스트(manifests)가 작성됩니다.
Archive — 실행 디렉터리가 봉인되고 인덱싱됩니다.

이러한 수명 주기는 어떤 실행이라도 추측 없이 재구성하거나 비교하거나 내보낼 수 있음을 의미합니다.

🌍 다국어 및 접근성 지원 (Multilingual & Accessibility Support)

NeuralForge는 언어를 일급의 관심사(first-class concern)로 취급합니다. CLI 메시지, 로그 템플릿, 보고서 헤더를 메시지 카탈로그(message catalogs)를 통해 현지화할 수 있습니다. 이는 여러 지역에 걸쳐 팀이 분산되어 있거나 재현 가능한 파이프라인을 다양한 청중에게 발표하는 연구자들에게 중요합니다.

접근성 기능에는 다음이 포함됩니다:

해당되는 경우 스크린 리더 친화적인 보고서 출력.
반응형 대시보드에서 높은 대비 테마(High-contrast themes).
키보드 탐색이 가능한 실험 브라우저.

📱 반응형 대시보드 (Responsive Dashboard)

번들된 대시보드는 실행 아티팩트(run artifacts)를 위한 경량 보기입니다. 이는 화면 크기에 따라 유연하게 적응하며, 메트릭 추세, 설정 차이점(config diffs), 체크포인트 타임라인을 제시합니다. 모바일에서는 집중적인 실행 요약으로 축소되고, 데스크톱에서는 다중 패널 비교 작업 공간으로 확장됩니다.

이 대시보드는 임베드되거나 자체 호스팅(self-hosted)되도록 설계되었으며, 특정 클라우드 제공업체를 가정하지 않습니다.

🛎️ 지원 모델 (Support Model)

NeuralForge는 연구가 사무실 근무 시간표를 따르지 않는다고 전제합니다. 지원 모델은 다음을 중심으로 구축되었습니다:

보장된 응답 시간을 필요로 하는 팀을 위한 24/7 고객 지원 라우팅.
설계 질문 및 패턴 공유를 위한 커뮤니티 토론.
순환 일정으로 게시되는 메인테이너 오피스 아워(Maintainer office hours).

지원 등급은 문서화되어 있어 무엇을 기대할지 정확히 알 수 있습니다.

🗺️ 로드맵 (Roadmap)

계획된 방향에는 다음이 포함됩니다:

멀티 노드 환경을 위한 분산 학습 어댑터.
시각적 설정 그래프를 갖춘 심층적인 실험 차이점 도구(diff tooling).
관측 가능성 플랫폼을 위한 추가 메트릭 싱크(metric sinks).
확장된 로케일 카탈로그 및 번역 도구.
커뮤니티 모듈을 위한 플러그인 마켓플레이스 규칙.

로드맵 항목은 약속이 아닌 토론 스레드로 추적됩니다.

🔎 SEO & 검색 용이성 참고 사항

본 프로젝트는 PyTorch 실험 프레임워크, Hydra 설정 관리(configuration management), 재현 가능한 딥러닝 파이프라인, 모듈형 학습 루프, 그리고 연구팀을 위한 실험 추적과 같은 자연어 문구를 사용하여 설명됩니다. 이러한 구문들은 순위 향상을 위해 삽입된 것이 아니라 NeuralForge가 실제로 무엇을 하는지 정확하게 설명하기 때문에 나타납니다.

만약 임시적인(ad-hoc) 학습 스크립트의 구조화된 대안을 검색하던 중 이 저장소를 발견했다면, 당신이 바로 의도된 사용자입니다.

⚠️ 면책 조항 (Disclaimer)

NeuralForge는 연구 및 엔지니어링 목적으로 '있는 그대로(as-is)' 제공됩니다. 이는 모델 성능, 학습 안정성 또는 특정 도메인에 대한 적합성을 보장하지 않습니다. 사용자는 해당 법률, 타사 종속성 라이선스 및 자신의 분야에서의 윤리적 지침을 준수할 책임이 있습니다.

유지 관리자들은 이 소프트웨어의 사용으로 인해 발생하는 어떠한 손해에 대해서도 책임을 지지 않습니다. 프로덕션 환경이나 출판물에서 의존하기 전에 항상 결과를 독립적으로 검증하십시오.

📄 라이선스

본 프로젝트는 MIT License 하에 공개됩니다. 전체 약관은 라이선스 파일을 참조하십시오: MIT License.