파이썬 클라이언트 bareunpy

bareunpy는 바른 서버를 파이썬에서 쉽게 쓸 수 있도록 감싼 공식 클라이언트 라이브러리입니다. 형태소 분석(Tagger), 분절(Tokenizer), 맞춤법 교정(Corrector), 사용자 사전 관리(CustomDict) 네 가지 기능을 제공합니다.

bareunpy 2.1 — 동형이의어 의미 구분 (베타)

2.1.0에서 동형이의어 의미 구분(WSD) API 가 추가되었습니다. 다리가 건너는 다리(橋)인지 몸의 다리(脚)인지는 품사(NNG)로 갈리지 않는데, 이 기능을 켜면 문맥으로 뜻을 골라 어깨번호(사전 의미 번호)와 뜻풀이를 함께 받습니다.

pip install --upgrade "bareunpy>=2.1"

의미만 바로 받기 — senses()

from bareunpy import Tagger

tagger = Tagger(apikey="koba-XXXX-...")

for s in tagger.senses("다리를 건넜다."):
    print(s.content, s.tag, s.sense_no, s.meaning)
# 다리 NNG 5 물을 건너거나 … 건너다닐 수 있도록 만든 시설물.
# 건너 VV 1 무엇을 사이에 두고 한편에서 맞은편으로 가다.

for s in tagger.senses("다리가 저리다."):
    print(s.content, s.sense_no, s.meaning)
# 다리 1 사람이나 동물의 몸통 아래 붙어 있는 신체의 부분. …

senses() 는 의미가 부여된 형태소만 돌려줍니다. 조사·어미처럼 사전 의미 번호가 없는 형태소는 빠지므로, 결과가 형태소 목록보다 짧은 것이 정상입니다.

각 항목은 SenseInfo 이며 다음 값을 담습니다.

분석 결과와 함께 받기 — with_sense

res = tagger.tag("다리를 건넜다.", with_sense=True)

res.senses()                      # SenseInfo 목록
res.pos(join=True, sense=True)    # ['다리__005/NNG', '를/JKO', '건너__001/VV', ...]
res.pos(sense=True)               # [('다리', 'NNG', 5), ('를', 'JKO', 0), ...]

# 여러 문장·원시 분석에서도 같은 옵션을 씁니다.
tagger.tags(["다리를 건넜다.", "다리가 저리다."], with_sense=True)
tagger.taglist(["다리를 건넜다."], with_sense=True)
tagger.tag_raw("다리를건넜다", with_sense=True)

bareunpy 2.0

무엇이 달라졌나요?

2.0은 내부 통신 방식을 Connect RPC로 전환한 버전입니다. 서버가 한 포트에서 gRPC·Connect·REST를 모두 처리하는 방식으로 바뀐 것에 맞춰 클라이언트도 맞췄습니다.

설치

pip install "bareunpy>=2.0"

파이썬 3.10 이상이 필요합니다.

bareunpy 1.x

기존 grpcio 기반 버전입니다. 이미 1.x를 사용 중인 환경은 계속 동작합니다.

pip install "bareunpy<2.0"

API 키와 서버 주소

API 키는 koba-로 시작하는 값이며, 바른 포털에서 발급합니다.

host를 생략하면 api.bareun.ai:443이 기본값입니다.

형태소 분석 — Tagger

from bareunpy import Tagger

tagger = Tagger(apikey="koba-XXXX-...")
# 또는 명시적으로
tagger = Tagger(apikey="koba-XXXX-...", host="api.bareun.ai", port=443)

result = tagger.tag("나비 허리에 새파란 초생달이 시리다.")
print(result.pos())
# [('나비', 'NNG'), ('허리', 'NNG'), ('에', 'JKB'), ...]

print(result.nouns())   # ['나비', '허리', '초생달']

from bareunpy import Tagger

tagger = Tagger(apikey="koba-XXXX-...", host="localhost", port=5656)

result = tagger.tag("나비 허리에 새파란 초생달이 시리다.")
print(result.pos())
# [('나비', 'NNG'), ('허리', 'NNG'), ('에', 'JKB'), ...]

print(result.nouns())   # ['나비', '허리', '초생달']

여러 문장 분석

# 리스트로 여러 문장 — 개행으로 묶어 분석
result = tagger.tags(["첫 번째 문장.", "두 번째 문장."])

# 리스트 그대로, 문장 단위 분리 없이
result = tagger.taglist(["첫 번째 문장.", "두 번째 문장."])
print(result.morphs())

tagger = Tagger(apikey="koba-XXXX-...", host="localhost", port=5656)

result = tagger.tags(["첫 번째 문장.", "두 번째 문장."])
result = tagger.taglist(["첫 번째 문장.", "두 번째 문장."])
print(result.morphs())

Tagged 결과 다루기

result = tagger.tag("햇빛이 선명하게 나뭇잎을 핥고 있었다.")

result.pos()               # [(형태소, 품사), ...]
result.pos(join=True)      # ['햇빛/NNG', '이/JKS', ...]
result.pos(detail=True)    # (형태소, 품사, OOV여부, 확률)
result.pos(sense=True)     # (형태소, 품사, 어깨번호) — 2.1, with_sense=True 로 분석했을 때
result.senses()            # 동형이의어 의미 목록 — 2.1, with_sense=True 로 분석했을 때
result.morphs()            # ['햇빛', '이', '선명', ...]
result.nouns()             # ['햇빛', '나뭇잎']
result.verbs()             # ['핥']
result.as_json()           # dict
result.as_json_str()       # JSON 문자열

