bareunpy 2.0.1

The bareun python library using connect-rpc

bareunpy

bareunpy는 한국어 자연어 처리(NLP) 엔진 Bareun 의 Python 3 클라이언트 라이브러리입니다.

형태소 분석(POS tagging), 토크나이징(tokenizing), 맞춤법 검사(spelling correction) 기능을 제공합니다.

---

변경사항

2.0.1

• AnalyzeSyntaxRaw API 추가: tagger.tag_raw() — seg+tag 모델 추론만 수행, 복합명사·동사 분해/사용자 사전/자동 띄어쓰기 후처리 없이 순수 모델 출력 반환

2.0

• Connect RPC 전환: grpcio 의존성 제거. 공식 connectrpc 라이브러리로 교체
• 경량화: 의존성 2개(connectrpc, protobuf)만 필요 — 기존 grpcio / connecpy 설치 불필요
• 버그 수정: 스트리밍 응답 처리, 빈 입력 처리 안정성 개선, 에러 메시지 한글화
• Python 3.10+ 지원 유지, 기존 API와 호환

---

설치 (Installation)

pip3 install bareunpy

요구사항: Python 3.10 이상. 서버와의 통신은 공식 Connect RPC 파이썬 라이브러리 (connectrpc, connect-python) 위에서 동작합니다. (2.0.0 부터 기존 gRPC 직접 연결에서 Connect RPC 로 전환되었습니다.)

API KEY 발급

1. https://bareun.ai/ 에 접속하여 회원가입 후 이메일 인증을 완료하면 자동 발급됩니다.
2. 로그인 → 내정보 확인에서 API KEY(koba-...)를 조회합니다.

발급받은 API KEY로 api.bareun.ai 호스팅 서버에 바로 연결하거나, 자체 서버에 Bareun을 설치하여 사용할 수도 있습니다.

서버 연결 방식

from bareunpy import Tagger

API_KEY = "koba-ABCDEFG-1234567-LMNOPQR-7654321"  # 본인의 API KEY로 교체

# 1) 호스팅 API 사용 (가장 간편한 방법, host 생략 시 기본값)
tagger = Tagger(API_KEY)
# 또는 명시적으로 지정
tagger = Tagger(API_KEY, 'api.bareun.ai', 443)

# 2) 로컬 서버 사용
tagger = Tagger(API_KEY, 'localhost', 5656)

# 3) 원격 자체 서버 사용 (예: 10.8.3.211:15656)
tagger = Tagger(API_KEY, '10.8.3.211', 15656)

자체 서버 설치는 Docker 이미지로 간편하게 할 수 있습니다.

docker pull bareunai/bareun:latest

자세한 내용은 Docker Hub를 참고하세요.

---

형태소 분석 (Tagger)

기본 사용법

from bareunpy import Tagger

API_KEY = "koba-ABCDEFG-1234567-LMNOPQR-7654321"  # 본인의 API KEY로 교체
tagger = Tagger(API_KEY)

# POS 태깅
print(tagger.pos('햇빛이 선명하게 나뭇잎을 핥고 있었다.'))
# [('햇빛', 'NNG'), ('이', 'JKS'), ('선명', 'NNG'), ('하', 'XSA'), ('게', 'EC'),
#  ('나뭇잎', 'NNG'), ('을', 'JKO'), ('핥', 'VV'), ('고', 'EC'), ('있', 'VX'),
#  ('었', 'EP'), ('다', 'EF'), ('.', 'SF')]

# 형태소 추출
print(tagger.morphs('안녕하세요, 반가워요.'))
# ['안녕', '하', '시', '어요', ',', '반갑', '어요', '.']

# 명사 추출
print(tagger.nouns('나비 허리에 새파란 초생달이 시리다.'))
# ['나비', '허리', '초생달']

# 동사 추출
print(tagger.verbs('햇빛이 선명하게 나뭇잎을 핥고 있었다.'))
# ['핥']

여러 문장 분석

# tags(): 여러 문장을 한 번에 분석 (문장 분할 적용)
res = tagger.tags(["안녕하세요.", "반가워요!"])

# taglist(): 입력된 문장 단위를 그대로 유지하여 분석 (문장 분할 없음)
res = tagger.taglist(["안녕하세요.", "반가워요!"])

원시(Raw) 형태소 분석

tag_raw()는 seg+tag 모델 추론 결과를 후처리 없이 반환합니다. 복합명사·동사 분해, 자동 띄어쓰기·붙여쓰기 보정, 사용자 사전을 적용하지 않아 순수 모델 출력을 확인할 때 사용합니다.

# tag_raw(): 후처리 없는 순수 모델 출력
res = tagger.tag_raw('나는밥을먹었다')
print(res.pos())

# 문장 자동 분리 적용 가능
res = tagger.tag_raw('나는밥을먹었다. 그리고잤다.', auto_split=True)

