멀티테넌시 사용자 사전 운영 패턴
여러 고객·팀·업무가 한 바른 서버를 함께 쓰는 환경에서는, 각자 다른 어휘를 인식해야 합니다.
바른은 사용자 사전과 custom_dict_names 옵션으로 이 멀티테넌시를 자연스럽게 지원합니다.
사전은 CustomDictionaryService로 관리하고, 분석 요청 시 사용할 사전을 골라 지정합니다.
이 문서는 사용자별·업무별로 사전을 분리해 운영하는 패턴을 정리합니다.
핵심 아이디어: 사전을 테넌트 단위로 나눈다
사전을 테넌트(고객/팀/도메인) 단위로 만들어두고, 요청마다 해당 테넌트의 사전을
custom_dict_names로 지정합니다. 여러 개를 지정하면 먼저 나온 사전이 우선합니다.
graph TD T1[테넌트 A] --> D1[dict-tenant-a] T2[테넌트 B] --> D2[dict-tenant-b] S[공통 어휘] --> DC[dict-common] D1 --> REQ[AnalyzeSyntax<br/>custom_dict_names=dict-tenant-a, dict-common] DC --> REQ
사용자 사전 종류
CustomDictionaryService로 만드는 사전에는 다음 표제어 집합을 담을 수 있습니다.
| 집합 | 품사 | 용도 |
|---|---|---|
np_set | 고유명사(NP) | 회사명·제품명 등 |
cp_set | 복합명사(CP) | 합성 명사 |
cp_caret_set | 복합명사 분리(CP^) | ^로 분리 지점 표시 |
vv_set / va_set | 동사·형용사 | 도메인 용언 |
mm_set / mag_set / ic_set | 관형사·부사·감탄사 | 기타 품사 |
요청에서 사전 지정하기
from bareunpy import Tagger
tagger = Tagger("koba-XXXX-...", host="api.bareun.ai", port=443)
# 테넌트 전용 사전을 먼저, 공통 사전을 뒤에 지정합니다(앞이 우선).
res = tagger.tags(
["우리 제품 바른토크의 신규 기능을 소개합니다."],
custom_dict_names=["dict-tenant-a", "dict-common"],
)
분석 결과의 형태소에는 out_of_vocab이 IN_CUSTOM_DICT로, custom_dict_name에
실제 적용된 사전 이름이 담겨, 어떤 사전이 단어를 결정했는지 확인할 수 있습니다.
무중단 갱신
사용자 사전은 운영 중에도 안전하게 바꿀 수 있습니다. 바른 서버는 사전 디렉토리의 파일 변경을 실시간으로 감지하고, 주기적으로도 점검해 변경을 무중단으로 다시 불러옵니다.
- 사전을 추가·수정·삭제하면 서버 재시작 없이 반영됩니다.
- 같은 표제어가 여러 사전에 충돌하면
CheckConflict로 미리 점검할 수 있습니다.
사전 간 충돌은 미리 점검하세요
같은 표제어가 NP/CP/CP^/VV/VA 등 여러 사전에 동시에 있으면 충돌로 보고됩니다.
테넌트별 사전을 합쳐 쓰기 전에 CheckConflict로 중복(duplicated)·충돌(conflict)을
확인하면 예기치 않은 분석 차이를 줄일 수 있습니다.
자주 묻는 질문
Q. 테넌트마다 다른 어휘를 인식하게 하려면 어떻게 하나요?
테넌트 단위로 사용자 사전을 만들어두고, 분석 요청 시 custom_dict_names에 해당 사전을
지정하세요. 여러 사전을 함께 지정하면 먼저 나온 사전이 우선 적용됩니다.
Q. 운영 중에 사전을 바꾸면 재시작해야 하나요?
아닙니다. 바른 서버는 사전 디렉토리의 파일 변경을 실시간으로 감지하고 주기적으로 점검해 변경을 무중단으로 다시 불러옵니다. 재시작 없이 반영됩니다.
Q. 어떤 사전이 단어를 결정했는지 알 수 있나요?
형태소의 out_of_vocab이 IN_CUSTOM_DICT이면 사용자 사전에서 온 단어이며,
custom_dict_name에 실제 적용된 사전 이름이 담깁니다.