Safe Initialization Pattern for ONNX Runtime C API

ONNX Runtime API 버전 고정으로 ABI 안정화

ONNX Runtime의 C API를 쓸 때는 “요청한 API 버전과 런타임의 실제 버전이 맞는지”를 먼저 확인해야 한다.

• OrtGetApiBase()->GetApi(uint32_t version)으로 원하는 버전의 OrtApi 함수 테이블 포인터를 얻는다. 요청한 버전을 런타임이 지원하지 않으면 nullptr를 돌려주므로 반드시 널 체크 후 조기 종료하는 게 안전하다. (ONNX Runtime)

• 헤더 쪽 버전 상수는 ORT_API_VERSION이며, 보통 “헤더가 더 새롭고 런타임이 더 옛날”일 때 GetApi가 nullptr가 된다. 이런 상황은 C API 함수 포인터 레이아웃(ABI)이 어긋났을 가능성이 있으니 예외로 넘기지 말고 즉시 실패 처리하는 편이 좋다. (Gitee)

• 참고로 GetVersionString()으로 현재 로딩된 onnxruntime 라이브러리 버전(예: "1.18.x")을 읽어 로그에 남길 수 있다. (ONNX Runtime)

빠른 체크리스트

• 빌드/런타임 매칭: 배포 패키지에 포함된 onnxruntime.dll/.so가 헤더와 같은 메이저/마이너 라인을 쓰는지 확인. GetApi 널이면 즉시 중단. (GitHub)

• 초기화 순서: C++ 래퍼(onnxruntime_cxx_api.h)를 쓰더라도 내부적으로 위 C API 포인터를 잡으니, 전역 초기화 시점 문제를 피하고 예외 메시지를 확인하자. (ONNX Runtime)