How to Fix “Protobuf Parsing Failed” When Loading ONNX Models

ONNX Protobuf 오류 점검 리스트

모델 로딩 중 “Protobuf parsing failed”(프로토버프 파싱 실패) 에러가 뜰 때, 원인부터 해결까지 한 번에 점검할 수 있는 빠른 체크리스트를 정리했다.

왜 생기나?

• 파일 손상/불완전 다운로드: ONNX/모델 파일이 깨짐.

• Export‑Runtime 불일치: 다른 opset, 다른 IR/producer, 다른 ORT 최적화 버전.

• 형식 위반: 그래프/노드 스키마 위배, 중복 이름, 외부 데이터 분리(.data) 누락.

• 압축·전송 문제: Git LFS 미적용, 텍스트 변환(EOL), HTTP 중단 다운로드 등.

10분 해결 체크리스트 (상위에서부터 순서대로)

1. 무결성 확인

• 원본과 체크섬 대조:

• Git LFS 사용 모델이면 git lfs pull로 실제 바이너리 받았는지 확인.

1. ONNX 형식 검사

• 로컬에서 즉시 검사:

• 외부 데이터가 분리된 모델이면 .onnx와 .data(또는 folder) 경로가 함께 있는지 확인.

1. Export 재수행 (최소화 전략)

• 최소 opset으로 재수출(opset을 높이면 파서가 모르는 연산 등장 가능).

• 불필요한 커스텀/불안정 연산 제거(가능하면 표준 연산으로 fold).

• 동적축/shape inference 실패 시, 가능한 부분은 정적화 후 export.

• PyTorch → ONNX 예시:

1. 런타임/최적화 버전 일치

• ORT 최적화된 모델(ort optimized)이라면 동일한 ORT 메이저/마이너에서 사용:
• 예: onnxruntime==1.23.2로 최적화한 모델은 런타임도 1.23.x 권장.

• 그래프 최적화 끄고 먼저 로딩 테스트:
실패 시:

1. IR/도메인 호환성 점검

• model.ir_version, opset_import 확인해 런타임이 지원하는 범위인지 확인.

• 커스텀 도메인(com.example::Op)이 있으면 해당 EP/커스텀 오퍼레이터가 로드되는지 점검.

1. 단계적 이분법

• 같은 모델을 onnx.shape_inference, onnxsim으로 간소화 후 재검:

• 실패 지점 노드명을 추출해 문제 연산을 pinpoint.

1. 전송/압축 재점검

• S3/HTTP 전송 시 멱등 다운로드, Content-Length 일치, 중간 프록시 변환 금지.

• ZIP 전송 시 텍스트모드 변환(EOL) 방지, 바이너리 모드로 압축.

자주 맞닥뜨리는 함정

• GitHub에서 원클릭 다운로드로 LFS 포인터만 받아서 파일 수KB짜리인 경우.

• 외부 데이터 분리 모델인데 .data 파일 누락.

• opset 18+ 실험 연산을 낮은 버전 ORT로 열기.

• Float16/8 양자화 모델인데 대상 EP가 미지원.

자동화 스크립트 스니펫 (CI에 넣어 빠르게 거르기)

• 실패하면 CI 빨간불로 즉시 감지.

너의 환경(xvoice/ONNX, CPU‑only EP) 기준 빠른 가이드

• 우선 onnx.checker 통과 여부와 onnxsim 간소화 결과 확인.

• ORT 1.23.2로 최적화했다면 배포 타겟도 1.23.x로 고정(컨테이너/서버 공통).

• ARM/Windows 교차 빌드 시 ORT DLL/SO 불일치 주의(SONAME, rpath, PATH).

• 대용량 모델은 외부데이터 모드 사용 시 .data 동봉 및 상대경로 유지.