파이썬 클라이언트(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 구현에 유용합니다.

Q: What changed in bareunpy 2.0 and how do I upgrade?

bareunpy 2.0 moves off grpcio to a Connect RPC transport (connectrpc + protobuf), cutting install size and avoiding version conflicts, and adds streaming correction via correct_error_stream(). Install with `pip install "bareunpy>=2.0"` on Python 3.10+ (3.12 or 3.13 recommended); the Tagger, Tokenizer, Corrector, and CustomDict APIs stay the same, so most existing code keeps working after the upgrade.

파이썬 클라이언트 bareunpy

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

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

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

pip install --upgrade "bareunpy>=2.1"

베타 기능입니다

이 기능은 베타이며 바른 3.1.0 이상 서버가 필요합니다. 베타 기간에는 api.bareun.ai(클라우드)에서 사용할 수 있고, 자체 설치 서버에서는 3.1.0 업그레이드 후 사용할 수 있습니다. 정확도·한계는 동형이의어 의미 구분 API를 확인하세요.

의미만 바로 받기 — `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 이며 다음 값을 담습니다.

필드	설명
`content` / `tag`	형태소의 표층형과 품사
`sense_no`	어깨번호(우리말샘 기준 의미 번호). 사전 표기로는 3자리 0채움(`005`)
`meaning`	한국어 뜻풀이. 빈 문자열일 수 있습니다(우리말샘에 표제어가 없는 1% 미만)
`urimal_target_id`	우리말샘 표제어 고유 번호(없으면 0)
`urimal_url`	우리말샘 사전 화면 주소(번호가 없으면 빈 문자열)
`probability`	후보 의미 중 이 의미를 고른 확률 `[0,1]`. 후보가 하나뿐이면 항상 1.0

분석 결과와 함께 받기 — `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)

켜지 않으면 아무것도 달라지지 않습니다

with_sense·sense 는 모두 기본값이 False 입니다. 켜지 않은 호출은 응답 내용과 처리 시간이 종전과 동일하고, pos() 결과의 튜플 모양도 그대로입니다. 켜면 서버에서 추론이 한 번 더 일어나므로 필요한 곳에만 켜는 편이 좋습니다.

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.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 문자열

주요 메서드

메서드	반환	설명
`tag(text)`	`Tagged`	문자열 형태소 분석. 내부에서 문장 분리
`tags(sentences)`	`Tagged`	문자열 리스트, 개행으로 묶어 분석
`taglist(sentences)`	`Tagged`	리스트 그대로 문장 단위 분석(분리 없음)
`pos(text)`	`list`	`tag()` + `.pos()` 축약
`morphs(text)`	`list`	`tag()` + `.morphs()` 축약
`nouns(text)`	`list`	`tag()` + `.nouns()` 축약
`senses(text)`	`list`	동형이의어 의미 구분 결과(`SenseInfo` 목록). 2.1 이상, 베타
`tag_raw(text)`	`Tagged`	후처리 없는 원시 모델 분석. 2.0.1 이상

분절 — 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. 동형이의어의 뜻을 구분해서 받을 수 있나요?

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 구현에 유용합니다.

도움이 되었나요?

파이썬 클라이언트(bareunpy)

파이썬 클라이언트 bareunpy

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

의미만 바로 받기 — senses()

분석 결과와 함께 받기 — with_sense

bareunpy 2.0

무엇이 달라졌나요?

설치

bareunpy 1.x

API 키와 서버 주소

형태소 분석 — Tagger

여러 문장 분석

Tagged 결과 다루기

주요 메서드

분절 — Tokenizer

맞춤법 교정 — Corrector

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

사용자 사전 — CustomDict

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

자주 묻는 질문

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

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

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

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

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

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

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

의미만 바로 받기 — `senses()`

분석 결과와 함께 받기 — `with_sense`