Git으로 버전 관리

사용자 사전을 Git으로 버전 관리하기

바른의 사용자 사전은 CustomDictionaryService API로 관리합니다. 서버가 사용자 사전을 자체 형식(바이너리)으로 보관하므로, 사전 디렉토리의 파일을 직접 손으로 편집하지 않습니다.

그래서 Git으로 관리할 대상은 서버의 사전 파일이 아니라 여러분이 보유한 단어 목록(소스)입니다. 표제어 목록을 사람이 읽기 좋은 소스(원하는 형식의 텍스트·CSV 등)로 두고 Git으로 관리한 뒤, 이를 UpdateCustomDictionary API로 바른에 반영하는 흐름을 권장합니다.

서버의 사전 디렉토리 파일을 Git에 넣지 마세요

사용자 사전 디렉토리에 들어 있는 파일은 서버가 관리하는 바이너리입니다. 사람이 편집하거나 Git의 diff·merge로 다루기에 적합하지 않습니다. 버전 관리는 여러분의 단어 목록 소스를 대상으로 하세요.

왜 Git으로 관리하나

얻는 것	설명
변경 이력	누가 언제 어떤 단어를 추가·삭제했는지 추적
리뷰	단어 목록 변경을 PR/MR로 검토 후 반영
롤백	잘못 등록한 단어를 이전 상태로 되돌리기
일관성	여러 환경(개발·운영)에 같은 사전을 동일하게 반영
협업	도메인 전문가별로 단어 목록을 나눠 관리

저장소 구성 예시

여러분의 단어 목록 소스를 도메인·사전 종류별로 나눠 두면 관리하기 좋습니다. 형식은 자유이며(아래는 한 줄 한 표제어 예시), 배포 스크립트가 이 소스를 읽어 API로 등록합니다.

각 txt 파일은 한 줄에 한 단어가 들어가는 단순한 구조입니다.

custom-dict-src/
  legal/
    np.txt           # 고유명사 — 한 줄에 하나 (민식이법, 김영란법 ...)
    cp.txt           # 복합명사 (압수수색 ...)
    cp-caret.txt     # 복합명사 분리, ^로 분리 지점 표시 (손해^배상 ...)
    vv.txt           # 동사 (기소하다 ...)
    va.txt           # 형용사
  finance/
    np.txt
    cp.txt
  README.md          # 분류 기준·등록 규칙 메모

예를 들어 legal/np.txt는 다음과 같습니다(한 줄에 한 단어).

민식이법
김영란법
공수처

협업 워크플로우

graph LR
  A[단어 목록 소스 수정] --> B[충돌 검사];
  B --> C[PR/MR 리뷰];
  C --> D[머지];
  D --> E[UpdateCustomDictionary API 반영];
  E --> F[무중단 reload];

1. 수정: 담당자가 도메인 단어 목록 소스에 표제어를 추가·수정합니다.
2. 충돌 검사: 반영 전 CheckConflict로 중복·충돌을 점검합니다(CI에 넣으면 자동화).
3. 리뷰: PR/MR로 "왜 이 단어를 이 사전에 넣는지"를 함께 검토합니다.
4. 머지·반영: 머지된 소스를 배포 스크립트가 읽어 UpdateCustomDictionary API로 등록합니다.
5. 무중단 반영: 바른이 사전 변경을 감지해 재시작 없이 새 사전을 적용합니다.

충돌 검사를 CI에 넣으세요

단어 목록이 바뀔 때마다 CheckConflict를 돌리는 CI 잡을 두면, 충돌이 있는 변경은 머지 전에 걸러집니다. 운영 사전을 항상 충돌 0 상태로 유지하는 가장 확실한 방법이에요.

배포 패턴

• API 반영 배포: 배포 스크립트가 Git에서 받은 단어 목록 소스를 읽어 UpdateCustomDictionary API로 등록합니다. 애플리케이션 배포 파이프라인과 묶기 좋고, 등록 후 무중단으로 반영됩니다.
• 소스 = 단일 진실(Source of Truth): 운영 사전의 내용은 항상 Git의 단어 목록 소스에서 출발하도록 두면, 어느 환경이든 같은 상태로 재현할 수 있습니다.

API 키·민감 정보는 단어 목록과 분리

단어 목록 소스에는 표제어만 두세요. API 키나 접속 정보 같은 민감 정보는 별도로 관리하고, 저장소에 함께 커밋하지 마세요.

예제: txt 목록을 읽어 API로 반영하기

품사별 txt 파일(한 줄에 한 단어)을 읽어 바른의 사용자 사전으로 반영하는 스크립트입니다. Git에서 단어 목록이 바뀌면(머지 후·CI에서) 이 스크립트를 한 번 돌려 UpdateCustomDictionary API로 등록하면 됩니다. 등록 즉시 무중단으로 반영됩니다.

코드출력

import os
from bareunpy import Tagger

