3.4.0

파이썬 패키지(baropy, 서버 내장)

파이썬 패키지 baropy

baropy(패키지 이름 bareun-baropy)는 형태소 분석 서버를 패키지 안에 함께 담은 파이썬 패키지입니다. pip install 한 줄이면 끝나고, 서버를 따로 설치해 띄우거나 글을 클라우드로 보낼 필요가 없습니다. 처음 분석을 부르면 분석 서버가 뒤에서 조용히 켜지고, 파이썬 프로그램이 끝나면 함께 꺼집니다.

지금은 형태소 분석까지입니다

baropy는 형태소 분석, 어절 나누기, 사용자 사전을 제공합니다. 맞춤법 교정은 들어 있지 않습니다. 교정이 필요하면 bareunpy로 클라우드 API를 쓰세요. bareunpy는 지금처럼 계속 쓸 수 있습니다.

구분bareunpybaropy
하는 일서버에 요청을 보내는 클라이언트서버를 담은 패키지(내 컴퓨터에서 직접 분석)
서버클라우드(api.bareun.ai)나 따로 설치한 서버가 필요패키지에 들어 있음
기능형태소 분석, 분절, 맞춤법 교정, 사용자 사전형태소 분석, 분절, 사용자 사전

설치

pip install bareun-baropy
항목내용
파이썬3.10 이상
운영체제리눅스 x86_64(glibc 2.28 이상), 리눅스 ARM64(glibc 2.34 이상). CPU 전용입니다. 윈도우와 macOS용은 준비되는 대로 알려 드립니다
API 키필요합니다. bareun.ai에서 받은 키를 그대로 씁니다
모델패키지에 넣지 않았습니다. 처음 부를 때 약 420MB를 내려받아 사용자 캐시 폴더에 둡니다

설치한 뒤 baropy version으로 버전을, baropy help로 이 설명서를 엽니다.


빠른 시작

import baropy

with baropy.Bareun(api_key="발급받은 API 키") as b:
    res = b.analyze("나는 어제 도서관에서 빌린 책을 읽었다.")
    for tok in res.tokens:
        print(tok.text, [(m.text, m.tag) for m in tok.morphemes])
나는 [('나', 'NP'), ('는', 'JX')]
어제 [('어제', 'NNG')]
도서관에서 [('도서관', 'NNG'), ('에서', 'JKB')]
빌린 [('빌리', 'VV'), ('ㄴ', 'ETM')]
책을 [('책', 'NNG'), ('을', 'JKO')]
읽었다. [('읽', 'VV'), ('었', 'EP'), ('다', 'EF'), ('.', 'SF')]

API 키를 환경변수 BAREUN_API_KEY에 넣어 두면 객체를 만들지 않고 baropy.analyze("문장")처럼 바로 부를 수도 있습니다. 키 등록은 처음 부를 때 패키지가 알아서 합니다.

첫 호출은 오래 걸릴 수 있습니다

처음 한 번은 모델을 내려받고 올리느라 수 초에서 몇 분이 걸립니다(회선에 따라 다릅니다). 그 뒤로는 받아 둔 모델을 쓰고, 호출은 수십 밀리초에 끝납니다.


결과 구조

결과는 호출 한 번이 Analysis 하나이고, 그 아래로 문장, 어절, 형태소 순서입니다. 모든 결과 객체는 읽기 전용이며, 아래층에서 위층으로 되짚어 올라갈 수 있습니다.

classDiagram
  Analysis "1" o-- "*" Sentence
  Sentence "1" o-- "*" Token
  Token "1" o-- "*" Morpheme
  Morpheme --> Token : token
  Morpheme --> Sentence : sentence
res = b.analyze("나는 책을 읽었다.")

s = res.sentences[0]                  # 문장
tok = s.tokens[1]                     # 어절 '책을'
m = tok.morphemes[0]                  # 형태소 '책'
print(m.text, m.tag, m.index)         # 책 NNG 2   (index 는 문장 안 형태소 순번)
print(m.token.text, m.sentence.index) # 책을 0     (형태소에서 어절과 문장으로 올라감)
print(m.span.begin, m.span.length)    # 원문 안 위치(글자 단위)
객체주요 속성
Analysissentences, tokens, morphemes, stats()
Sentenceindex, text, span, tokens, morphemes, stats()
Tokenindex, text, span, morphemes, sentence, stats()
Morphemetext, tag, index, span, probability, out_of_vocab, vocab, sense, custom_dict_name, token, sentence

vocab은 낱말의 출처(IN_WORD_EMBEDDING, OUT_OF_VOCAB, IN_CUSTOM_DICT, IN_BUILTIN_DICT 등)이고, out_of_vocab은 그것이 미등록단어(OUT_OF_VOCAB)인지 여부입니다. IN_URIMALSAEM, IN_WIKI_DICT, IN_ON_DICT는 맞춤법 검사기에서만 나타나므로 baropy에서는 보이지 않습니다.

