Kiwi.h

Kiwi C++ API를 담고 있는 헤더 파일

Author: bab2min (bab2min@gmail.com)
Version: 0.20.0
Date: 2024-07-01

namespace kiwi

Functions

inline uint32_t getDefaultMorphemeId(POSTag tag)

class Kiwi

#include <Kiwi.h>

실제 형태소 분석을 수행하는 클래스.

Public Types

enum class SpecialMorph

Values:

enumerator singleQuoteOpen

enumerator singleQuoteClose

enumerator singleQuoteNA

enumerator doubleQuoteOpen

enumerator doubleQuoteClose

enumerator doubleQuoteNA

enumerator max

Public Functions

Kiwi(ArchType arch = ArchType::default_, LangModel _langMdl = {}, bool typoTolerant = false, bool continualTypoTolerant = false, bool lengtheningTypoTolerant = false): 빈 Kiwi 객체를 생성한다.

Note

이 생성자는 기본 생성자로 이를 통해 생성된 객체는 바로 형태소 분석에 사용할 수 없다. kiwi::KiwiBuilder 를 통해 생성된 객체만이 형태소 분석에 사용할 수 있다.

~Kiwi()

Kiwi(const Kiwi&) = delete

Kiwi(Kiwi&&) noexcept

Kiwi &operator=(const Kiwi&) = delete

Kiwi &operator=(Kiwi&&)

inline bool ready() const

현재 Kiwi 객체가 형태소 분석을 수행할 준비가 되었는지를 알려준다.

Note

기본 생성자를 통해 생성된 경우 언제나 ready() == false이며, kiwi::KiwiBuilder를 통해 생성된 경우 ready() == true이다.

Returns:: 형태소 분석 준비가 완료된 경우 true를 반환한다.

inline ArchType archType() const

inline bool isTypoTolerant() const

현재 Kiwi 객체가 오타 교정 기능이 켜진 상태로 생성되었는지 알려준다.

Returns:: 오타 교정 기능이 켜진 경우 true를 반환한다.

