ONNX Runtime

• ONNX Runtime은 프레임워크에 독립적으로 ML 모델을 추론하는 크로스플랫폼 가속 엔진
• PyTorch·TensorFlow 등에서 학습한 모델을 ONNX 포맷으로 변환해 어디서든 실행하는 런타임
• 그래프 최적화와 Execution Provider로 하드웨어별 가속을 추상화한 추론 엔진
• CPU·GPU·모바일·브라우저(WebGPU/WASM)까지 단일 모델로 배포 가능한 구조

해당 개념이 필요한 이유

• 학습 환경(PyTorch/Python)과 배포 환경(C++/Java/브라우저)이 서로 다름
• 하드웨어마다 최적 추론 방식이 달라 직접 대응하면 유지보수 비용 큼
• 온디바이스 배포에는 경량·고속 추론이 필수

ONNX와 ONNX Runtime은 다르다

ONNX는 모델의 구조와 가중치를 담은 표준 파일 포맷(.onnx)이고, 그 자체로는 실행되지 않는 데이터다. MP3 파일과 음악 플레이어의 관계처럼, ONNX 파일을 실제로 불러와 추론(inference)을 수행하는 실행 엔진이 ONNX Runtime이다. 따라서 “모델을 사용한다”는 것은 ONNX Runtime이 .onnx 파일을 로드해 예측·생성을 수행한다는 의미다.

구분	ONNX	ONNX Runtime
정체	파일 포맷 (.onnx)	그 파일을 읽어 실행하는 엔진
비유	MP3 파일 / PDF 문서	음악 플레이어 / PDF 뷰어
혼자서	실행 못 함 (그냥 데이터)	ONNX 파일을 로드해야 동작

ONNX의 목적 — 학습 환경과 배포 환경의 분리

ONNX(Open Neural Network Exchange)의 핵심 목적은 학습 프레임워크와 실행 환경을 분리(decoupling)하는 것이다. PyTorch나 TensorFlow로 학습한 모델을 ONNX로 변환해 두면, 그 프레임워크가 없는 환경(브라우저·C++ 앱·모바일)에서도 동일한 모델을 그대로 실행할 수 있다.

flowchart LR
    A[PyTorch / TensorFlow<br/>로 학습] -->|export| B[(model.onnx<br/>표준 포맷)]
    B --> C[Python 서버]
    B --> D[Node.js 서버]
    B --> E[브라우저 WebGPU]
    B --> F[모바일 iOS/Android]

모델은 어떻게 만들어지고, 언제 .onnx가 되나

학습된 모델은 기본적으로 .onnx가 아니다. .onnx는 학습이 끝난 뒤 선택적으로 변환해서 만드는 산출물이다.

flowchart LR
    A["① 설계<br/>신경망 구조를 코드로 정의<br/>(PyTorch: nn.Module)"] --> B["② 학습(training)<br/>forward→loss→backprop<br/>가중치 업데이트 반복"]
    B --> C["③ 저장 (네이티브 포맷)<br/>PyTorch: .pt / .safetensors<br/>TF: SavedModel / .h5"]
    C -.선택적 변환.-> D["④ ONNX export<br/>model.onnx"]
    D --> E["⑤ ONNX Runtime으로 추론"]

1. 설계: 신경망 구조(레이어)를 코드로 정의한다 (PyTorch면 nn.Module).
2. 학습: 데이터를 넣어 예측 → 정답과의 오차(loss) 계산 → 역전파(backprop)로 가중치를 수정, 이를 수없이 반복한다.
3. 저장: 학습된 “구조 + 가중치”를 프레임워크 네이티브 포맷으로 저장한다. PyTorch는 .pt/.safetensors, TensorFlow는 SavedModel/.h5다. 이 단계까지는 .onnx가 아니다.
4. ONNX export(선택): 배포·추론을 위해 별도 변환 단계를 거쳐야 .onnx가 된다.

# PyTorch 모델을 ONNX로 변환(export)하는 한 줄
torch.onnx.export(model, example_input, "model.onnx")

