ONNX 런타임 로드 실패

Q: 바른에서 ONNX 런타임 로드에 실패하는 원인은 무엇인가요?

bareun.json의 libPath가 가리키는 위치에 ONNX 런타임 라이브러리가 없거나, 환경이 지원하지 않는 executionProvider를 지정했을 때가 가장 흔합니다. modelPath 아래에 seg-model.onnx, tag-model.onnx 같은 모델 파일이 없는 경우도 원인이 됩니다.

Q: ONNX 런타임 로드 실패를 어떻게 점검하나요?

먼저 executionProvider를 cpu로 두고 서버가 기동하는지 확인하세요. 그 다음 ONNX 런타임 라이브러리가 들어 있는 libPath와, modelPath 아래 seg-model.onnx·tag-model.onnx 모델 파일의 존재 여부를 점검하고, GPU가 필요하면 단계적으로 설정을 적용하면 원인을 좁힐 수 있습니다.

Q: seg-model.onnx 세션 생성 단계에서 서버가 죽어요.

modelPath(기본 BAREUN_ROOT/models) 아래에 seg-model.onnx와 tag-model.onnx가 모두 있는지 확인하세요. 파일이 없거나 일부만 복사됐다면 설치 패키지가 불완전한 것이므로 다시 설치하면 됩니다. ONNX 런타임 라이브러리가 들어 있는 libPath도 함께 점검하세요.

Q: CUDA나 CoreML 실행 프로바이더 초기화 오류는 어떻게 해결하나요?

환경이 지원하지 않는 executionProvider를 지정했을 때 발생합니다. 먼저 executionProvider를 cpu로 두고 서버가 정상 기동하는지 확인한 뒤 GPU 설정을 단계적으로 적용하세요. GPU가 CPU로 폴백되는 현상과 CUDA/cuDNN 버전 불일치 문제는 별도 문서에서 자세히 다룹니다.

ONNX 런타임 로드 실패 점검

서버를 켰는데 모델 로딩 단계에서 실패하나요? 바른은 형태소 분석에 ONNX 런타임을 사용하므로, 런타임 라이브러리 경로(libPath)나 실행 프로바이더 설정이 어긋나면 시작하지 못합니다. 이 문서로 하나씩 점검해봐요.

증상

서버 기동 중 ONNX 런타임 라이브러리를 찾지 못하거나 로드할 수 없다는 오류로 종료됩니다.
seg-model.onnx/tag-model.onnx 세션 생성 단계에서 실패합니다.
실행 프로바이더(예: CUDA/CoreML) 초기화 오류가 보입니다.

원인

바른은 ONNX 런타임 동적 라이브러리를 libPath 경로에서 찾아 로드하고, 그 위에서 seg-model.onnx(분절)와 tag-model.onnx(품사 태깅) 세션을 만듭니다. 다음이 어긋나면 실패해요.

원인	설명
`libPath` 경로 오류	ONNX 런타임 라이브러리가 있는 위치가 잘못됨
라이브러리 누락	플랫폼별 ONNX 런타임 파일이 패키지에 없음
`executionProvider` 불일치	환경이 지원하지 않는 프로바이더 지정
모델 경로 오류	`modelPath` 아래에 모델 파일이 없음

해결

libPath를 확인하세요. bareun.json의 libPath는 ONNX 런타임 라이브러리가 들어 있는 디렉토리를 가리킵니다. 기본값은 보통 ${BAREUN_ROOT}/lib이며, 굳이 바꿀 필요가 없는 값이에요. 변경했다면 실제 라이브러리 위치와 맞는지 확인하세요.
```
{
  "libPath": "${BAREUN_ROOT}/lib",
  "modelPath": "${BAREUN_ROOT}/models",
  "executionProvider": "cpu"
}
```
라이브러리가 실제로 있는지 보세요. 플랫폼별 ONNX 런타임 파일이 libPath 아래에 있어야 합니다. 설치 패키지가 깨졌거나 일부만 복사됐다면 다시 설치하세요.
executionProvider를 환경에 맞추세요. GPU 환경이 아니라면 cpu로 두는 게 가장 안전합니다. gpu로 두었는데 드라이버·런타임이 갖춰지지 않으면 초기화에 실패할 수 있어요.
모델 경로를 확인하세요. modelPath(기본 ${BAREUN_ROOT}/models) 아래에 seg-model.onnx, tag-model.onnx가 있는지 보세요. 없으면 패키지가 불완전한 것입니다.

설정 파일 오타 주의

bareun.json은 서버가 그대로 읽어들이는 JSON입니다. 키 이름이나 경로에 오타가 있으면 서버가 동작하지 않습니다. 수정 전 원본을 백업하는 습관을 들이세요.

예방·팁

우선 executionProvider를 cpu로 두고 서버가 정상 기동하는지 확인한 뒤, GPU 설정을 단계적으로 적용하면 원인을 좁히기 쉽습니다.
GPU에서 CPU로 자동 전환되는 현상은 GPU 실행이 CPU로 떨어질 때, CUDA 버전 문제는 CUDA/cuDNN 버전 불일치 문서를 참고하세요.

자주 묻는 질문

Q. ONNX 런타임 로드 실패는 보통 무엇 때문인가요?

libPath가 가리키는 위치에 ONNX 런타임 라이브러리가 없거나, 환경이 지원하지 않는 executionProvider를 지정했을 때가 가장 흔합니다. 모델 파일(seg-model.onnx, tag-model.onnx) 누락도 원인이 됩니다.

Q. libPath는 어떻게 설정해야 하나요?

bareun.json의 libPath는 ONNX 런타임 라이브러리 디렉토리를 가리키며 기본값(보통 ${BAREUN_ROOT}/lib)을 그대로 쓰면 됩니다. 임의로 옮겼다면 실제 라이브러리 위치와 일치시키세요.

Q. 모델 세션 생성에서 실패해요. 무엇을 봐야 하나요?

modelPath(기본 ${BAREUN_ROOT}/models) 아래에 seg-model.onnx(분절)와 tag-model.onnx(품사 태깅)가 모두 있는지 확인하세요. 파일이 없거나 일부만 복사됐다면 설치 패키지가 불완전한 것이니 다시 설치하면 됩니다.

Q. CUDA/CoreML 같은 실행 프로바이더 초기화 오류가 나요.

환경이 지원하지 않는 executionProvider를 지정했을 때 생깁니다. 먼저 cpu로 두고 서버가 기동하는지 확인한 뒤 GPU 설정을 단계적으로 적용하세요. GPU가 CPU로 떨어지는 현상은 GPU 폴백, 버전 문제는 CUDA/cuDNN 버전 불일치 문서를 참고하세요.

도움이 되었나요?