inline TokenResult analyze(const std::u16string &str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

Parameters:

str –
matchOptions –

Returns:

TokenResult

inline TokenResult analyze(const std::string &str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

Parameters:

str –
matchOptions –

Returns:

TokenResult

std::vector<TokenResult> analyze(const std::u16string &str, size_t topN, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

Parameters:

str –
topN –
matchOptions –

Returns:

std::vector<TokenResult>

inline std::vector<TokenResult> analyze(const std::string &str, size_t topN, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

Parameters:

str –
topN –
matchOptions –

Returns:

std::vector<TokenResult>

std::future<std::vector<TokenResult>> asyncAnalyze(const std::string &str, size_t topN, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

Parameters:

str –
topN –
matchOptions –

Returns:

std::future<std::vector<TokenResult>>

std::future<std::vector<TokenResult>> asyncAnalyze(std::string &&str, size_t topN, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, std::vector<PretokenizedSpan> &&pretokenized = {}) const

std::future<TokenResult> asyncAnalyze(const std::string &str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

std::future<TokenResult> asyncAnalyze(std::string &&str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, std::vector<PretokenizedSpan> &&pretokenized = {}) const

std::future<std::pair<TokenResult, std::string>> asyncAnalyzeEcho(std::string &&str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, std::vector<PretokenizedSpan> &&pretokenized = {}) const

std::future<std::vector<TokenResult>> asyncAnalyze(const std::u16string &str, size_t topN, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

std::future<std::vector<TokenResult>> asyncAnalyze(std::u16string &&str, size_t topN, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, std::vector<PretokenizedSpan> &&pretokenized = {}) const

std::future<TokenResult> asyncAnalyze(const std::u16string &str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, const std::vector<PretokenizedSpan> &pretokenized = {}) const

std::future<TokenResult> asyncAnalyze(std::u16string &&str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, std::vector<PretokenizedSpan> &&pretokenized = {}) const

std::future<std::pair<TokenResult, std::u16string>> asyncAnalyzeEcho(std::u16string &&str, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr, std::vector<PretokenizedSpan> &&pretokenized = {}) const

template<class ReaderCallback, class ResultCallback> inline void analyze(size_t topN, ReaderCallback &&reader, ResultCallback &&resultCallback, Match matchOptions, const std::unordered_set<const Morpheme*> *blocklist = nullptr) const

Template Parameters:

ReaderCallback –
ResultCallback –

Parameters:

topN –
reader –
resultCallback –
matchOptions –

std::vector<std::pair<size_t, size_t>> splitIntoSents(const std::u16string &str, Match matchOptions = Match::allWithNormalizing, TokenResult *tokenizedResultOut = nullptr) const

Parameters:

str –
matchOptions –
tokenizedResultOut –

Returns:

std::vector<pair<size_t, size_t>>

std::vector<std::pair<size_t, size_t>> splitIntoSents(const std::string &str, Match matchOptions = Match::allWithNormalizing, TokenResult *tokenizedResultOut = nullptr) const

Parameters:

str –
matchOptions –
tokenizedResultOut –

Returns:

std::vector<pair<size_t, size_t>>

cmb::AutoJoiner newJoiner(bool lmSearch = true) const

형태소들을 결합하여 텍스트로 복원해주는 작업을 수행하는 AutoJoiner를 반환한다.

See also

kiwi::cmb::AutoJoiner

Parameters:: lmSearch – 결합 전에 언어 모델을 이용하여 최적의 형태소를 탐색하여 사용한다.
Returns:: 새 AutoJoiner 인스턴스

std::unique_ptr<LmObjectBase> newLmObject() const: Kiwi에 내장된 언어 모델에 접근할 수 있는 LmObject 객체를 생성한다.

std::u16string getTypoForm(size_t typoFormId) const

TokenInfo::typoFormId로부터 실제 오타 형태를 복원한다.

Parameters:: typoFormId – analyze함수의 리턴으로 반환된 TokenInfo 내의 typoFormId 값
Returns:: 복원된 오타의 형태

inline size_t morphToId(const Morpheme *morph) const

inline size_t getSpecialMorphId(SpecialMorph type) const

inline SpecialMorph determineSpecialMorphType(size_t morphId) const

inline size_t getMorphemeSize() const

inline const Morpheme *idToMorph(size_t morphId) const

inline size_t getNumThreads() const

inline utils::ThreadPool *getThreadPool() const

inline float getCutOffThreshold() const

inline void setCutOffThreshold(float v)

inline float getUnkScoreBias() const

inline void setUnkScoreBias(float v)

inline float getUnkScoreScale() const

inline void setUnkScoreScale(float v)

inline size_t getMaxUnkFormSize() const

inline void setMaxUnkFormSize(size_t v)

inline size_t getSpaceTolerance() const

inline void setSpaceTolerance(size_t v)

inline float getSpacePenalty() const

inline void setSpacePenalty(float v)

inline float getTypoCostWeight() const

inline void setTypoCostWeight(float v)

inline bool getIntegrateAllomorph() const

inline void setIntegrateAllomorph(bool v)

inline const lm::KnLangModelBase *getKnLM() const

void findMorpheme(std::vector<const Morpheme*> &out, const std::u16string &s, POSTag tag = POSTag::unknown) const

std::vector<const Morpheme*> findMorpheme(const std::u16string &s, POSTag tag = POSTag::unknown) const

Private Functions

inline const Morpheme *getDefaultMorpheme(POSTag tag) const

template<class LmState> inline cmb::AutoJoiner newJoinerImpl() const

template<class Str, class Pretokenized, class ...Rest> auto _asyncAnalyze(Str &&str, Pretokenized &&pt, Rest&&... args) const

template<class Str, class Pretokenized, class ...Rest> auto _asyncAnalyzeEcho(Str &&str, Pretokenized &&pt, Rest&&... args) const

Private Members

bool integrateAllomorph = true

float cutOffThreshold = 8

float unkFormScoreScale = 5

float unkFormScoreBias = 5

float spacePenalty = 7

float typoCostWeight = 6

float continualTypoCost = INFINITY

float lengtheningTypoCost = INFINITY

size_t maxUnkFormSize = 6

size_t spaceTolerance = 0

TagSequenceScorer tagScorer

Vector<Form> forms

Vector<Morpheme> morphemes

KString typoPool

Vector<size_t> typoPtrs

Vector<TypoForm> typoForms

utils::FrozenTrie<kchar_t, const Form*> formTrie

LangModel langMdl

std::shared_ptr<cmb::CompiledRule> combiningRule

std::unique_ptr<utils::ThreadPool> pool

ArchType selectedArch = ArchType::none

void *dfSplitByTrie = nullptr

void *dfFindForm = nullptr

void *dfFindBestPath = nullptr

std::array<size_t, static_cast<size_t>(SpecialMorph::max)> specialMorphIds = {{0,}}

Private Static Functions

static std::vector<PretokenizedSpan> mapPretokenizedSpansToU16(const std::vector<PretokenizedSpan> &orig, const std::vector<size_t> &bytePositions)

Friends

friend class KiwiBuilder

friend class PathEvaluator

friend class cmb::AutoJoiner

friend struct NewAutoJoinerGetter

class KiwiBuilder

#include <Kiwi.h>

형태소 분석에 사용될 사전을 관리하고, 사전을 바탕으로 실제 형태소 분석을 수행하는 Kiwi의 인스턴스를 생성하는 클래스.

Public Types

using TokenFilter = std::function<bool(const std::u16string&, POSTag)>

Public Functions

KiwiBuilder(): KiwiBuilder의 기본 생성자

Note

이 생성자로 생성된 경우 ready() == false인 상태이므로 유효한 Kiwi 객체를 생성할 수 없다.

~KiwiBuilder()

KiwiBuilder(const KiwiBuilder&)

KiwiBuilder(KiwiBuilder&&) noexcept

KiwiBuilder &operator=(const KiwiBuilder&)

KiwiBuilder &operator=(KiwiBuilder&&)

KiwiBuilder(const ModelBuildArgs &args): KiwiBuilder를 raw 데이터로부터 생성한다.

Note

이 함수는 현재 내부적으로 기본 모델 구축에 쓰인다. 추후 공개 데이터로도 쉽게 직접 모델을 구축할 수 있도록 개선된 API를 제공할 예정.

KiwiBuilder(const std::string &modelPath, const ModelBuildArgs &args): 기본 모델로부터 확장 모델을 학습하여 생성한다.

KiwiBuilder(const std::string &modelPath, size_t numThreads = 0, BuildOption options = BuildOption::default_, bool useSBG = false)

KiwiBuilder를 모델 파일로부터 생성한다.

Parameters:

modelPath – 모델이 위치한 경로
numThreads – 모델 및 형태소 분석에 사용할 스레드 개수
options – 생성 옵션. kiwi::BuildOption을 참조

inline bool ready() const

현재 KiwiBuilder 객체가 유효한 분석 모델을 로딩한 상태인지 알려준다.

Returns:: 유효한 상태면 true를 반환한다. 기본 생성자로 생성한 경우 ready() == false이며, 다른 생성자로 생성한 경우는 ready() == true이다.

void saveModel(const std::string &modelPath) const

std::pair<uint32_t, bool> addWord(const std::u16string &form, POSTag tag = POSTag::nnp, float score = 0)

사전에 새로운 형태소를 추가한다. 이미 동일한 형태소가 있는 경우는 무시된다.

Note

이 방법으로 추가된 형태소는 언어모델 탐색에서 어휘 사전 외 토큰(OOV 토큰)으로 처리된다. 이 방법으로 추가된 형태소는 항상 분석 과정에서 최우선으로 탐색되지는 않으므로 최상의 결과를 위해서는 score 값을 조절할 필요가 있다. score 값을 높게 설정할수록 다른 후보들과의 경쟁에서 이 형태소가 더 높은 점수를 받아 최종 분석 결과에 노출될 가능성이 높아진다. 만약 이 방법으로 추가된 형태소가 원치 않는 상황에서 과도하게 출력되는 경우라면 score를 더 작은 값으로, 반대로 원하는 상황에서도 출력되지 않는 경우라면 score를 더 큰 값으로 조절하는 게 좋다.

Parameters:

form – 새로운 형태소의 형태
tag – 품사 태그
score – 페널티 점수. 이에 대한 자세한 설명은 하단의 note 참조.

Returns:

추가된 형태소의 ID와 성공 여부를 pair로 반환한다. form/tag 형태소가 이미 존재하는 경우 추가에 실패한다.

std::pair<uint32_t, bool> addWord(const char16_t *form, POSTag tag = POSTag::nnp, float score = 0)

std::pair<uint32_t, bool> addWord(const std::u16string &newForm, POSTag tag, float score, const std::u16string &origForm)

사전에 기존 형태소의 변이형을 추가한다. 이미 동일한 형태소가 있는 경우는 무시된다.

Note

이 방법으로 추가된 형태소는 언어모델 탐색 과정에서 origForm/tag 토큰으로 처리된다.

Parameters:

newForm – 새로운 형태
tag – 품사 태그
score – 새로운 형태의 페널티 점수. 이에 대한 자세한 설명은 하단의 addWord함수의 note 참조.
origForm – 기존 형태

Throws:

kiwi::UnknownMorphemeException – `origForm/tag`에 해당하는 형태소가 없을 경우 예외를 발생시킨다.

Returns:

추가된 형태소의 ID와 성공 여부를 pair로 반환한다. newForm/tag 형태소가 이미 존재하는 경우 추가에 실패한다.

std::pair<uint32_t, bool> addWord(const char16_t *newForm, POSTag tag, float score, const char16_t *origForm)

bool addPreAnalyzedWord(const std::u16string &form, const std::vector<std::pair<std::u16string, POSTag>> &analyzed, std::vector<std::pair<size_t, size_t>> positions = {}, float score = 0)

사전에 기분석 형태소열을 추가한다. 이미 동일한 기분석 형태소열이 있는 경우는 무시된다.

Note

이 함수는 특정 문자열이 어떻게 분석되어야하는지 직접적으로 지정해줄 수 있다. 따라서 addWord 함수를 사용해도 오분석이 발생하는 경우, 이 함수를 통해 해당 사례들에 대해 정확한 분석 결과를 추가하면 원하는 분석 결과를 얻을 수 있다.

Parameters:

form – 분석될 문자열 형태
analyzed – form 문자열이 입력되었을 때, 이의 분석결과로 내놓을 형태소의 배열
positions – analyzed의 각 형태소가 form내에서 차지하는 위치(시작/끝 지점, char16_t 단위). 생략 가능
score – 페널티 점수. 이에 대한 자세한 설명은 하단의 addWord함수의 note 참조.

Throws:

kiwi::UnknownMorphemeException – `analyzed`로 주어진 형태소 중 하나라도 존재하지 않는게 있는 경우 예외를 발생시킨다.

Returns:

형태소열을 추가하는데 성공했으면 true, 동일한 형태소열이 존재하여 추가에 실패한 경우 false를 반환한다.

bool addPreAnalyzedWord(const char16_t *form, const std::vector<std::pair<const char16_t*, POSTag>> &analyzed, std::vector<std::pair<size_t, size_t>> positions = {}, float score = 0)

template<class Replacer> inline std::vector<std::pair<uint32_t, std::u16string>> addRule(POSTag tag, Replacer &&repl, float score = 0)

규칙에 의해 변형된 형태소 목록을 생성하여 자동 추가한다.

Parameters:

tag –
repl –
score –

Returns:

새로 추가된 변형된 형태소의 ID와 그 형태를 pair로 묶은 목록

size_t loadDictionary(const std::string &dictPath)

Parameters:: dictPath –
Returns:

std::vector<WordInfo> extractWords(const U16MultipleReader &reader, size_t minCnt = 10, size_t maxWordLen = 10, float minScore = 0.25, float posThreshold = -3, bool lmFilter = true) const

std::vector<WordInfo> extractAddWords(const U16MultipleReader &reader, size_t minCnt = 10, size_t maxWordLen = 10, float minScore = 0.25, float posThreshold = -3, bool lmFilter = true)

Kiwi build(const TypoTransformer &typos = {}, float typoCostThreshold = 2.5f) const

현재 단어 및 사전 설정을 기반으로 Kiwi 객체를 생성한다.

Parameters:

typos –
typoCostThreshold –

Returns:

형태소 분석 준비가 완료된 Kiwi의 객체.

inline Kiwi build(DefaultTypoSet typos, float typoCostThreshold = 2.5f) const

void convertHSData(const std::vector<std::string> &inputPathes, const std::string &outputPath, const std::string &morphemeDefPath = {}, size_t morphemeDefMinCnt = 0) const

HSDataset makeHSDataset(const std::vector<std::string> &inputPathes, size_t batchSize, size_t causalContextSize, size_t windowSize, size_t numWorkers, double dropoutProb = 0, double dropoutProbOnHistory = 0, const TokenFilter &tokenFilter = {}, const TokenFilter &windowFilter = {}, double splitRatio = 0, bool separateDefaultMorpheme = false, const std::string &morphemeDefPath = {}, size_t morphemeDefMinCnt = 0, HSDataset *splitDataset = nullptr) const

Private Types

using MorphemeMap = UnorderedMap<std::tuple<KString, uint8_t, POSTag>, std::pair<size_t, size_t>>

Private Functions

void loadMorphBin(std::istream &is)

void saveMorphBin(std::ostream &os) const

FormRaw &addForm(const KString &form)

size_t addForm(Vector<FormRaw> &newForms, UnorderedMap<KString, size_t> &newFormMap, KString form) const

void initMorphemes()

template<class Fn> MorphemeMap loadMorphemesFromTxt(std::istream &is, Fn &&filter)

MorphemeMap restoreMorphemeMap(bool separateDefaultMorpheme = false) const

template<class VocabTy> void _addCorpusTo(RaggedVector<VocabTy> &out, std::istream &is, MorphemeMap &morphMap, double splitRatio, RaggedVector<VocabTy> *splitOut) const

void addCorpusTo(RaggedVector<uint8_t> &out, std::istream &is, MorphemeMap &morphMap, double splitRatio = 0, RaggedVector<uint8_t> *splitOut = nullptr) const

void addCorpusTo(RaggedVector<uint16_t> &out, std::istream &is, MorphemeMap &morphMap, double splitRatio = 0, RaggedVector<uint16_t> *splitOut = nullptr) const

void addCorpusTo(RaggedVector<uint32_t> &out, std::istream &is, MorphemeMap &morphMap, double splitRatio = 0, RaggedVector<uint32_t> *splitOut = nullptr) const

void updateForms()

void updateMorphemes()

size_t findMorpheme(U16StringView form, POSTag tag) const

std::pair<uint32_t, bool> addWord(U16StringView newForm, POSTag tag, float score, size_t origMorphemeId, size_t lmMorphemeId)

std::pair<uint32_t, bool> addWord(const std::u16string &newForm, POSTag tag, float score, size_t origMorphemeId, size_t lmMorphemeId)

std::pair<uint32_t, bool> addWord(U16StringView form, POSTag tag = POSTag::nnp, float score = 0)

std::pair<uint32_t, bool> addWord(U16StringView newForm, POSTag tag, float score, U16StringView origForm)

template<class U16> bool addPreAnalyzedWord(U16StringView form, const std::vector<std::pair<U16, POSTag>> &analyzed, std::vector<std::pair<size_t, size_t>> positions = {}, float score = 0)

void addCombinedMorpheme(Vector<FormRaw> &newForms, UnorderedMap<KString, size_t> &newFormMap, Vector<MorphemeRaw> &newMorphemes, UnorderedMap<size_t, Vector<uint32_t>> &newFormCands, size_t leftId, size_t rightId, const cmb::Result &r) const

void addCombinedMorphemes(Vector<FormRaw> &newForms, UnorderedMap<KString, size_t> &newFormMap, Vector<MorphemeRaw> &newMorphemes, UnorderedMap<size_t, Vector<uint32_t>> &newFormCands, size_t leftId, size_t rightId, size_t ruleId) const

void buildCombinedMorphemes(Vector<FormRaw> &newForms, UnorderedMap<KString, size_t> &newFormMap, Vector<MorphemeRaw> &newMorphemes, UnorderedMap<size_t, Vector<uint32_t>> &newFormCands) const

void addAllomorphsToRule()

Private Members

Vector<FormRaw> forms

Vector<MorphemeRaw> morphemes

UnorderedMap<KString, size_t> formMap

LangModel langMdl

std::shared_ptr<cmb::CompiledRule> combiningRule

WordDetector detector

size_t numThreads = 0

BuildOption options = BuildOption::none 

ArchType archType = ArchType::none

struct ModelBuildArgs

Public Members

std::string morphemeDef

std::vector<std::string> corpora

size_t minMorphCnt = 10

size_t lmOrder = 4

std::vector<size_t> lmMinCnts = {1}

size_t numWorkers = 1

size_t sbgSize = 1000000

bool useLmTagHistory = true

bool quantizeLm = true

bool compressLm = true

float dropoutSampling = 0.05f

float dropoutProb = 0.15f

namespace cmb