# khaiii Korean Morphological Analysis with CNN Models

> khaiii is Kakao Hangul Analyzer III, a data-driven Korean morphological analyzer built around CNN models and trained on a large corpus. It offers base and large models plus two user dictionaries, but the README leaves installation and API usage to separate wiki documentation.

**kakao/khaiii** — Kakao Hangul Analyzer III

- Repository: https://github.com/kakao/khaiii
- Stars: 1,455 · Forks: 297
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/kakao-khaiii

## Why khaiii Targets Korean Morphological Analysis

khaiii addresses Korean morphological analysis, the task of dividing written text into morphemes that carry identifiable linguistic meaning. Kakao describes it as its third morphological analyzer, following the dha2 name used by the second version. The target audience is developers who need a Korean text-processing stage before higher-level NLP work such as parsing or semantic analysis. That position matters because downstream components usually expect text divided into units with part-of-speech tags rather than an undivided sentence.

The project makes a deliberate departure from dictionary-and-rule systems. Its models learn analysis patterns from data, with a CNN serving as the classifier. Kakao reports training on approximately 850,000 sentences and ten million eojeol from a corrected and partly extended version of the National Institute of Korean Language's 21st Century Sejong Project final output. Sentences that caused preprocessing errors were excluded. The README does not document domain adaptation or retraining commands, so the documented strength is centered on the training corpus rather than arbitrary new domains.

## How khaiii's CNN Context Model Produces Tags

The model operates around the syllable being classified. Its main hyperparameters are `win`, which defines the size of the left and right context, and `emb`, which defines the syllable embedding dimension. Kakao evaluated 6 values of `win` and 10 values of `emb`, producing 60 combinations. The documented architecture is a Convolutional Neural Network, selected instead of LSTM or other recurrent architectures because morphological analysis was treated as a latency-sensitive preprocessing operation.

The project publishes two model sizes. The v0.4 base model uses `win=4` and `emb=35`, with a reported F-Score of 94.96. The large model uses `win=4` and `emb=180`, with an F-Score of 96.71. Earlier v0.3 experiments reported 97.11 for `win=3`, `emb=150`, but that figure belongs to a different model version and should not be presented as the v0.4 large-model result. The README also explains that increasing the context beyond `win=3` or `win=4` reduced performance in the v0.3 experiment, while embedding gains flattened after 150 dimensions.

This model selection exposes a direct speed and accuracy trade-off. Kakao reports analyzing 10,000 sentences totaling 903KB, with an average sentence length of 91. For v0.3, the base model took about 10.5 seconds and the large model about 78.8 seconds. In the later v0.4 measurements, base processing rose to 14.4 and large processing to 165. These figures come from the project's documented comparison setup; the README does not state hardware, operating system, compiler settings, or enough context to reproduce them independently.

## Spacing Errors Shape the v0.4 Model Choice

The v0.4 models were revised after separate experiments on resistance to spacing errors. According to the README, v0.4 performs better on input whose spacing is not handled well, while its accuracy on the Sejong corpus decreases somewhat. Kakao then changed the parameters of both base and large rather than simply shipping a model optimized for clean corpus-style text.

That compromise is important for prospective users. A model selected on carefully segmented Sejong data may not be the best choice for noisy OCR output, informal messages, preprocessing output with unusual token boundaries, or text assembled from multiple sources. A model tuned for spacing tolerance may give up accuracy under the corpus conditions used for measurement. The README does not publish the spacing-error experiment's dataset size, exact error distribution, or complete F-Score, so it supports only a qualitative comparison.

For an adoption decision, the appropriate question is therefore not whether v0.4 has one universal accuracy number. Teams should compare the base and large models against representative input, especially inputs containing inconsistent spacing. The project's published 14.4 and 165 measurements also indicate that large-model use should be justified by an accuracy requirement rather than selected by default.

## Installing khaiii and Reaching a First Analysis

The README does not give a standalone installation or first-use tutorial. It directs users to the repository's Build and installation wiki page, so there is no verified `pip install` command, package name, Python invocation, CLI syntax, model download command, or output example that can safely be reproduced here. The repository includes `CMakeLists.txt`, a `cmake/` directory, `docker/`, `requirements.txt`, and source directories, which indicates a native build setup rather than establishing a documented Python package.

The only visible dependency constraint is the repository's `requirements.txt`, which lists `cmake>=3.10`. That entry is relevant to building the project, but it is not a complete installation procedure. It does not identify the compiler, platform matrix, Python package version, model artifact location, or runtime dependency set.