분석 옵션

tag(), tags(), taglist() 메서드에서 다음 옵션을 사용할 수 있습니다.

파라미터	타입	기본값	설명
auto_split	bool	False	문장 자동 분리 (tag, tags만 해당)
auto_spacing	bool	True	띄어쓰기 보정
auto_jointing	bool	True	붙여쓰기 보정

res = tagger.tag('햇빛이선명하게나뭇잎을핥고있었다', auto_spacing=True, auto_jointing=True)
print(res.pos())

결과 활용

res = tagger.tags(["안녕하세요.", "반가워요!"])

# protobuf 메시지 원본
m = res.msg()

# JSON 변환
print(res.as_json())
print(res.as_json_str())

# 형태소, POS 태그, 명사, 동사 추출
print(res.morphs())
print(res.pos())
print(res.nouns())
print(res.verbs())

상세 결과 탐색 (Advanced)

import sys
import google.protobuf.text_format as tf

m = res.msg()
tf.PrintMessage(m, out=sys.stdout, as_utf8=True)

for sent in m.sentences:
    for token in sent.tokens:
        for morph in token.morphemes:
            print(f'{morph.text.content}/{morph.tag}:{morph.probability}:{morph.out_of_vocab}')

---

토크나이저 (Tokenizer)

from bareunpy import Tokenizer

API_KEY = "koba-ABCDEFG-1234567-LMNOPQR-7654321"  # 본인의 API KEY로 교체
tokenizer = Tokenizer(API_KEY)

# 토크나이징
tokenized = tokenizer.tokenize_list(["안녕하세요.", "반가워요!"])

# 다양한 추출 메서드
print(tokenized.segments())       # 전체 세그먼트
print(tokenized.nouns())          # 명사
print(tokenized.verbs())          # 동사
print(tokenized.postpositions())  # 조사
print(tokenized.adverbs())        # 부사
print(tokenized.symbols())        # 기호

상세 결과 탐색

m = tokenized.msg()
for sent in m.sentences:
    for token in sent.tokens:
        for seg in token.segments:
            print(f'{seg.text.content}/{seg.hint}')

---

맞춤법 검사 (Corrector)

참고: 맞춤법 검사는 api.bareun.ai 호스팅 API에서만 사용 가능합니다. 로컬 서버에서는 지원되지 않습니다.

from bareunpy import Corrector

API_KEY = "koba-ABCDEFG-1234567-LMNOPQR-7654321"  # 본인의 API KEY로 교체
corrector = Corrector(API_KEY)

response = corrector.correct_error("영수 도 줄기가 얇어서 시들을 것 같은 꽃에물을 주었다.")
print(f"원문:   {response.origin}")
print(f"교정문: {response.revised}")

# 상세 결과 출력
corrector.print_results(response)

실시간 교정 (Streaming)

correct_error_stream() 은 교정 결과를 한 번에 받지 않고, 서버가 보내는 대로 여러 개의 응답으로 나눠 받는 server-streaming 방식입니다. AI 기반 교정처럼 결과가 점진적으로 확정되는 경우에 유용합니다.

from bareunpy import Corrector

corrector = Corrector(API_KEY)

for res in corrector.correct_error_stream("영수 도 줄기가 얇어서 시들을 것 같다."):
    # 각 응답은 res(oneof) 로 다음 중 하나를 담습니다:
    #  - first    : 첫 번째 기본 교정 결과
    #  - progress : AI 가 추가 검토 중인 항목의 진행 상태
    #  - post     : 추가 검토가 끝나 확정된 교정 결과
    #  - cancelled: 이전에 제안한 교정이 취소됨
    kind = res.WhichOneof("res")
    if kind == "first":
        print("교정문:", res.first.revised)
    elif kind == "progress":
        print("진행중:", res.progress.thinking_msg)
    elif kind == "post":
        print("확정:", res.post.revision.revised)
    elif kind == "cancelled":
        print("취소:", res.cancelled.thinking_id)

---

사용자 사전 (Custom Dictionary)

사용자 사전을 등록하면 도메인 특화 용어의 분석 정확도를 높일 수 있습니다.

사전 등록 및 업데이트

# 사용자 사전 생성/수정
cust_dic = tagger.custom_dict("my")
cust_dic.copy_np_set({'내고유명사', '우리집고유명사'})    # 고유명사
cust_dic.copy_cp_set({'코로나19'})                       # 복합명사
cust_dic.copy_cp_caret_set({'코로나^백신', '독감^백신'})  # 복합명사 (분리 위치 지정)
cust_dic.update()

사전 불러오기 및 적용

# 기존 사전 불러오기
cust_dic2 = tagger.custom_dict("my")
cust_dic2.load()

# 분석 시 사용자 사전 적용
tagger.set_custom_dicts(["my"])
tagger.pos('코로나19는 언제 끝날까요?')