주요 메서드

분절 — Tokenizer

형태소 분석 전 단계인 분절(Segmentation) 결과를 반환합니다.

from bareunpy import Tokenizer

tokenizer = Tokenizer(apikey="koba-XXXX-...")
result = tokenizer.tokenize("안녕하세요, 반가워요.")

print(result.seg())    # 분절 결과 리스트
print(result.nouns())  # 명사만

from bareunpy import Tokenizer

tokenizer = Tokenizer(apikey="koba-XXXX-...", host="localhost", port=5656)
result = tokenizer.tokenize("안녕하세요, 반가워요.")

print(result.seg())    # 분절 결과 리스트
print(result.nouns())  # 명사만

맞춤법 교정 — Corrector

from bareunpy import Corrector

corrector = Corrector(apikey="koba-XXXX-...")  # api.bareun.ai:443 기본값

resp = corrector.correct_error("영수 도 줄기가 얇어서 고은 꽃이 피었다.")
print(resp.revised)        # 교정된 문장
corrector.print_results(resp)

스트리밍 교정 (2.0 신기능)

긴 문장이나 실시간 피드백이 필요할 때 서버가 교정 결과를 조각 단위로 보내는 스트리밍 방식을 쓸 수 있습니다.

corrector = Corrector(apikey="koba-XXXX-...")  # 클라우드 전용

for resp in corrector.correct_error_stream("긴 텍스트를 여기에 넣습니다..."):
    kind = resp.WhichOneof("res")
    if kind == "first":
        print("원문:", resp.first.origin)
    elif kind == "progress":
        print("교정 중...", resp.progress)
    elif kind == "post":
        print("최종:", resp.post.revised)

사용자 사전 — CustomDict

from bareunpy import Tagger

tagger = Tagger(apikey="koba-XXXX-...")
cd = tagger.custom_dict("my-domain")

cd.copy_np_set({"바이칼AI", "바른NLP"})   # 고유명사
cd.update()                               # 서버에 반영

tagger.set_custom_dicts(["my-domain"])
result = tagger.tag("바이칼AI의 바른NLP 엔진")

from bareunpy import Tagger

tagger = Tagger(apikey="koba-XXXX-...", host="localhost", port=5656)
cd = tagger.custom_dict("my-domain")

cd.copy_np_set({"바이칼AI", "바른NLP"})
cd.update()

tagger.set_custom_dicts(["my-domain"])
result = tagger.tag("바이칼AI의 바른NLP 엔진")

사용자 사전 운영에 대한 자세한 내용은 사용자 사전 깊이 활용을 참고하세요.

1.x에서 2.0으로 이전하기

기본 API는 동일하므로 대부분의 코드를 그대로 쓸 수 있습니다.

pip install "bareunpy>=2.0"

주의할 사항:

• grpcio 의존성이 없어졌습니다. 기존에 grpcio를 직접 사용하던 코드가 있다면 별도로 유지해야 합니다.
• set_domain()은 set_custom_dicts()의 별칭으로만 유지됩니다. DeprecationWarning이 발생하며 향후 제거됩니다.
• correct_error_list()는 폐기되었습니다. correct_error()를 쓰세요.
• 파이썬 3.6–3.9는 지원하지 않습니다.

자주 묻는 질문

Q. bareunpy 2.0은 어떻게 설치하나요?

pip install "bareunpy>=2.0"으로 설치합니다. 파이썬 3.10 이상이 필요하며, 3.12 또는 3.13을 권장합니다.

Q. 1.x에서 2.0으로 바꾸려면 코드를 많이 고쳐야 하나요?

Tagger, Tokenizer, Corrector, CustomDict의 기본 API는 동일합니다. pip install "bareunpy>=2.0" 으로 업그레이드하면 대부분 그대로 동작합니다.

Q. 2.0에서 grpcio를 직접 쓰던 코드가 있으면 어떻게 되나요?

bareunpy 자체는 더 이상 grpcio를 필요로 하지 않습니다. 기존 코드에서 grpcio를 직접 import해 사용했다면 별도로 설치해야 합니다.

Q. 파이썬 3.11을 쓰고 있는데 2.0을 설치할 수 있나요?

HTTP 전송 계층인 pyqwest가 아직 3.11용 바이너리를 제공하지 않습니다. 3.10, 3.12, 3.13을 사용해 주세요.

Q. 맞춤법 교정을 직접 설치한 서버에서도 쓸 수 있나요?

맞춤법 교정(Corrector)은 api.bareun.ai 클라우드 서비스에서만 사용할 수 있습니다. 직접 설치한 서버에서는 형태소 분석과 분절 기능만 사용 가능합니다.

Q. 동형이의어의 뜻을 구분해서 받을 수 있나요?

bareunpy 2.1.0 이상에서 tagger.senses("다리를 건넜다.") 로 어깨번호와 뜻풀이를 받을 수 있습니다. tag()·tags()·taglist()·tag_raw() 에 with_sense=True 를 주는 방식도 됩니다. 베타 기능이며 바른 3.1.0 이상 서버가 필요합니다.

Q. 스트리밍 교정은 어디서 쓰나요?

Corrector.correct_error_stream()을 사용하면 교정 결과를 실시간으로 조각 단위로 받을 수 있습니다. 2.0에서 새로 추가된 기능으로 긴 문장 처리나 실시간 피드백 UI 구현에 유용합니다.