형태소를 배열로 꺼내 쓰기

문장, 어절, 호출 전체의 morphemes는 모두 같은 MorphemeSeq(형태소 배열)입니다. 인덱스, 슬라이스, len, 반복문을 쓸 수 있고, 아래 메서드는 원본을 바꾸지 않습니다.

seq = res.morphemes                   # 호출 전체의 형태소
seq.texts()                           # ['나', '는', '책', '을', '읽', '었', '다', '.']
seq.pairs()                           # [('나', 'NP'), ('는', 'JX'), ...]
seq.tagged()                          # '나/NP 는/JX 책/NNG 을/JKO ...'
seq.nouns().texts()                   # ['책']  (NNG, NNP)
seq.verbs().texts()                   # ['읽']  (VV)
seq.select("N").texts()               # ['나', '책']  (N 으로 시작하는 태그 모두)
seq.select("J", exclude="JKO")        # 조사에서 목적격 조사만 뺀 것
seq.select(min_probability=0.9)       # 확률이 0.9 이상인 형태소
seq.select(oov=True)                  # 미등록단어만
seq.where(lambda m: len(m.text) > 1)  # 조건 함수로 고르기
메서드돌려주는 것
texts(), pairs(), tagged(sep=" ")글자 목록, (글자, 태그) 목록, 글자/태그 문자열
select(tags, exclude=, min_probability=, oov=)조건에 맞는 MorphemeSeq. 태그는 접두어로 맞춥니다("NN"은 NNG, NNP, NNB)
where(조건함수)조건 함수가 참인 MorphemeSeq
nouns(), verbs(), adjectives(), adverbs()각각 NNG·NNP, VV, VA, MAG·MAJ
tokens()이 형태소들이 속한 어절 목록(중복 없이)

nouns()는 일반명사와 고유명사만 봅니다. 의존명사, 수사, 대명사까지 넓게 보려면 select("N")을 쓰세요.

여러 문장을 한 번에, 호출 단위 통계

문자열 목록을 주면 항목 하나가 문장 하나이고, 결과의 sentences[i]가 입력 i번째와 1:1로 맞습니다. 호출 한 번의 결과가 Analysis 하나이므로 그 단위로 통계를 낼 수 있습니다.

res = b.analyze(["바른은 빠르다.", "책을 읽는다."])

st = res.stats()
print(st.sentence_count, st.token_count, st.morpheme_count, st.oov_count)
print(st.tokens_per_sentence, st.morphemes_per_token)   # 문장당 어절 수, 어절당 형태소 수 평균
print(res.tag_counts())                                  # {'NNG': 1, 'JKO': 1, ...} 많은 순
print(res.frequency("N", top=5))                         # 명사류 빈도 [('책', 1), ...]
print(res.frequency(by="pair", top=3))                   # 글자/태그 별 빈도
st.to_dict()                                             # JSON 으로 바꿀 수 있는 dict

문장, 어절, MorphemeSeq에도 같은 stats(), tag_counts(), frequency()가 있어 그 범위만의 통계를 냅니다. 문자열 하나를 주면 서버가 문장을 나눕니다(split_sentences=False면 통째로 한 문장으로 봅니다).

동형이의어 의미 구분

b.analyze(문장, sense=True)로 부르면 형태소마다 sense(sense_no, meaning, probability)가 실립니다. 자세한 내용은 동형이의어 의미 구분 API를 보세요.

어절 나누기

for t in b.tokenize("나는 책을 읽었다."):
    print(t.text, t.segments)    # 나는 ('나', '는')

사용자 사전

b.dicts로 사용자 사전을 정의하고 조회하고 지웁니다. 사전은 이름 하나 아래에 종류별 낱말 목록이 들어 있습니다. 이름은 영문자, 숫자, _, -만 쓸 수 있고 서버가 소문자로 바꿉니다.

종류뜻
np고유명사
cp복합명사
cp_caret복합명사 분리(^로 나눌 자리를 적습니다)
vv, va동사, 형용사
mm, mag, ic관형사, 부사, 감탄사
b.dicts.put("lab", np=["바른형태소분석기"], cp=["자연어처리"])   # 정의
print(b.dicts.list())                                           # [DictInfo(name='lab', counts={'np': 1, ...})]
print(b.dicts.get("lab").words("np"))                           # ['바른형태소분석기']

res = b.analyze(["바른형태소분석기는 빠르다."], dicts=["lab"])    # 이 호출에서만 쓸 사전
m = res.morphemes[0]
print(m.text, m.tag, m.custom_dict_name)                        # 바른형태소분석기 NNP lab

