5종 사용자 사전 한눈에 — 언제 무엇을 쓰나
바른의 사용자 사전은 단순히 "모르는 단어를 등록하는 곳"이 아닙니다.
등록하려는 단어가 고유명사인지, 복합명사인지, 동사인지에 따라 들어갈 사전이 다르고,
어느 사전에 넣느냐에 따라 형태소 분석 결과의 품사와 토큰화가 달라집니다.
이 문서는 5종 사용자 사전(NP/CP/CP^/VV/VA)의 용도를 한눈에 정리하고, "이 단어는 어느 사전에 넣어야 하나요?"라는 질문에 답하기 위한 선택 기준을 제시합니다.
5종 사용자 사전 용도 표
하나의 사용자 사전(도메인)은 아래 다섯 개의 묶음(DictSet)으로 구성됩니다.
각 묶음은 형태소 분석 결과에서 서로 다른 품사로 인식됩니다.
| 사전 필드 | 이름 | 인식 품사 | 용도 | 예시 |
|---|---|---|---|---|
np_set | 고유명사(NP) | NNP | 사람·지역·상품·이벤트 등 고유한 이름 | 크리스토퍼놀란, 걸어서세계속으로, 민식이법 |
cp_set | 복합명사(CP) | NNG | 여러 명사가 굳어진 신조어·전문어 한 덩어리 | 코로나19, 바나나우유, 압수수색 |
cp_caret_set | 복합명사 분리(CP^) | NNG + NNG | 붙여 써도 두 단어로 분리해 토큰화 | 형태소^분석, 디지털^인문학, 데이터^산업 |
vv_set | 동사(VV) | VV | 신조어 동사, 활용형까지 인식 | 카톡하다, 맑내하다 |
va_set | 형용사(VA) | VA | 신조어 형용사, 활용형까지 인식 | 소녀스럽다, 신박하다, 판타스틱하다 |
왜 사전을 5종으로 나누나요?
한국어는 같은 글자라도 문맥에 따라 명사가 되기도, 용언이 되기도 합니다.
바른은 등록 시점에 품사 의도를 명확히 받아, 분석할 때 그 의도대로 태깅합니다.
예를 들어 카톡하다를 동사 사전에 넣으면 "카톡했다", "카톡하는"처럼 활용형까지 동사로
인식하지만, 명사 사전에 넣으면 그렇지 못합니다.
무엇보다 바른은 모르는 단어라 허더라도 그게 용언인지 체언인지는 미뤄서 짐작합니다.
그 정확도도 매우 높습니다. 용언이 올 자리에 모르는 단어가 나타나면, 동사나 형용사 사전을 뒤집니다.
그래서 바른에서는 품사별로 사전을 다르게 유지합니다.
어느 사전에 넣을지 선택하는 기준
아래 흐름을 따라가면 대부분의 단어가 들어갈 자리를 찾을 수 있습니다.
graph TD
A[등록할 단어] --> B{용언인가?};
B -- 동사다 --> VV[vv_set 동사];
B -- 형용사다 --> VA[va_set 형용사];
B -- 명사다 --> C{고유한 이름인가?};
C -- 예 사람·상품·법령 --> NP[np_set 고유명사];
C -- 아니오 일반 개념 --> D{한 덩어리로 볼까<br>둘로 나눌까?};
D -- 한 단어로 --> CP[cp_set 복합명사];
D -- 두 단어로 분리 --> CPC[cp_caret_set 복합명사 분리];
- 이름이면 NP: 회사·상품·인물·법령처럼 세상에 하나뿐인 이름은 고유명사(
np_set)입니다. 결과에서NNP로 태깅됩니다. - 굳어진 한 덩어리면 CP:
코로나19처럼 의미상 한 단어로 굳어진 신조어·전문어는 복합명사(cp_set)에 넣으면 통째로NNG한 개로 인식됩니다. - 검색·색인 때문에 나누고 싶으면 CP^: 한 덩어리로 인식되면 검색이 안 되는 단어는
복합명사 분리(
cp_caret_set)에형태소^분석처럼^로 분리 지점을 표시합니다. - 활용하는 단어면 VV/VA: "~하다/~스럽다"로 끝나며 활용하는 신조어는 동사·형용사 사전에 넣어야 "했다, 하는, 스러운"까지 인식됩니다.
여러 사전을 도메인으로 묶으세요
5종 묶음 하나가 도메인 하나입니다. 법률·의료·금융처럼 영역별로 도메인을 따로 만들고,
분석할 때 custom_dict_names로 필요한 도메인을 골라 쓰면 됩니다.
도메인 이름은 영문·숫자·_·-만 쓸 수 있습니다.
사용자 사전은 API 키별로 분리됩니다
사용자 사전은 발급받은 API 키(사용자)별로 따로 보관됩니다. 같은 바른 서버를 쓰더라도 API 키가 다르면 서로 다른 사전 집합을 가집니다.
- 어떤 API 키로 등록한 사전은 그 키로 분석·교정할 때만 적용됩니다. 다른 키의 요청에는 보이지 않습니다.
- 등록된 사전 목록을 조회해도 자신의 키에 등록된 도메인만 나타납니다.
- 도메인 개수 한도도 API 키별로 매겨집니다.
이 때문에 custom_dict_names에 도메인을 넣어도 동작하지 않는다면, 먼저 그 도메인이 지금
사용 중인 API 키로 등록돼 있는지 확인하세요. 키 A로 등록한 사전은 키 B의 요청에서는 쓸 수
없습니다. 팀이 여러 키를 쓴다면 사전을 사용하는 키마다 각각 등록해야 합니다.
MCP 에서도 동일합니다
MCP 의 bareun://custom-dicts 리소스도 호출에 쓰인 API 키 기준으로 등록된 사전
목록을 돌려줍니다. 즉 키마다 보이는 사전이 다릅니다.
등록 결과 확인하기
등록한 단어가 사용자 사전에서 왔는지는 형태소의 out_of_vocab 값이 IN_CUSTOM_DICT인지로
확인합니다. 어느 도메인에서 왔는지는 custom_dict_name에 들어 있습니다.
크리스토퍼놀란/NNP, IN_CUSTOM_DICT
코로나19/NNG, IN_CUSTOM_DICT
카톡하/VV, IN_CUSTOM_DICT
자주 묻는 질문
Q. 사용자 사전은 모든 사용자가 공유하나요?
아니요. 사용자 사전은 발급받은 API 키별로 분리됩니다. 어떤 키로 등록한 사전은 그 키로
분석·교정할 때만 적용되고, 목록 조회에도 자신의 키 사전만 보입니다. 여러 키로 같은 사전을
쓰려면 키마다 각각 등록해야 합니다. (MCP 의 bareun://custom-dicts 도 호출 키 기준입니다.)
Q. 같은 단어를 여러 사전에 넣어도 되나요?
권장하지 않습니다. 같은 표제어가 NP/CP/CP^/VV/VA 여러 사전에 동시에 있으면 충돌(conflict)로
보고됩니다. 등록 전에 CheckConflict로 점검하세요. 자세한 내용은 충돌 검사 문서를 참고하세요.
Q. 복합명사(CP)와 복합명사 분리(CP^)는 무엇이 다른가요?
CP는 코로나19처럼 통째로 명사 한 개(NNG)로 묶고, CP^는 형태소^분석처럼 둘 이상의
명사로 나눕니다. 검색·RAG처럼 단어 단위 색인이 중요하면 CP^를 사용하세요.
Q. 사전을 바꾸면 서버를 다시 띄워야 하나요?
아닙니다. 바른은 사전 파일 변경을 실시간으로 감지해 무중단으로 반영합니다.
자세한 내용은 무중단 즉시 반영 문서를 참고하세요.
Q. 사용자 사전은 어떻게 관리하나요? 텍스트 파일을 직접 고치면 되나요?
사용자 사전은 CustomDictionaryService API(UpdateCustomDictionary 등)로 관리합니다.
서버가 사용자 사전을 자체 형식(바이너리)으로 보관하므로, 사전 디렉토리의 파일을 손으로
편집하지 않습니다. 버전 관리가 필요하면 여러분이 보유한 단어 목록 소스를 Git으로 두고
API로 반영하세요.
Q. 등록한 단어가 사용자 사전에서 왔는지 어떻게 확인하나요?
형태소의 out_of_vocab 값이 IN_CUSTOM_DICT인지로 확인합니다. 어느 도메인에서 왔는지는
custom_dict_name에 담겨 있어, 크리스토퍼놀란/NNP, IN_CUSTOM_DICT처럼 출처와 품사를 함께
점검할 수 있습니다.