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

Q: 바른 사용자 사전이 분석에 반영되지 않는 이유는 무엇인가요?

가장 흔한 원인은 분석 요청에 custom_dict_names를 지정하지 않은 것입니다. 사전을 등록해도 요청마다 사용할 사전 이름을 명시해야 적용됩니다. 그 밖에 사전 종류 불일치나 사전 간 충돌도 원인이 될 수 있습니다.

Q: 사용자 사전을 수정하면 서버를 재시작해야 하나요?

재시작할 필요가 없습니다. 사용자 사전은 CustomDictionaryService API로 관리하며, 바른이 사전 디렉토리의 파일 변경을 실시간으로 감지하고 60초 주기로도 점검하여 변경을 무중단으로 즉시 다시 읽어들입니다.

Q: 사용자 사전 파일을 텍스트 편집기로 직접 수정해도 되나요?

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

Q: 사용자 사전을 등록했는데 단어가 NA나 UNK로 그대로 나와요.

분석 요청에 custom_dict_names를 지정했는지, 사전 이름이 정확한지, 단어를 알맞은 DictSet(np_set·cp_set·vv_set 등)에 넣었는지 확인하세요. CheckConflict로 사전 간 충돌도 점검할 수 있습니다. 정상 적용되면 out_of_vocab가 IN_CUSTOM_DICT로 바뀌고 custom_dict_name에 사전 이름이 채워집니다.

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

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

증상

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

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

원인

세 가지를 의심하세요.

원인	설명
`custom_dict_names` 누락	분석 요청에 사용할 사전 이름을 지정하지 않음
사전 종류 불일치	단어를 엉뚱한 DictSet(`np_set`/`cp_set`/`vv_set` 등)에 등록
충돌/중복	같은 표제어가 여러 사전·여러 종류에 동시에 존재

해결

분석 요청에 custom_dict_names를 지정하세요. 사전을 만들었다고 자동 적용되지 않습니다. 요청마다 사용할 사전 이름을 명시해야 해요. 여러 개를 줄 수 있고, 먼저 지정한 사전이 우선합니다.
```
{
  "document": { "content": "바른은 한국어 형태소 분석기입니다.", "language": "ko_KR" },
  "custom_dict_names": ["my-domain", "company-names"]
}
```

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

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

충돌을 검사하세요. CheckConflict로 같은 사전 내 중복(duplicated)과 사전 간 충돌(conflict)을 확인합니다. 같은 표제어가 NP/CP/CP^/VV/VA에 동시에 있으면 충돌로 보고되며, 의도한 한 종류만 남기는 게 좋습니다.
갱신이 반영됐는지 확인하세요. 사용자 사전은 CustomDictionaryService API로 관리하며, 서버의 사전 디렉토리에 놓이는 파일은 바이너리(서버 관리 형식)입니다. UpdateCustomDictionary로 변경하면 바른이 사전 디렉토리의 파일 변경(추가·수정·삭제)을 실시간으로 감지하고 60초 주기로도 점검해 무중단 reload합니다. 변경 직후 반영이 안 보이면 잠시 기다렸다가 다시 분석해보세요.

사전 이름은 정확히

custom_dict_names에 넣은 이름이 실제 등록한 사전 이름과 한 글자라도 다르면 적용되지 않습니다. GetCustomDictionaryList로 등록된 사전 이름 목록을 먼저 확인하세요.

예방·팁

등록이 잘 됐는지는 분석 결과 형태소의 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로 반영하는 흐름을 권장합니다.

도움이 되었나요?