첫 기동에서 모델을 내려받지 못할 때

바른은 형태소 분석에 쓰는 모델과 사전을 설치 파일에 담지 않고, 서버를 처음 실행할 때 자동으로 내려받습니다. 그래서 설치 직후 모델 폴더가 비어 있는 것은 정상이고, 첫 기동에서 다운로드가 막히면 서버가 분석을 시작하지 못합니다. 이 문서로 하나씩 점검해봐요.

증상

설치는 끝났는데 서버가 기동 중에 멈추거나, 모델을 준비하지 못했다는 오류로 종료됩니다.
모델이 저장되는 곳(설치 폴더의 var/models)이 비어 있거나 일부 파일만 있습니다.
분석을 요청하면 서버가 아직 준비되지 않았다는 응답이 옵니다.
도커에서 컨테이너를 다시 만들 때마다 시작이 오래 걸립니다(모델을 매번 다시 받는 경우).

먼저 기다려 보세요

첫 기동에서는 수백 MB를 내려받습니다. 네트워크 상태에 따라 수십 초에서 몇 분이 걸릴 수 있으니, 바로 실패로 판단하지 말고 기동 로그가 진행되는지 잠시 지켜보세요.

원인

원인	설명
바깥으로 나가는 연결 차단	방화벽·프록시가 외부 HTTPS 접속을 막아 파일을 받지 못함
이름 풀이(DNS) 실패	내부망 DNS가 외부 주소를 풀지 못함
디스크 여유 부족	모델·사전을 저장할 공간이 부족함
쓰기 권한 부족	서버를 실행하는 계정이 데이터 영역(`var`)에 쓸 수 없음
도커 볼륨 미마운트	`var`를 볼륨으로 붙이지 않아 컨테이너를 다시 만들 때마다 처음부터 받음
폐쇄망	애초에 외부 접속이 불가능한 환경

해결

기동 로그를 보세요. 어디에서 멈췄는지가 가장 빠른 단서입니다. 연결 실패, 권한 오류, 디스크 부족은 로그 메시지로 구분됩니다.
바깥으로 나가는 연결을 확인하세요. 서버가 설치된 호스트에서 외부 HTTPS(TCP 443) 접속이 되는지 확인합니다. 방화벽이나 프록시를 쓰는 환경이라면 storage.googleapis.com 으로 나가는 접속을 허용해 주세요.
```
curl -sSI https://storage.googleapis.com | head -n 1
```
```
curl.exe -sSI https://storage.googleapis.com | Select-Object -First 1
```
디스크 여유와 쓰기 권한을 확인하세요. 모델·사전은 수백 MB이므로 2 GB 이상 여유를 권장합니다. 서버를 실행하는 계정이 설치 폴더의 var 아래에 쓸 수 있어야 합니다.
도커라면 데이터 영역을 볼륨으로 붙이세요. -v ~/bareun/var:/bareun/var 마운트가 있으면 내려받은 모델이 호스트에 남아, 컨테이너를 다시 만들어도 다시 받지 않습니다.
```
mkdir -p ~/bareun/var
docker run -d -p 5656:5656 -v ~/bareun/var:/bareun/var bareunai/bareun:latest
```
다시 시작해 보세요. 원인을 고친 뒤 서버를 다시 켜면 받지 못한 파일만 이어서 내려받습니다. 이미 받아 둔 파일은 다시 받지 않습니다.

다시 설치할 필요는 없습니다

모델은 설치 파일에 들어 있지 않으므로, 모델 폴더가 비어 있다는 것이 설치가 깨졌다는 뜻은 아닙니다. 재설치를 반복해도 같은 상태가 되니, 연결·권한·디스크를 먼저 확인하세요. ONNX 런타임 라이브러리 자체가 문제인 경우는 ONNX 런타임 로드 실패 점검을 보세요.

폐쇄망에 설치했다면

인터넷이 닿지 않는 망에서는 서버가 모델을 내려받을 수 없습니다. 이때는 모델을 미리 준비해 데이터 영역에 놓아 두면 서버가 그대로 사용합니다. 준비 방법과 파일 구성은 환경에 따라 다르므로 모델 업데이트를 확인하시고, 필요하면 helpdesk@bareun.ai 로 문의해 주세요.

예방·팁

여러 대에 설치할 예정이라면, 한 대에서 첫 기동을 마친 뒤 데이터 영역을 그대로 복사해 두면 나머지 서버의 첫 기동이 빨라집니다.
도커·쿠버네티스에서는 데이터 영역을 반드시 지속 볼륨으로 두세요. 컨테이너를 자주 다시 만드는 환경일수록 재다운로드 비용이 커집니다.
새 모델로 바꾸는 방법은 모델 업데이트에 정리되어 있습니다.

자주 묻는 질문

Q. 설치했는데 모델 폴더가 비어 있어요. 설치가 잘못된 건가요?

아닙니다. 바른은 모델을 설치 파일에 담지 않고 첫 기동에 내려받습니다. 서버를 한 번 켜고 기동 로그가 끝날 때까지 기다려 보세요.

Q. 첫 기동에 인터넷 연결이 꼭 필요한가요?

네, 모델을 내려받기 위해 바깥으로 나가는 HTTPS 연결이 한 번 필요합니다. 그 뒤에는 내부망만으로 동작합니다. 폐쇄망이라면 모델을 미리 준비해 두어야 합니다.

Q. 다운로드가 중간에 끊겼습니다. 처음부터 다시 받나요?

이미 받아 둔 파일은 다시 받지 않습니다. 서버를 다시 켜면 빠진 파일만 이어서 내려받습니다.

Q. 도커에서 컨테이너를 다시 만들 때마다 모델을 또 받습니다.

데이터 영역이 마운트되지 않아 내려받은 모델이 컨테이너와 함께 사라지는 경우입니다. -v ~/bareun/var:/bareun/var처럼 볼륨을 붙여 주세요.