다른 분석기 대비 무중단 사용자 사전의 가치

대부분의 한국어 형태소 분석기는 사용자 사전을 바꾸려면 사전을 다시 빌드하거나 분석기를 재시작해야 합니다. 바른은 사용자 사전 디렉토리의 파일 변경을 실시간으로 감지해, 사전 파일이 바뀌면 서버를 멈추지 않고 즉시 반영합니다. 운영 서비스에서 도메인 용어가 계속 늘어나는 환경이나 여러 고객·팀이 사전을 따로 쓰는 멀티테넌시 환경에서 이 무중단 갱신은 분석 품질과 운영 안정성에 큰 차이를 만듭니다.

사전 갱신 방식 비교

항목	바른	사전 재빌드형 분석기
사전 반영	파일 변경 즉시 무중단 reload	재컴파일·재시작 필요
감시 방식	파일 변경 즉시 감지 + 60초 주기 점검	수동 배포
다운타임	없음	재시작 동안 발생 가능
다중 사전	`custom_dict_names`로 동시 지정·우선순위	보통 단일 사전
충돌 검사	`CheckConflict`로 중복·충돌 사전 점검	별도

무중단 갱신이 중요한 이유

분석 서버를 재시작하면 그동안 요청이 끊기거나 지연됩니다. 사전을 자주 갱신해야 하는 서비스라면 재시작은 누적된 운영 부담이 됩니다. 바른은 파일을 바꾸기만 하면 서버가 알아서 다시 읽어 들이므로, 사전을 운영 중에도 안전하게 키워갈 수 있습니다.

사용자가 직접 파일을 변경하나요?

사용자 사전을 변경하는 것은 CustomDictionaryService(UpdateCustomDictionary 등) API를 통해서 이뤄집니다. 서버의 사전 디렉토리에 있는 파일은 서버가 관리하는 바이너리 형식이므로, 사용자가 그 파일을 직접 텍스트로 편집하지는 않습니다. 단어 목록은 사용자 쪽 소스(예 Git으로 관리하는 목록)에 두고 API로 반영하는 흐름을 권장합니다. 사용자 사전을 여러 머신에서 공유할 수 있어, 바른 서비스를 여러 개 운영하는 경우 한 서버에만 사전을 변경해도 다른 모든 서버에 거의 실시간으로 반영됩니다.

어떻게 동작하나

바른은 사용자 사전 디렉토리에서 파일 생성·수정·삭제(Write/Create/Remove)를 감시합니다. 변경이 감지되면 사전을 다시 로드하고, 보조로 60초 주기 모니터링도 함께 돌려 누락을 막습니다. 무중단 갱신의 설정과 동작은 사용자 사전 실시간 반영에서 더 자세히 다룹니다.

graph TD
  EDIT[사전 파일 수정] --> WATCH[파일 변경 감지];
  WATCH --> RELOAD[무중단 reload];
  RELOAD --> READY[다음 요청부터 반영];
  TIMER[60초 주기 모니터링] --> RELOAD;

등록할 수 있는 사용자 사전 종류도 다양합니다.

사전	대상
`np_set`	고유명사(NP)
`cp_set`	복합명사(CP)
`cp_caret_set`	복합명사 분리 지점 표시(CP^)
`vv_set`	동사(VV)
`va_set`	형용사(VA)
`mm_set`	관형사(MM)
`mag_set`	부사(MAG)
`ic_set`	감탄사(IC)

멀티테넌시: 여러 사전을 동시에

바른은 분석 요청마다 custom_dict_names로 여러 사전을 동시에 지정할 수 있고, 먼저 지정한 사전이 우선합니다. 고객사별·도메인별로 사전을 분리해두고 요청 시 필요한 조합을 골라 쓸 수 있어, 하나의 서버로 여러 테넌트를 다루기 좋습니다. 사용자 사전 전반은 사용자 사전 살펴보기에서 정리합니다.

또한 CheckConflict로 같은 표제어가 여러 사전(NP/CP/CP^/VV/VA)에 동시에 들어가 충돌하는지, 같은 사전 안에 중복이 있는지 미리 점검할 수 있습니다. 사전이 커질수록 이런 점검이 운영 품질을 지켜줍니다.

비교 시 유의

다른 분석기도 사용자 사전을 지원하지만, 적용 방식(재빌드 여부)·다중 사전·충돌 검사 지원은 도구마다 다릅니다. 구체 동작은 각 도구의 버전·문서를 확인하세요. 이 문서는 바른의 동작을 기준으로 설명합니다.

자주 묻는 질문

Q. 사전을 바꾸면 서버를 재시작해야 하나요?

아니요. 바른은 사전 디렉토리의 파일 변경을 실시간으로 감지해 파일이 바뀌면 무중단으로 다시 읽어 들입니다. 재시작 없이 다음 요청부터 반영됩니다.

Q. 고객사마다 다른 사전을 쓸 수 있나요?

네. 요청마다 custom_dict_names로 사용할 사전을 여러 개 지정할 수 있고, 먼저 지정한 사전이 우선합니다. 하나의 서버로 여러 테넌트의 사전을 분리해 운영할 수 있습니다.

Q. 사전끼리 충돌하면 어떻게 되나요?

CheckConflict로 사전 내 중복과 사전 간 충돌을 미리 점검할 수 있습니다. 같은 표제어가 여러 품사 사전에 동시에 있으면 충돌로 보고해, 등록 전에 바로잡을 수 있습니다.

Q. 사전 파일을 직접 텍스트로 편집하면 되나요?

아니요. 서버의 사전 디렉토리 파일은 서버가 관리하는 바이너리 형식이라 직접 편집하지 않습니다. 단어 목록은 사용자 쪽 소스(예 Git으로 관리하는 목록)에 두고 CustomDictionaryService의 UpdateCustomDictionary API로 반영합니다. API로 갱신하면 바른이 변경을 감지해 무중단으로 다음 요청부터 적용합니다.