# ── 설정값 ───────────────────────────────────────────────
# API_KEY : bareun.ai에서 발급받은 본인 API 키. 소스에 직접 적지 말고
#           환경변수(os.environ["BAREUN_API_KEY"]) 등으로 주입하길 권장합니다.
# HOST    : 바른 서버 호스트. 로컬 설치본이면 "localhost".
# PORT    : 바른 서버 포트. 기본값은 5656.
# SRC_DIR : Git으로 관리하는 '내 단어 목록' 디렉토리(품사별 txt가 들어 있음).
# DOMAIN  : 바른에 등록·갱신할 사용자 사전 이름(요청 시 custom_dict_names로 골라 씀).
API_KEY = "koba-..."
HOST, PORT = "localhost", 5656
SRC_DIR = "custom-dict-src/legal"
DOMAIN = "legal"

def read_words(path: str) -> set:
    """품사별 txt 파일을 읽어 표제어 집합으로 돌려줍니다.

    txt 파일은 '한 줄에 한 단어' 구조입니다. 각 줄의 앞뒤 공백을 없애고,
    빈 줄과 '#'으로 시작하는 주석 줄은 건너뜁니다. 같은 단어가 여러 번
    나와도 집합(set)이라 자동으로 중복이 제거됩니다.

    Args:
        path (str): 읽어들일 txt 파일 경로(예: "custom-dict-src/legal/np.txt").

    Returns:
        set: 표제어 문자열의 집합. 파일이 없으면 빈 집합을 돌려줍니다
             (그 품사 사전을 비워서 등록하는 효과).
    """
    # 파일이 아직 없는 품사(예: va.txt 미작성)는 빈 집합으로 처리합니다.
    if not os.path.exists(path):
        return set()
    # UTF-8로 읽고, 공백 제거 후 빈 줄·주석(#)을 뺀 단어만 모읍니다.
    with open(path, encoding="utf-8") as fp:
        return {ln.strip() for ln in fp
                if ln.strip() and not ln.startswith("#")}

# 1) 품사별 txt 목록을 각각 집합으로 읽어들입니다.
np_set       = read_words(f"{SRC_DIR}/np.txt")        # 고유명사(NP)
cp_set       = read_words(f"{SRC_DIR}/cp.txt")        # 복합명사(CP)
cp_caret_set = read_words(f"{SRC_DIR}/cp-caret.txt")  # 복합명사 분리(CP^), ^로 분리 지점 표시
vv_set       = read_words(f"{SRC_DIR}/vv.txt")        # 동사(VV)
va_set       = read_words(f"{SRC_DIR}/va.txt")        # 형용사(VA)

# 2) 서버에 접속해 대상 사용자 사전(DOMAIN)을 열고, 품사별 집합으로 채웁니다.
#    copy_*_set은 해당 품사 사전의 '전체 내용을 이 집합으로 교체'합니다.
#    (누적이 아니라 대체이므로, txt가 곧 그 사전의 최종 상태가 됩니다.)
tagger = Tagger(API_KEY, HOST, PORT)
cust = tagger.custom_dict(DOMAIN)
cust.copy_np_set(np_set)
cust.copy_cp_set(cp_set)
cust.copy_cp_caret_set(cp_caret_set)
cust.copy_vv_set(vv_set)
cust.copy_va_set(va_set)

# 3) UpdateCustomDictionary API를 호출해 서버에 반영합니다.
#    호출 즉시 그 서버에 적용되고(무중단), 여러 서버가 사전 디렉토리를
#    공유하면 나머지 서버에도 곧바로 전파됩니다.
cust.update()
print(f"'{DOMAIN}' 사전 반영 완료: "
      f"NP {len(np_set)}, CP {len(cp_set)}, CP^ {len(cp_caret_set)}, "
      f"VV {len(vv_set)}, VA {len(va_set)}")

'legal' 사전 반영 완료: NP 3, CP 1, CP^ 1, VV 1, VA 0

CI/배포에 그대로 연결하세요

이 스크립트를 머지 후 실행되는 배포 잡에 넣으면, Git의 단어 목록이 곧 운영 사전이 됩니다. 실행 전 CheckConflict로 충돌을 한 번 점검하면 더 안전해요.

자주 묻는 질문

Q. 사용자 사전을 Git으로 관리해도 되나요?

서버의 사전 파일(바이너리) 자체는 Git 관리 대상이 아닙니다. 대신 여러분이 보유한 단어 목록 소스를 Git으로 관리하고, UpdateCustomDictionary API로 반영하면 변경 이력·리뷰·롤백을 그대로 활용할 수 있습니다.

Q. 저장소 구조는 어떻게 잡는 게 좋나요?

도메인별로 디렉토리를 나누고 사전 종류별(np/cp/cp-caret/vv/va)로 목록 파일을 두면 관리하기 쉽습니다. 형식은 자유이며, 분류 기준은 README로 함께 남기세요.

Q. Git에서 머지한 단어 목록을 어떻게 운영에 반영하나요?

배포 스크립트가 단어 목록 소스를 읽어 UpdateCustomDictionary API로 등록합니다. 등록되면 바른이 사전 변경을 감지해 무중단으로 반영합니다.

도움이 되었나요?

의견 보내기