safetensors는 ‘가중치’만 담는다 — open weights ≠ open source

safetensors는 학습된 가중치(텐서 = 수많은 숫자)만 담는 파일 포맷이다(pickle과 달리 임의 코드 실행이 없어 “safe”하다). 따라서 이 파일을 받았다고 해서 “어떻게 학습됐는지”까지 알 수 있는 것은 아니다.

• 알 수 있는 것: 가중치 값, 그리고 보통 함께 배포되는 config.json과 공개된 modeling 코드(예: HuggingFace transformers)로 파악하는 모델 구조(architecture). 가중치를 로드하려면 구조를 알아야 하므로 구조는 대체로 공개된다.
• 알 수 없는 것: 학습에 쓴 데이터, 정확한 학습 코드·레시피·하이퍼파라미터, RLHF 등 후처리. 이런 정보는 safetensors에 들어있지 않다.

그래서 Gemma·Llama 같은 모델은 “open weights”(가중치 공개)이지 완전한 “open source”가 아니다. 가중치는 내려받아 쓰고 튜닝할 수 있지만, 어떤 데이터로 어떻게 학습했는지는 기술 보고서(technical report)의 개략적 설명 정도만 공개되며 전체를 재현(reproduce)할 수는 없다. 가중치 + 학습 코드 + 데이터까지 모두 공개하는 OLMo, Pythia 같은 사례가 진짜 “open source”에 가깝다.

비유하면 safetensors는 공부를 끝낸 학생의 ‘머릿속 지식’을 통째로 복사한 것과 같다. 무엇을 아는지(가중치)는 그대로 가져왔지만, 그 학생이 어떤 교재로 어떻게 공부했는지(학습 데이터·과정)는 복사본만 봐서는 알 수 없다.

.onnx에서 튜닝할 수 있나?

없다고 보는 게 맞다. ONNX는 추론에 최적화된 거의 고정된 그래프라 학습/튜닝용이 아니다. 따라서 fine-tuning은 ONNX 파일이 아니라 PyTorch 원본(.safetensors 등)에서 수행하고, 끝난 뒤 다시 ONNX로 re-export한다. Gemma 같은 공개 모델도 원본은 보통 .safetensors로 배포되며, ONNX 버전은 커뮤니티가 변환했거나 직접 export한 별도 산출물이다. 즉 “학습·튜닝은 PyTorch에서, 배포·추론은 ONNX에서”가 일반적인 분업이며, Supertonic도 PyTorch로 학습한 뒤 ONNX로 배포한 사례다.

가중치로 무엇을 재활용하나 — fine-tuning과 distillation

open weights를 받으면 다음을 할 수 있다.

• 그대로 추론: 변환·학습 없이 바로 사용한다.
• Fine-tuning(미세조정): 공개 가중치를 출발점으로 삼아 내 데이터로 추가 학습한다. 처음부터(scratch) 학습하는 것보다 훨씬 적은 데이터·비용으로 내 용도에 맞춘다. 대학 졸업자를 신입으로 뽑아 회사 업무만 단기 교육하는 것과 같다. 실무에서 가장 흔한 재활용 방식이다.
• Knowledge Distillation(지식 증류): 큰 모델(teacher)의 출력을 작은 모델(student)에게 가르쳐 지식을 옮긴다. 박사가 학생을 과외해 비슷한 답을 내게 만드는 셈이다.

“머릿속 지식을 통째로 옮길 수 있나?”에 답하면, 구조가 같은 모델이라면 가중치 파일을 그대로 복사하는 것이 곧 통째 복제다(동일한 ‘뇌’ 복사본). 하지만 더 작거나 다른 구조의 모델로 옮기려면 통째 이식이 아니라 distillation으로 “가르쳐서 흉내내게” 해야 하며, 이는 원본의 근사치다. 기존 지식 위에 내 전문 지식을 얹는 것은 fine-tuning이다.

동작 3단계

