사용자 사전이 반영되지 않을 때

사용자 사전에 단어를 등록했는데 분석 결과가 그대로인가요? 대부분은 사전 이름 지정이 빠졌거나, 사전 종류가 맞지 않거나, 사전 간 충돌이 원인입니다. 이 문서로 차근차근 짚어봐요.

증상

UpdateCustomDictionary로 단어를 등록했는데도 형태소 분석 결과에서:

• 등록한 단어가 여전히 NA/UNK로 나오거나,
• out_of_vocab가 IN_CUSTOM_DICT가 아니라 OUT_OF_VOCAB 그대로이거나,
• custom_dict_name이 비어 있습니다.

원인

세 가지를 의심하세요.

해결

1. 분석 요청에 custom_dict_names를 지정하세요. 사전을 만들었다고 자동 적용되지 않습니다. 요청마다 사용할 사전 이름을 명시해야 해요. 여러 개를 줄 수 있고, 먼저 지정한 사전이 우선합니다.

   복사

   {
     "document": { "content": "바른은 한국어 형태소 분석기입니다.", "language": "ko_KR" },
     "custom_dict_names": ["my-domain", "company-names"]
   }
   

2. 사전 종류가 맞는지 확인하세요. 단어 성격에 맞는 DictSet에 넣어야 합니다.

   DictSet	용도
   np_set	고유명사(NP)
   cp_set	복합명사(CP)
   cp_caret_set	복합명사 분리(^로 분리 지점 표시)
   vv_set	동사(VV)
   va_set	형용사(VA)
   mm_set / mag_set / ic_set	관형사 / 부사 / 감탄사

3. 충돌을 검사하세요. CheckConflict로 같은 사전 내 중복(duplicated)과 사전 간 충돌(conflict)을 확인합니다. 같은 표제어가 NP/CP/CP^/VV/VA에 동시에 있으면 충돌로 보고되며, 의도한 한 종류만 남기는 게 좋습니다.

4. 갱신이 반영됐는지 확인하세요. 사용자 사전은 CustomDictionaryService API로 관리하며, 서버의 사전 디렉토리에 놓이는 파일은 바이너리(서버 관리 형식)입니다. UpdateCustomDictionary로 변경하면 바른이 사전 디렉토리의 파일 변경(추가·수정·삭제)을 실시간으로 감지하고 60초 주기로도 점검해 무중단 reload합니다. 변경 직후 반영이 안 보이면 잠시 기다렸다가 다시 분석해보세요.

예방·팁

• 등록이 잘 됐는지는 분석 결과 형태소의 out_of_vocab가 IN_CUSTOM_DICT로 바뀌고 custom_dict_name에 사전 이름이 채워지는지로 확인할 수 있어요.
• index.dup.txt는 감시 대상에서 제외되므로 직접 수정하지 마세요.

자주 묻는 질문

Q. 사전에 등록만 하면 자동으로 적용되나요?

아니요. 분석 요청마다 custom_dict_names에 사용할 사전 이름을 지정해야 적용됩니다. 여러 개를 지정할 수 있고 먼저 지정한 사전이 우선합니다.

Q. 사전을 바꿨는데 서버를 재시작해야 하나요?

재시작할 필요 없습니다. 바른은 사전 디렉토리의 파일 변경을 실시간으로 감지해 변경을 무중단으로 다시 읽습니다. 60초 주기 점검도 함께 동작합니다.

Q. 같은 단어를 여러 사전에 넣어도 되나요?

같은 표제어가 NP/CP/CP^/VV/VA 등 여러 종류에 동시에 있으면 충돌로 보고됩니다. CheckConflict로 점검하고 의도한 한 종류만 남기는 것을 권장합니다.

Q. 사전 파일을 텍스트 편집기로 직접 고쳐도 되나요?

권장하지 않습니다. 서버의 사전 디렉토리에 놓이는 파일은 바이너리(서버 관리 형식)이므로, .txt로 직접 편집하는 방식이 아닙니다. 사용자 사전은 CustomDictionaryService API (UpdateCustomDictionary)로 관리하세요. 단어 목록 소스는 Git으로 버전 관리하고, 그 목록을 API로 반영하는 흐름을 권장합니다.