Grilly

Deep learning, well done.

PyPI

Tests

License: MIT

Docs

Vulkan compute shaders를 사용한 GPU 가속 신경망 프레임워크. 모든 GPU(AMD, NVIDIA, Intel)에서 실행되는 PyTorch와 유사한 API이며 CUDA 종속성이 없습니다. 231개의 GLSL compute shader가 SPIR-V로 컴파일되어 자동 CPU 폴백(fallback)을 가진 네이티브 C++ 레이어를 통해 디스패치됩니다.

⚠️ v1.0 이전 버전 출시 — 대규모 변경 예정

현재 main 브랜치는 마지막 태그된 릴리스(v0.6.1) 이후 대폭 재작성되었습니다. 변경 사항은 C++ Vulkan 디스패치 레이어, VMA 버퍼 할당 전략, autograd graph, nn 모듈의 forward 시그니처, torch_api 파사드 및 여러 shader에 영향을 미칩니다. v0.6.1의 의미론(semantics)에 의존하는 기존 사용자 코드는 업데이트가 필요할 수 있습니다.

변경 사항 하이라이트:

• **AMD/Windows에서 40배 빠른 nn.Linear**을 새로운 스테이징 버퍼 패턴(DEVICE_LOCAL VRAM compute + WC stage-in + HOST_CACHED readback)을 통해 구현했습니다. 동일한 패턴은 linear / linear_backward / layernorm / embedding / activations / optimizer / loss / dropout 전반에 적용되었습니다.
• Cooperative-matrix GEMM (gemm-coopmat-shared.glsl) — VK_KHR_cooperative_matrix를 통한 fp16 GEMM을 구현했습니다. RDNA3/NVIDIA RTX에서는 하드웨어 텐서 코어에 도달하며, RDNA2에서는 드라이버 에뮬레이션 경로를 통해 실행됩니다. 새로운 LinearParams.elemSize 필드와 범용 py::array 바인딩 덕분에 nn.Linear가 fp32 또는 fp16 입력을 투명하게 수용할 수 있게 되었습니다.