1. Graph optimization: 연산 그래프를 최적화한다
2. Hardware partitioning: 그래프를 가속기별 서브그래프로 분할한다
3. Execution Provider: 하드웨어별 라이브러리(CUDA/TensorRT/OpenVINO/CoreML/QNN/WebGPU/WASM)로 가속한다

언어·플랫폼 바인딩

ONNX Runtime은 Python 전용이 아니라 다양한 언어 바인딩을 제공한다. 같은 ONNX 모델 하나를 여러 런타임에서 그대로 실행할 수 있다.

• Python (onnxruntime) — 학습·프로토타이핑에서 가장 많이 사용
• Node.js (onnxruntime-node) — 서버사이드 JavaScript에서 네이티브 추론
• Browser (onnxruntime-web) — WASM·WebGPU로 브라우저 내 추론
• C/C++, C#(.NET), Java, Rust, Swift/Objective-C, React Native 등

엔진은 하나, 바인딩만 여럿

ONNX Runtime은 언어마다 별개의 구현이 있는 것이 아니라, C++로 작성된 단일 코어 엔진이 실제 추론을 담당한다. onnxruntime(Python), onnxruntime-node(Node.js), onnxruntime-web(브라우저) 등은 모두 이 같은 코어를 각 언어에서 호출하기 위한 얇은 바인딩이다. 자동차 엔진은 동일하고 운전대만 언어별로 다른 셈이다. 따라서 Python으로 부르든 Node로 부르든 같은 ONNX 모델에 대해 동일한 추론 결과를 얻는다.

flowchart TD
    subgraph CORE["ONNX Runtime 코어 (C++) — 실제 추론 엔진"]
        E["모델 로드 · 그래프 최적화 · 연산 실행"]
    end
    P["Python 바인딩<br/>(onnxruntime)"] --> E
    N["Node.js 바인딩<br/>(onnxruntime-node)"] --> E
    W["Browser 바인딩<br/>(onnxruntime-web, WASM/WebGPU)"] --> E
    J["Java / C# / Rust ..."] --> E

실행 엔진과 호출 레이어의 관계

ONNX 모델을 실제로 실행하는 것은 C++로 작성·컴파일된 네이티브 엔진(.so/.dll/.dylib)이고, Python·Node 등은 그 엔진을 호출하는 상위 레이어다. 다만 사용자가 C++ 컴파일러나 개발 환경을 따로 준비할 필요는 없다. pip install onnxruntime이나 npm install onnxruntime-node를 하면 미리 빌드된 네이티브 바이너리가 패키지에 함께 설치되어, Python/Node 환경만으로 곧바로 추론이 가능하다. 브라우저처럼 네이티브 바이너리를 올릴 수 없는 환경에서는 같은 C++ 코어를 WebAssembly로 컴파일한 onnxruntime-web을 사용한다.

flowchart TD
    A["① 호출 레이어<br/>내 코드 (Python / Node / Java ...)"] --> B
    B["② 바인딩 레이어<br/>onnxruntime 패키지 (얇은 래퍼)"] --> C
    C["③ 엔진 레이어<br/>C++로 만든 네이티브 바이너리<br/>(.so/.dll/.dylib) — 실제 연산"]
    D[("model.onnx<br/>(데이터/입력)")] -.로드.-> C

Supertonic에서의 역할

• Supertonic의 모든 모듈이 ONNX로 배포되어 GPU 없이 CPU·브라우저에서 실행된다.
• 양자화(quantized) 모델을 함께 제공해 크기·속도를 추가 최적화한다.
• from supertonic import TTS의 TTS 객체가 내부적으로 여러 .onnx 모듈을 ONNX Runtime으로 구동하므로, 사용자는 ONNX 파일을 직접 다루지 않는다.
• Python·Node.js·Browser(WebGPU) SDK를 모두 제공할 수 있는 것도 이 멀티 바인딩 덕분이다.

참고 문서

• ONNX Runtime Documentation
• ONNX 공식 사이트
• 상위 개념: Supertonic 3