How to Prevent ONNX Runtime C API Version Mismatch Crashes

ORT API 버전 고정으로 ABI 충돌 방지

왜 중요한가

• ONNX Runtime은 C API를 버전된 함수 테이블(vtable) 로 노출한다.

• 앱이 컴파일한 헤더의 API 버전과 배포된 libonnxruntime 의 내부 버전이 다르면, 심각한 UB나 크래시가 난다.

• 그래서 컴파일 시점에 ORT_API_VERSION을 정의하고, 시작 시 OrtApiBase::GetApi(ORT_API_VERSION) 로 정확한 버전 테이블을 받아 써야 한다. 지원 안 하면 nullptr 로 알려주므로 깨끗하게 실패 처리 가능.

최소 패턴 (C 예시)

실전 체크리스트

• 컴파일 플래그: DORT_API_VERSION=<헤더 버전> 을 빌드 시스템(CMake/Makefile)에 고정.

• 단일 진입점 사용: 함수들은 반드시 g_ort->Function(...) 형태로 호출(헤더에 직접 심볼 링크 X).

• 버전 불일치 처리: GetApi() 가 NULL이면 “지원 안 함”으로 사용자 메시지 후 종료.

• 런타임 교체 시 안전성: 같은 앱이라도 서버에 다른 버전의 libonnxruntime 가 배포될 수 있으므로 위 패턴이 필수.

• 플러그인/멀티모듈: 공용 싱글턴 g_ort 를 노출하거나, 초기화 함수로 주입해 중복 초기화 방지.

CMake 예

흔한 실수

• 헤더만 업데이트하고 libonnxruntime 는 예전 버전을 쓰는 경우.

• OrtGetApiBase()/GetApi() 를 건너뛰고 헤더의 심볼을 직접 부르는 경우.

• 서브모듈이 각자 초기화하여 서로 다른 OrtApi* 를 들고 다니는 경우.