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`가 서버가 모델을 받아 두는 위치를 가리키지 않음

모델 파일이 아직 없는 것은 정상일 수 있습니다

바른은 설치 파일에 모델을 담지 않고 처음 실행할 때 내려받습니다. 그래서 설치 직후 modelPath 아래가 비어 있는 것은 정상입니다. 모델을 내려받지 못해 기동이 멈춘 경우라면 첫 기동에서 모델을 내려받지 못할 때 문서를 보세요. 이 문서는 모델은 갖춰졌는데 ONNX 런타임 쪽에서 실패하는 경우를 다룹니다.

해결

libPath를 확인하세요. bareun.json의 libPath는 ONNX 런타임 라이브러리가 들어 있는 디렉토리를 가리킵니다. 기본값은 보통 ${BAREUN_ROOT}/lib이며, 굳이 바꿀 필요가 없는 값이에요. 변경했다면 실제 라이브러리 위치와 맞는지 확인하세요.
```
{
  "libPath": "${BAREUN_ROOT}/lib",
  "modelPath": "${BAREUN_ROOT}/var/models",
  "executionProvider": {
    "provider": "cpu"
  }
}
```
라이브러리가 실제로 있는지 보세요. 플랫폼별 ONNX 런타임 파일이 libPath 아래에 있어야 합니다. 설치 패키지가 깨졌거나 일부만 복사됐다면 다시 설치하세요.
executionProvider를 환경에 맞추세요. GPU 환경이 아니라면 cpu로 두는 게 가장 안전합니다. gpu로 두었는데 드라이버·런타임이 갖춰지지 않으면 초기화에 실패할 수 있어요.
모델 경로를 확인하세요. modelPath(기본 ${BAREUN_ROOT}/var/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}/var/models) 아래에 seg-model.onnx(분절)와 tag-model.onnx(품사 태깅)가 모두 있는지 확인하세요. 모델은 설치 파일에 들어 있지 않고 첫 기동에 내려받으므로, 파일이 없다면 다시 설치할 것이 아니라 다운로드가 끝났는지를 봐야 합니다 — 첫 기동에서 모델을 내려받지 못할 때 문서를 참고하세요.

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

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