A first real use therefore needs to begin with the linked build guide rather than with an invented command. The guide should establish how the analyzer executable or library is built, how a base or large model is obtained, and where model files must be placed. After that, a practical first check would feed a short Korean sentence through the documented interface and inspect the emitted morphemes and tags. The README itself gives examples of dictionary entries and corrected analysis, but it does not show the invocation that produces them.

## User Dictionaries Control Opaque Model Errors

khaiii adds two mechanisms around the neural analyzer because model decisions are difficult to trace directly. The preanalysis dictionary handles a single eojeol whose analysis should remain the same regardless of context. An entry such as `이더리움* | 이더리움/NNP` causes matching input to bypass the neural model and receive the declared analysis. Kakao says an automatically extracted dictionary from unambiguous Sejong entries can contain about 80,000 entries.

The README reports applying that extracted dictionary to the base model reduced processing of its 10,000-sentence comparison set from about 10.5 seconds to 9.2 seconds, an improvement of roughly 10 percent. That is a documented result for this particular dictionary, model, and text set, not a general promise that every deployment will become faster. A large dictionary also changes analytical precedence because matching words are resolved before model inference.

The misanalysis patch addresses a different case. It matches a complete erroneous sequence containing enough context to distinguish the correct result. The README's example replaces `이/JKS + _ + 다/VA + 른/MM + _ + 것/NNB` with `이/JKS + _ + 다르/VA + ㄴ/ETM + _ + 것/NNB` when the erroneous sequence appears. The underscore represents a word boundary. These controls are useful for known production failures, but they require exact corpus-aware rules. The README does not document conflict handling, patch precedence, regular-expression support, or a reload mechanism.

## Limitations, Alternatives, and Operational Cost

The clearest limitation is documentation depth at the adoption boundary. The project is marked as Python in the repository metadata, but the README points to a C++-style repository layout with CMake and does not document a Python package, import statement, wheel, or binding. Teams whose main requirement is `pip` installation and direct Python calls may find that the repository does not meet their workflow without an additional, undocumented integration layer.

A real alternative is a dictionary-and-rule-based Korean analyzer. khaiii replaces explicit lexical rules with corpus-trained CNN classification and can use learned context to resolve ambiguous forms. A rule-based system is harder to curate and update as vocabulary grows, but its behavior can usually be inspected and corrected through readable rules. khaiii trades that inspectability for learned contextual decisions, then compensates with preanalysis entries and whole-sequence patches. Neither approach dominates automatically: choose the learned model when representative accuracy matters more than transparent rule coverage, and consider the dictionary-and-rule model when deterministic, directly editable behavior is the priority.

The repository is not archived, and its last push was on 2026-10-10. However, the listed releases are old: v0.4 was released on 2019-06-17, v0.3 on 2019-02-12, and v0.2 on 2018-12-27. The project therefore has a recent repository push but no newer tagged release in the listed versions. Upgrading requires checking compatibility of models, dictionary formats, build dependencies, and any local patches across khaiii versions. Apache-2.0 permits use and modification under its conditions, including preservation of license notices and the stated warranty and liability terms; this is not legal advice.

## Conclusion

Adopt khaiii when Korean text preprocessing and corpus-trained morphological analysis justify a native build and model selection. Do not choose it when you need documented Python packaging, a public API, or confirmed deployment support without first resolving those gaps. Check the linked build guide, available model artifacts, platform prerequisites, and the behavior of your own text before integration, especially text with irregular spacing.

## FAQ

### What problem does khaiii solve?

khaiii performs Korean morphological analysis by dividing text into morphemes with part-of-speech information. Kakao positions it as a foundational preprocessing stage for higher-level NLP work.

### How do I install khaiii?

The README directs users to its Build and installation wiki page rather than providing complete steps. The visible requirements file specifies `cmake>=3.10`, but compiler, platform, model setup, and runtime instructions are not included in the README.

### Should I use the base or large khaiii model?

The v0.4 base model emphasizes lower processing cost, while the large model has a higher reported F-Score but substantially slower documented processing. The README reports base and large times of 14.4 and 165 for its v0.4 comparison set.

### How can khaiii correct known analysis errors?

A preanalysis dictionary can force a consistent result for a matching single word without neural inference. A misanalysis patch can replace a specified erroneous sequence when it occurs within a longer context.

## Sources

- [Issues](https://github.com/kakao/khaiii/issues)
- [kakao/khaiii on GitHub](https://github.com/kakao/khaiii)
- [License: Apache-2.0](https://github.com/kakao/khaiii/blob/master/LICENSE)
- [README](https://github.com/kakao/khaiii/blob/master/README.md)
- [Releases](https://github.com/kakao/khaiii/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kakao-khaiii