• Causal Linear-RNN prefix scan — 새로운 prefix-scan-causal / prefix-scan-causal-backward 셰이더와 C++ 디스패처, 그리고 Python autograd wrapper를 추가했습니다. grilly.nn.prefix_scan.CausalSequenceMixer는 자기회귀적 인과성(autoregressive causality)을 엄격하게 준수하는 시퀀스 풀링에 대한 드롭인 서브그룹-병렬 대체재입니다.
• nn.Linear, nn.LayerNorm, nn.Embedding을 통한 실제 autograd 구현 — 이 모듈들의 forward 메서드가 이제 numpy 출력을 Variable로 래핑하고, 기존의 backward()를 호출하는 GradFn을 포함하여, loss.backward()가 실제로 레이어 파라미터를 업데이트하도록 했습니다. 이전에는 최적화기 단계(optimizer steps)가 표준 self.weight = nn.Parameter(...) 관용구(idiom)를 사용하는 모든 Module 서브클래스에서 조용히 아무 작업도 하지 않았습니다 (no-op'd).
• Module.__setattr__ 자동 등록 — 이제 Parameter 및 자식 Module 속성 할당이 자동으로 _parameters / _modules를 채웁니다. 이는 표준 PyTorch 관용구이며, 이전에는 조용히 깨져 있었습니다 (모든 서브클래스가 0개의 파라미터를 반환했음).
• .grl 체크포인트 왕복(roundtrip) — torch.save({'model': sd, 'step': N}, path); ck = torch.load(path)가 이제 저장된 내용과 정확히 일치하는 값을 반환합니다 (PyTorch 시맨틱스 준수). 이전에는 로더가 콘텐츠를 고정된 'model' 키 아래에 강제로 래핑했습니다.
• VMA 수정 — BufferPool::allocateBuffer가 이제 preferredFlags 대신 requiredFlags = DEVICE_LOCAL_BIT을 사용하므로, 할당기가 느린 호스트 메모리로 조용히 되돌아가지 않고 실제로 VRAM을 선택합니다.
• Variable.__array__ — numpy 연동. np.matmul(tensor, w) / np.dot(tensor, w) / np.asarray(tensor)가 이제 투명하게 작동합니다.
• PEP 660 편집 가능 설치 수정 — import grilly_core가 이제 최신 편집 가능 설치 환경에서도 작동합니다 (path hook이 패키지 디렉터리를 sys.path에 추가하지 않아, 정상적인 Vulkan 환경의 장치에서도 Vulkan 프로브가 조용히 VULKAN_AVAILABLE = False를 보고했음).

전체 목록은 [아래

태그는 나머지 인과적-RNN(causal-RNN) 학습 검증 데이터가 들어오면 v1.0.0-rc.1로 지정될 것입니다.

Grilly를 사용해야 하는 이유?

• 모든 GPU: Vulkan은 AMD, NVIDIA, Intel, 그리고 Apple(MoltenVK 경유)에서 작동합니다. CUDA 종속성으로부터 자유롭습니다.
• PyTorch와 유사한 API: nn.Module, F.relu, AdamW 등 친숙한 패턴을 새로운 백엔드에 적용했습니다.
• 항상 작동: GPU를 사용할 수 없는 경우 순수 Python numpy로 폴백(fallback)합니다. 동일한 코드로 동일한 결과를 얻습니다.
• 연구 준비 완료: 스파이킹 신경망(Spiking neural networks), 벡터 기호 아키텍처(Vector Symbolic Architectures), 전문가 혼합 모델(Mixture of Experts), 인지 제어기(cognitive controllers), 시간 추론(temporal reasoning) 등 모든 것이 GPU 가속됩니다.
• 가볍습니다: 핵심 의존성은 numpy만 필요합니다. torch, HuggingFace, ONNX를 위한 선택적 추가 기능이 제공됩니다.

설치 방법

옵션 1: Python 전용 (GPU 가속 없음)

pip install grilly

numpy만으로 즉시 작동합니다. GPU, Vulkan SDK, C++ 컴파일러가 필요 없습니다.

옵션 2: Vulkan GPU 가속 사용

Linux / Google Colab (한 줄 명령어)

# 전체 빌드 (~30분 소요 — 검증 레이어 및 모든 SDK 도구 포함)
curl -sSL https://raw.githubusercontent.com/Grillcheese-AI/grilly/main/scripts/install.sh | bash

...

Colab의 경우:

# 권장: Colab 모드 (Vulkan 1.3 + 빠른 빌드 + NVIDIA ICD, ~5분 소요)
!wget -qO- https://raw.githubusercontent.com/Grillcheese-AI/grilly/main/scripts/install.sh | bash -s -- --colab

이 명령어는 시스템 의존성을 설치하고, Vulkan SDK 1.4를 다운로드 및 빌드하며, grilly C++ 확장을 컴파일하고, Python 패키지를 설치합니다. --fast 플래그는 grilly가 필요한 구성 요소(shaderc, loader, headers)만 빌드하고 검증 레이어는 건너뜁니다.

Linux (수동 단계별)

# 1. 시스템 의존성 (Ubuntu/Debian)
sudo apt-get install -y cmake g++ ninja-build pkg-config 
    libxcb-dri3-0 libxcb-present0 libpciaccess0 libpng-dev 
...

Windows

# 1. https://vulkan.lunarg.com/sdk/home 에서 Vulkan SDK 설치 (Windows 인스톨러)
# 2. C++ 워크로드가 포함된 Visual Studio 2022 설치

...

사전 빌드 바이너리 (Windows x64, Python 3.12): 최신 릴리스에서 grilly_core.cp312-win_amd64.pyd를 다운로드하여 grilly 설치 디렉터리에 복사하세요.

macOS

# 1. https://vulkan.lunarg.com/sdk/home#mac 에서 Vulkan SDK 설치
brew install cmake ninja
# 2. 위 리눅스 빌드 단계를 따르세요 (MoltenVK 사용)

설치 확인

import grilly
print(f"grilly {grilly.__version__}")

...

요구 사항

빠른 시작

import numpy as np
from grilly import nn
from grilly.optim import AdamW
...

Autograd

from grilly.nn import Variable, tensor

x = Variable(tensor([1.0, 2.0, 3.0]), requires_grad=True)
...

Functional API

import grilly.functional as F

out = F.linear(x, weight, bias)
...

전체 워크스루는 notebooks/01_getting_started.ipynb를 참조하세요.

기능 (Features)

레이어 (Layers) (100+)

스파이킹 신경망 (Spiking Neural Networks)

GPU 가속 스파이크 동역학을 갖춘 완전한 SNN 프레임워크:

• 뉴런(Neurons): IFNode, LIFNode, ParametricLIFNode
• 대리 기울기(Surrogate gradients): ATan, Sigmoid, FastSigmoid
• 시냅스(Synapses): STPSynapse, DualTimescaleSynapse, SynapseFilter
• 시간 컨테이너(Temporal containers): SeqToANNContainer, MultiStepContainer
• 스파이킹 어텐션(Spiking attention): SpikingSelfAttention, QKAttention, TemporalWiseAttention
• ANN-to-SNN 변환: Converter, VoltageScaler

최적화 도구 (Optimizers)

실험적 모듈 (Experimental Modules)

아키텍처

Python API                    C++ 브릿지                  GPU 셰이더
─────────────                 ──────────                  ───────────
nn.Module 레이어              pybind11 바인딩           231 SPIR-V 커널
... 

3단계 GPU 폴백 (Fallback)

모든 연산은 자동 폴백을 지원합니다:

1. grilly C++ / Vulkan -- 네이티브 컴퓨트 셰이더 (가장 빠름)
2. PyTorch CUDA -- torch가 사용 가능한 경우 (빠름)
3. NumPy CPU -- 항상 사용 가능 (정확함)

동일한 API, 동일한 결과, 다른 속도. 코드는 절대 변경되지 않습니다.

GPU 커널 (231개 연산)

에코시스템 (Ecosystem)

노트북 및 튜토리얼 (Notebooks & Tutorials)

테스트 (Testing)

# 모든 테스트
uv run pytest tests/ -v

...

환경 변수 (Environment Variables)

새로 추가된 기능 (What's New)

v1.0 이전 (현재 main, 0.6.1 이후) {#whats-new-since-061}

실제 워크로드(vsa_lm_v3c_grilly — 곱셈이 없는 FFN + 인과적 Linear-RNN mixer를 사용한 언어 모델링)에 대한 장시간 디버깅 세션에서, 0.6.1 테스트 스위트로는 절대 발견할 수 없었던 일련의 버그와 성능 저하 구간(perf cliffs)을 찾아내고 수정했습니다. 각 수정 사항은 개별적으로는 작지만, 이들이 쌓인 규모가 주요 버전 업데이트를 정당화할 만큼 충분합니다.

성능 — bridge dispatch 개선

• BufferPool::allocateBuffer VMA 수정. preferredFlags를 requiredFlags = DEVICE_LOCAL_BIT로 변경했습니다. 이전 코드는 할당자가 잘못된 힙을 선택했을 때 AMD/Windows 환경에서 느린 호스트 가시성 BAR 메모리로 조용히 폴백(fallback)하는 문제가 있었습니다. 이 수정은 ReBAR가 사용 가능한 경우 Resizable BAR 하에서 memoryType[2] (DEVICE_LOCAL+HOST_VISIBLE+HOST_COHERENT)를 강제하거나, ReBAR가 없을 때는 명확하게 실패하도록 합니다. (cpp/src/buffer_pool.cpp)
• 3가지 유형 버킷 풀 라우팅. acquire / acquireDeviceLocal / acquireReadback이 이제 크기별로 별도의 풀을 가지며, release는 버퍼의 deviceLocal / readback 플래그에 따라 경로를 지정합니다. 이로써 DL(Device Local) 버퍼가 호스트 가시성인 acquire에 의해 잘못 선택되어 mappedPtr=null 상태에서 충돌하는 것을 방지했습니다.
• 모든 주요 연산에 걸친 스테이징 패턴 (

다운로드 단계만으로도 출력 스테이지를 HOST_CACHED 메모리로 이동시키자 749 ms → 2.7 ms로 급감했습니다 (비캐시 WC 읽기 대신 랜덤 읽기를 사용).

• CommandBatch에 transferComputeBarrier() 추가 — 스태징 패턴에서 필요한 양방향 TRANSFER ↔ COMPUTE 메모리 및 실행 장벽이 필요합니다 (기존의 barrier()는 linearBackward의 3단계 인트라-셰이더 장벽을 위해 COMPUTE→COMPUTE 전용으로 유지됩니다).

fp16 + 협력 행렬 GEMM