파이썬 클라이언트(bareunpy)

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: bareunpy 2.0에서 grpcio 의존성은 어떻게 되나요?

bareunpy 2.0은 grpcio를 사용하지 않습니다. 내부 통신이 Connect RPC로 전환되어 connectrpc와 protobuf 두 가지만 필요합니다. 설치 크기가 크게 줄고 버전 충돌 걱정도 없어집니다.

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

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

Q: 스트리밍 교정 API는 무엇인가요?

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

파이썬 클라이언트 bareunpy

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

bareunpy 2.0

무엇이 달라졌나요?

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

2.0의 핵심 개선

훨씬 가벼워졌습니다

1.x는 grpcio(C 확장, 50MB+), bareun-apis, googleapis-common-protos, certifi, cryptography 등 여러 패키지가 필요했습니다. 2.0은 런타임 의존성이 connectrpc와 protobuf 단 두 가지입니다. 설치 크기가 크게 줄고 의존성 충돌 걱정도 사라집니다.

버그 수정

1.x에서 알려진 여러 문제를 수정했습니다.

문제	1.x	2.0
`set_domain()` 호출 시 TypeError 발생	❌ 깨진 상태	✅ `DeprecationWarning`으로 정상 작동
CA 인증서 오류(TLS)	❌ `api.bareun.ai` 연결 실패 가능	✅ 수정됨
`grpcio` ↔ `protobuf` 버전 충돌	❌ 환경에 따라 설치 실패	✅ 단일 protobuf 7.35+
`connecpy` 비공식 라이브러리 의존	❌ 유지 보수 위험	✅ 공식 `connectrpc`
파이썬 3.6–3.9 지원 (EOL)	(지원)	파이썬 3.10+ 으로 정비

스트리밍 교정 API 추가

맞춤법 교정 결과를 실시간으로 스트리밍 받는 Corrector.correct_error_stream() 이 추가되었습니다.

설치

pip install "bareunpy>=2.0"

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

pyqwest(Rust 기반 HTTP) 지원 버전

connectrpc의 HTTP 전송 계층 pyqwest는 파이썬 3.10·3.12·3.13용 바이너리를 제공합니다. 파이썬 3.11은 아직 지원하지 않으므로 3.12 또는 3.13을 권장합니다.

bareunpy 1.x

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

pip install "bareunpy<2.0"

1.x 장기 지원 안내

1.x는 현재 보안·긴급 수정 외에는 새 기능이 추가되지 않습니다. 신규 환경이라면 2.0 사용을 권장합니다.

API 키와 서버 주소

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

환경	`host`	`port`
클라우드(`api.bareun.ai`)	`"api.bareun.ai"`	`443` (TLS)
직접 설치·도커	`"localhost"`	`5656`

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

형태소 분석 — Tagger

클라우드 (api.bareun.ai)직접 설치 (localhost)

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())   # ['나비', '허리', '초생달']

여러 문장 분석

클라우드 (api.bareun.ai)직접 설치 (localhost)

# 리스트로 여러 문장 — 개행으로 묶어 분석
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.morphs()            # ['햇빛', '이', '선명', ...]
result.nouns()             # ['햇빛', '나뭇잎']
result.verbs()             # ['핥']
result.as_json()           # dict
result.as_json_str()       # JSON 문자열

주요 메서드

메서드	반환	설명
`tag(text)`	`Tagged`	문자열 형태소 분석. 내부에서 문장 분리
`tags(sentences)`	`Tagged`	문자열 리스트, 개행으로 묶어 분석
`taglist(sentences)`	`Tagged`	리스트 그대로 문장 단위 분석(분리 없음)
`pos(text)`	`list`	`tag()` + `.pos()` 축약
`morphs(text)`	`list`	`tag()` + `.morphs()` 축약
`nouns(text)`	`list`	`tag()` + `.nouns()` 축약

분절 — Tokenizer

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

클라우드 (api.bareun.ai)직접 설치 (localhost)

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

클라우드 전용 기능

맞춤법 교정(Corrector)은 api.bareun.ai 클라우드 서비스에서만 사용할 수 있습니다. 직접 설치(온프레미스)한 서버에는 맞춤법 교정 기능이 포함되지 않습니다.

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)

스트리밍은 2.0 전용

correct_error_stream()은 Connect RPC의 server-streaming을 사용합니다. 1.x에서는 지원하지 않습니다.

사용자 사전 — CustomDict

클라우드 (api.bareun.ai)직접 설치 (localhost)

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. 스트리밍 교정은 어디서 쓰나요?

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

도움이 되었나요?