b.default_dicts = ["lab"]            # 이후 호출의 기본 사전(생성 때 default_dicts= 로도 줍니다)
b.dicts.check_conflicts("lab")       # 사전 사이 충돌·중복 점검
b.dicts.remove("lab")                # 지우기(전부 지우려면 b.dicts.clear())

정의는 그 이름의 사전 전체를 바꿔치기합니다

put은 서버 규약대로 같은 이름의 기존 낱말을 모두 지우고 새로 올립니다. 낱말을 더하려면 get으로 받아 add한 뒤 put하세요(ud = b.dicts.get("lab"); ud.add("np", "새말"); b.dicts.put(ud)). dicts=에 여러 사전을 주면 앞에 적은 사전이 우선합니다.

사전은 캐시 폴더에 저장되므로 프로그램을 다시 켜도 남아 있습니다. 사전 서비스 자체는 사용자 사전 API를 보세요.


모델을 올리고 내리는 때

모델은 첫 분석에서 올리고, 아래 경우에 내립니다. 내려간 뒤에 다시 부르면 저절로 다시 올라옵니다(수 초).

경우옵션
b.release()를 부르거나 with 블록을 나갈 때
호출이 없는 채로 시간이 지났을 때(기본 3600초)idle_timeout (None이면 끔)
올린 지 정해진 시간이 지났을 때(기본 끔)session_timeout
파이썬 프로그램이 끝났을 때(kill -9로 죽어도 마찬가지)항상

분석 서버는 파이썬 프로세스의 숨은 자식 프로세스로 돌고, 부모와 연결이 끊기면 스스로 끝납니다. 같은 객체를 여러 스레드가 동시에 불러도 됩니다.

생성 옵션

옵션기본설명
api_key환경변수 BAREUN_API_KEYAPI 키(필수)
idle_timeout3600.0호출이 없을 때 모델을 내리는 초
session_timeoutNone올린 뒤 이 초가 지나면 내림
threads4추론 스레드 수
cache_dir사용자 캐시 폴더모델, 사전, 로그를 두는 곳
start_timeout1800.0첫 실행의 모델 내려받기를 기다리는 한도(초)
default_dicts()호출마다 기본으로 쓸 사용자 사전
backgroundFalseTrue면 서버 모드(아래)

서버 모드

기본은 프로세스마다 자식 서버를 하나씩 띄우는 방식입니다. 여러 프로세스가 같은 서버를 나눠 쓰려면 서버 모드를 씁니다. baropy.Bareun(background=True, port=5656)로 만들면 그 포트의 서버를 쓰고, 없으면 부모와 떼어 낸 프로세스로 띄웁니다. 이 서버는 release()로 끝나지 않으므로 b.shutdown_server()나 명령행 baropy stop으로 끝냅니다.

서버 모드의 보안 유의점

서버 모드는 그 포트에 떠 있는 프로세스가 바른 서버인지 확인할 수 없고, 거기에 API 키를 등록 요청으로 보냅니다. 기본 주소(127.0.0.1)는 내 컴퓨터 안이지만, 같은 컴퓨터를 여러 사용자가 쓴다면 다른 사용자가 같은 포트를 먼저 열어 둘 수 있습니다. 그런 환경이나 host를 다른 컴퓨터로 바꾸는 경우에는 믿을 수 있는 서버인지 확인한 뒤에 쓰세요. 기본 방식(프로세스마다 자식 서버)은 요청마다 무작위 토큰을 붙이므로 이 문제가 없습니다.


명령행

명령하는 일
baropy help이 설명서를 엽니다(로캘이 한국어면 한국어판)
baropy version패키지 버전
baropy serve서버를 앞에서 실행합니다
baropy stop서버 모드로 띄운 서버를 끝냅니다
baropy registerAPI 키를 서버에 등록합니다(BAREUN_API_KEY 환경변수)
baropy fetch모델을 미리 내려받아 둡니다

오류

모든 오류는 baropy.BaropyError의 하위 클래스입니다.

예외언제
AuthErrorAPI 키가 없거나 거부됐을 때
ModelFetchError모델 내려받기에 실패했을 때
ServerStartError숨은 서버가 켜지지 못했을 때(오류 메시지에 로그 끝부분이 들어갑니다)
AnalysisError분석 요청이 거부됐을 때

잘못된 인자(0 이하의 타임아웃, 이름 규칙에 어긋난 사전 이름 등)는 ValueError입니다.


라이선스

baropy는 상용 독점 라이선스입니다. 자세한 내용은 이용약관을 보세요.

파이썬 패키지(baropy, 서버 내장) | 바른 도움말