ONNX 모델과 입출력 계약
관련 기초 개념
개요
ONNX 모델의 이름·자료형·형상·전처리 계약을 확인해 추론한다.
먼저 로컬·원격 추론과 실행 환경의 핵심 개념을 확인하세요.
핵심 개요
ONNX 모델을 C++에서 실행하려면 입력 이름·자료형·형상·차원 의미와 전처리 계약을 알아야 합니다. 같은 원소 개수라도 차원 순서·정규화·토크나이저가 다르면 다른 입력이 됩니다.
Ort::Session으로 모델을 준비하고 메타데이터를 확인한 뒤 입력 텐서를 만들어 실행합니다. 동적 차원은 실제 입력에서 결정하고 결과 이름·자료형·범위를 검사합니다.
필요한 용어
- Tensor shape: 각 축의 크기와 순서를 나타내는 형상
- 전처리 계약: 원자료를 모델 입력 수치로 바꾸는 정확한 규칙
작동 과정
- 모델·opset·지원 연산·입출력 정보를 확인합니다.
- 전처리와 형상·자료형을 맞춰 텐서를 만듭니다.
- 작은 기준 입력의 결과를 원본 구현과 비교합니다.
풀이 예제
아래 입력과 기록은 직접 만든 교육용 가상 자료입니다.
입력·조건
입력 형상은 1×3×224×224인데 앱은 1×224×224×3 순서의 같은 수를 전달합니다.
판단·결과
원소 수만 같아도 채널 축 의미가 달라 잘못된 추론이 될 수 있습니다.
이렇게 판단한 이유
텐서는 숫자 배열뿐 아니라 축 의미와 전처리의 계약을 포함합니다.
로컬 실행 예제
Python 3.12. pip install onnx==1.23.2 onnxruntime==1.31.0 numpy 후 python create_onnx_model.py
python -m pip install onnx==1.23.2 onnxruntime==1.31.0 numpy
python create_onnx_model.py"""Construct and actually execute a deterministic CPU model: y = 2*x + 1."""
from pathlib import Path
import numpy as np
import onnx
from onnx import TensorProto, helper, numpy_helper
import onnxruntime as ort
root = Path(__file__).resolve().parent
x = helper.make_tensor_value_info('x', TensorProto.FLOAT, [1,3])
y = helper.make_tensor_value_info('y', TensorProto.FLOAT, [1,3])
graph = helper.make_graph([
helper.make_node('Mul',['x','two'],['scaled']),
helper.make_node('Add',['scaled','one'],['y'])], 'learning-linear', [x], [y],
[numpy_helper.from_array(np.array([2],np.float32),'two'), numpy_helper.from_array(np.array([1],np.float32),'one')])
model = helper.make_model(graph, opset_imports=[helper.make_opsetid('',18)])
model.ir_version = 9
onnx.checker.check_model(model)
onnx.save(model, root/'linear.onnx')
session = ort.InferenceSession(str(root/'linear.onnx'), providers=['CPUExecutionProvider'])
actual = session.run(['y'], {'x':np.array([[1,2,3]],np.float32)})[0]
np.testing.assert_allclose(actual, [[3,5,7]])
try:
session.run(['y'], {'x':np.array([[1,2]],np.float32)})
except ort.capi.onnxruntime_pybind11_state.InvalidArgument:
pass
else:
raise AssertionError('invalid shape accepted')
print(f'PASS: ONNX {onnx.__version__}, ORT {ort.__version__}; output [[3,5,7]], wrong shape rejected')기대 결과: linear.onnx 생성, CPU 결과 [[3,5,7]], 잘못된 형상 거절
2026-10-21 로컬 환경에서 실행했습니다. 가상 자료·소형 CPU 예제의 동작 검사이며 실제 업무 모델의 품질·클라우드·GPU·Office 제품 연동 검증은 아닙니다.
흔한 실패와 복구
모델 파일만 복사해 입력 의미를 추측하지 않습니다. 전처리·출력 라벨·지원 연산·버전을 함께 배포합니다.
확인 문제
원소 수가 같아도 추론이 틀릴 수 있는 이유는?
- 모든 텐서는 문자열이어서
- ONNX는 입력 이름이 없어서
- 축 순서·전처리·자료형의 의미가 다를 수 있어서
풀이 기록 기능을 불러오는 중…
해설 보기
정답: C. 축 순서·전처리·자료형의 의미가 다를 수 있어서
축 순서·전처리·자료형의 의미가 다를 수 있어서 모델 파일만 복사해 입력 의미를 추측하지 않습니다. 전처리·출력 라벨·지원 연산·버전을 함께 배포합니다.
참고 자료
- ONNX Runtime: Ort::Session — 세션 생성·입출력 정보·실행 계약.
- ONNX Runtime: C++ — C++ API와 모델 추론 진입점.
자료 확인: 2026-10-21. 사례·문항·실습은 자체 제작했습니다. 외부 서비스 호출과 실제 모델 품질 측정은 학습자가 별도 환경에서 수행합니다.
직접 적용하기
교육용 가상 상황
ONNX 문장 분류 모델을 붙이려 합니다. 입력 이름·정수 타입·토큰 길이·마스크·출력 라벨 검사를 설계하세요.
ONNX 모델의 이름·자료형·형상·전처리 계약을 확인해 추론한다. 판단 근거와 검증할 결과를 적으세요.
답안 저장 기능을 불러오는 중…
검증 기준과 해설 보기
- 모델 메타데이터와 토크나이저 버전을 확인한다
- 이름·타입·축·마스크 계약을 맞춘다
- 기준 입력을 원본 모델과 비교한다
모델 입력의 이름·int64 등 실제 자료형·동적 축을 확인하고 같은 토크나이저·패딩·절단·마스크를 적용합니다. 출력 점수의 라벨 순서와 후처리를 명세에 연결합니다. 정상·빈 입력·최대 길이에서 원본 구현과 허용 오차·분류를 비교합니다.
복습하기
- 모델 파일 외에 무엇이 필요한가요?
- 동적 차원은 어떻게 다루나요?
- 첫 검증 입력은 어떻게 고르나요?
답변 확인 기준
- 모델 파일 외에 무엇이 필요한가요?
전처리·라벨·런타임·버전·입출력 계약입니다.
- 동적 차원은 어떻게 다루나요?
모델 계약과 현재 입력에 맞게 실제 크기를 결정합니다.
- 첫 검증 입력은 어떻게 고르나요?
결과를 대조할 수 있는 작은 기준 입력과 경계 입력을 고릅니다.