Quick Start
If you want to try it without installing anything
After signing up, follow 3 Fastest Ways to Try Bareun to see results within minutes. If you are curious about spell checking, also see the Bareun Spell Checker.
- Sign up at bareun.ai to get an API key. (After requesting sign-up, verify your email and find the key under 'Login - My Info'.)
- Install Bareun. After installing, register your API key. If you already know of an existing
Bareuninstallation, you can skip this step. - Install the client library.
- Write code that uses your API key.
The flowchart below shows the ways to use Bareun.
- Use the cloud service (supports the morphological analyzer and the spell checker)
- Use another server that is already installed (morphological analyzer only)
- Download and install (morphological analyzer only)
graph TD A1[Sign up at bareun.ai] --> B[API key issued automatically]; B --> CR[Bareun spell checker]; B --> AN[Bareun morphological analyzer]; CR --> CLOUD[Use the cloud service]; AN --> CLOUD[Use the cloud service]; AN --> PREVINST[If another server is already installed]; AN --> INST[Download and install]; CLOUD --> LIB[Install the library]; PREVINST --> LIB[Install the library]; INST --> LIB[Install the library]; LIB --> KEY[Copy the API key and apply it to the server]; KEY --> CODE[Write and run your code];
Download and Install
If you download and install Bareun, you must register your API key at the end. The steps are summarized below.
graph TD
ONPREMISE[Install and use];
ONPREMISE --> C{OS};
C --->|Linux/Debian| L[.deb];
C --->|Windows| W[.exe];
C -->|macOS| M[.pkg];
M --> INST[Download and install];
L --> INST[Download and install];
W --> INST[Download and install];
INST --> APIKEY[Register the API key];
Follow Along
First, get your API key ready. An API key looks like koba-ABCDEFG-1234567-LMNOPQR-7654321.
This page uses that fictional API key in its examples. koba is short for Key of bareun ai.
Use the Cloud Service
If you find installing Bareun cumbersome, you can use the cloud service. For the connection address, authentication, and other details, see Using the Cloud.
- Address: The server hosted in the cloud is
api.bareun.ai. - Port: 443. The service port differs from the local server's and is 443.
- TLS: The cloud service protects packets in transit from attackers with TLS encryption.
- Multiple APIs: You can use gRPC, gRPC-web, or REST.
- APIs: spell checker, morphological analyzer
The cloud service is paid
Both morphological analysis and spell checking are paid services. Think of the fee as the cost of the remote computing resources you use. It can be much cheaper than buying your own laptop or renting machines on cloud systems such as AWS, Azure, GCP, or Naver Cloud.
To use the paid service, go through the paid membership registration process.
Cloud free tier
The cloud service's free tier is up to 50,000 word units (eojeol).
You use api.bareun.ai through the API for the free tier as well.
Once you log in, you can check usage statistics in real time.
The spell checker is cloud-only
The spell checking service is available only on the cloud. If you want to use the spell checker in an air-gapped network, however, we support a separate installation. That is also paid.
Free for research purposes
Both morphological analysis and spell checking are free for research purposes. Submit an application stating the research title, purpose, methods and content, expected outcomes, acknowledgment, and whether the research will be made public. We can approve it after review.
The development process is very simple.
- Copy your API key
- Write your code
- Run it
Connect to Another Server That Is Already Installed
If you know of another server where Bareun is installed, using it is one option. In this case, you just need to know that server's address.
Enter the server's address and port in the API and you can use the service right away.
Download
The installable Bareun is the morphological analyzer only
The freely installable Bareun includes only the morphological analyzer. It is free as long as the use is not commercial.
With a paid contract, the Bareun spell checker can be installed
You can also install the Bareun spell checker on-premises. However, a separate contract process is required. Please contact bareun.license@bareun.ai.
- On Linux and macOS, you can install using wget or curl.
- On Windows, press ++win+r++, then type
cmdto open a command prompt. Windows 10 and later include curl. On earlier versions, download the file manually.
wget -nv --no-check-certificate --content-disposition --header "uname:$(uname -a)" https://bareun.ai/api/get
curl -OLJs -H "uname:$(uname -a)" https://bareun.ai/api/get
curl -OLJs -H "uname: windows, %PROCESSOR_ARCHITECTURE%" https://bareun.ai/api/get
docker pull bareunai/bareun:latest
Install
Automatic installation
On Linux, install with the standard Debian package. It works out of the box on Ubuntu and Mint. On Windows, you can also install directly with the installer.
On Linux, run it with root privileges. On Windows, running the command automatically elevates to administrator privileges.
On macOS, installation goes through a package install.
For OS-specific installation instructions, see Install with Docker · Install on Linux · Install on Windows · Install on macOS. The overall flow is summarized in the Installation Overview.
Manual installation
A manual installation proceeds in this order:
- Install in your home directory.
- Set the environment variables.
- Run the
Bareunexecutable in the background.
sudo apt install bareun-v3.4.0.linux-x86_64.deb
# or
sudo apt install bareun-v3.4.0.linux-arm64.deb
VER="v3.4.0"
tar xf bareun-$VER.linux-x86_64.tar.gz
echo export BAREUN_ROOT=$HOME/bareun-$VER >> ~/.bashrc
echo export PATH=$BAREUN_ROOT/bin:$PATH >> ~/.bashrc
. ~/.bashrc
nohup $BAREUN_ROOT/bin/bareun &
VER="v3.4.0"
tar xf bareun-$VER.linux-arm64.tar.gz
echo export BAREUN_ROOT=$HOME/bareun-$VER >> ~/.bashrc
echo export PATH=$BAREUN_ROOT/bin:$PATH >> ~/.bashrc
. ~/.bashrc
nohup $BAREUN_ROOT/bin/bareun &
VER="v3.4.0"
tar xf bareun-$VER.darwin-x86_64.tar.gz
echo export BAREUN_ROOT=$HOME/bareun-$VER >> ~/.bashrc
echo export PATH=$BAREUN_ROOT/bin:$PATH >> ~/.bashrc
. ~/.bashrc
nohup $BAREUN_ROOT/bin/bareun &
VER="v3.4.0"
tar xf bareun-$VER.darwin-arm64.tar.gz
echo export BAREUN_ROOT=$HOME/bareun-$VER >> ~/.bashrc
echo export PATH=$BAREUN_ROOT/bin:$PATH >> ~/.bashrc
. ~/.bashrc
nohup $BAREUN_ROOT/bin/bareun &
bareun-v3.4.0.windows-x86_64.exe
mkdir -p ~/bareun/var
docker run -d -p 5656:5656 -v ~/bareun/var:/bareun/var bareunai/bareun:latest
Register the API Key
To register your API key, open http://localhost:5656 on the system where Bareun is installed.
Alternatively, you can register it from the command line as follows.
/opt/bareun/bin/bareun -reg koba-ABCDEFG-1234567-LMNOPQR-7654321
$BAREUN_ROOT/bin/bareun -reg koba-ABCDEFG-1234567-LMNOPQR-7654321
$BAREUN_ROOT/bin/bareun -reg koba-ABCDEFG-1234567-LMNOPQR-7654321
c:\Program Files\bareun\bin\bareun -reg koba-ABCDEFG-1234567-LMNOPQR-7654321
docker exec bareun /bareun/bin/bareun -reg koba-ABCDEFG-1234567-LMNOPQR-7654321
Do not copy the API key shown here.
The example API key koba-ABCDEFG-1234567-LMNOPQR-7654321 used here
must be replaced with your own API key issued at bareun.ai.
Install the Python Library
python -m venv venv
. venv/bin/activate
pip install bareunpy
Write the Code
import sys
from bareunpy import Tagger
# Enter the API KEY ("koba-...") issued after email verification at "https://bareun.ai/". See "Login - My Info".
API_KEY="koba-ABCDEFG-1234567-LMNOPQR-7654321" # <- replace with your own API KEY
# Connect to the host you just installed.
tagger = Tagger(API_KEY, 'localhost')
# Get the results.
# Inputs: "안녕하세요." ("Hello.") and "바른을 사용해서 새로운 경험을 해보세요." ("Try a new experience with Bareun.")
res = tagger.tags(["안녕하세요.", "바른을 사용해서 새로운 경험을 해보세요."])
Print the Results
pos(): Prints morphemes with their tags.
# Extract the morphemes from the result.
pa = res.pos()
print(pa)
[('안녕하', 'VA'), ('시', 'EP'), ('어요', 'EF'), ('.', 'SF'),
('바른', 'NNP'), ('을', 'JKO'), ('사용하', 'VV'), ('아서', 'EC'),
('새롭', 'VA'), ('ㄴ', 'ETM'), ('경험', 'NNG'), ('을', 'JKO'),
('하', 'VV'), ('아', 'EC'), ('보', 'VX'), ('시', 'EP'),
('어요', 'EF'), ('.', 'SF')]
morphs(): Returns only the morphemes.
# Extract all morphemes.
ma = res.morphs()
print(ma)
['안녕하', '시', '어요', '.', '바른', '을', '사용하', '아서',
'새롭', 'ㄴ', '경험', '을', '하', '아', '보', '시', '어요', '.']
nouns(): Returns only the nominals (nouns, pronouns, numerals).
# Extract only the nominals.
va = res.nouns()
print(va)
['바른', '경험']
verbs(): Returns only the predicates (verbs and adjectives).
# Extract only the predicates.
va = res.verbs()
print(va)
['사용하', '하']
msg() or as_json_str(): Shows the full morphological analysis result.
# Extract the full analysis result.
m = print(res.as_json_str())
print(m)
{
"sentences": [
{
"text": {
"content": "안녕하세요.",
"length": 6,
"beginOffset": 0
},
"tokens": [
{
"text": {
"content": "안녕하세요.",
"length": 6,
"beginOffset": 0
},
"morphemes": [
{
"text": {
"content": "안녕하",
"length": 3,
"beginOffset": 0
},
"tag": "VA",
"outOfVocab": "IN_BUILTIN_DICT",
"probability": 0.0
},
{
"text": {
"content": "시",
"beginOffset": 3,
"length": 1
},
"tag": "EP",
"probability": 0.9936437,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": "어요",
"beginOffset": 3,
"length": 2
},
"tag": "EF",
"probability": 0.992555,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": ".",
"beginOffset": 5,
"length": 1
},
"tag": "SF",
"probability": 0.9979541,
"outOfVocab": "IN_WORD_EMBEDDING"
}
],
"lemma": "안녕하",
"tagged": "안녕하/VA+시/EP+어요/EF+./SF"
}
],
"refined": "안녕하세요."
},
{
"text": {
"content": "바른을 사용해서 새로운 경험을 해보세요.",
"beginOffset": 7,
"length": 22
},
"tokens": [
{
"text": {
"content": "바른을",
"beginOffset": 7,
"length": 3
},
"morphemes": [
{
"text": {
"content": "바른",
"beginOffset": 7,
"length": 2
},
"tag": "NNP",
"probability": 0.7029643,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": "을",
"beginOffset": 9,
"length": 1
},
"tag": "JKO",
"probability": 0.9985147,
"outOfVocab": "IN_WORD_EMBEDDING"
}
],
"lemma": "바른",
"tagged": "바른/NNP+을/JKO"
},
{
"text": {
"content": "사용해서",
"beginOffset": 11,
"length": 4
},
"morphemes": [
{
"text": {
"content": "사용하",
"beginOffset": 11,
"length": 3
},
"tag": "VV",
"outOfVocab": "IN_BUILTIN_DICT",
"probability": 0.0
},
{
"text": {
"content": "아서",
"beginOffset": 13,
"length": 2
},
"tag": "EC",
"probability": 0.97633106,
"outOfVocab": "IN_WORD_EMBEDDING"
}
],
"lemma": "사용하",
"tagged": "사용하/VV+아서/EC"
},
{
"text": {
"content": "새로운",
"beginOffset": 16,
"length": 3
},
"morphemes": [
{
"text": {
"content": "새롭",
"beginOffset": 16,
"length": 2
},
"tag": "VA",
"probability": 0.9798353,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": "ㄴ",
"beginOffset": 18,
"length": 1
},
"tag": "ETM",
"probability": 0.99809676,
"outOfVocab": "IN_WORD_EMBEDDING"
}
],
"lemma": "새롭",
"tagged": "새롭/VA+ㄴ/ETM"
},
{
"text": {
"content": "경험을",
"beginOffset": 20,
"length": 3
},
"morphemes": [
{
"text": {
"content": "경험",
"beginOffset": 20,
"length": 2
},
"tag": "NNG",
"probability": 0.97490656,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": "을",
"beginOffset": 22,
"length": 1
},
"tag": "JKO",
"probability": 0.9992314,
"outOfVocab": "IN_WORD_EMBEDDING"
}
],
"lemma": "경험",
"tagged": "경험/NNG+을/JKO"
},
{
"text": {
"content": "해",
"beginOffset": 24,
"length": 1
},
"morphemes": [
{
"text": {
"content": "하",
"beginOffset": 24,
"length": 1
},
"tag": "VV",
"probability": 0.9053459,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": "아",
"beginOffset": 24,
"length": 1
},
"tag": "EC",
"probability": 0.9838363,
"outOfVocab": "IN_WORD_EMBEDDING"
}
],
"lemma": "하",
"tagged": "하/VV+아/EC"
},
{
"text": {
"content": "보세요.",
"beginOffset": 25,
"length": 4
},
"morphemes": [
{
"text": {
"content": "보",
"beginOffset": 25,
"length": 1
},
"tag": "VX",
"probability": 0.90671366,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": "시",
"beginOffset": 26,
"length": 1
},
"tag": "EP",
"probability": 0.9977518,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": "어요",
"beginOffset": 26,
"length": 2
},
"tag": "EF",
"probability": 0.9904806,
"outOfVocab": "IN_WORD_EMBEDDING"
},
{
"text": {
"content": ".",
"beginOffset": 28,
"length": 1
},
"tag": "SF",
"probability": 0.99819946,
"outOfVocab": "IN_WORD_EMBEDDING"
}
],
"lemma": "보",
"tagged": "보/VX+시/EP+어요/EF+./SF"
}
],
"refined": "바른을 사용해서 새로운 경험을 해 보세요."
}
],
"language": "ko_KR"
}
Next Steps
Once you know the basics, continue with the documents that match your goal.
- For result fields and options in detail: Morphological Analysis API, REST API
- For the meaning of the POS tags in the output (
VA,EP,NNP, and so on): POS Tags - To call Bareun from various languages and environments: Development Overview, Using Google Colab
- To improve recognition of domain terms: The Five Custom Dictionaries at a Glance
- If you need spell checking: Bareun Spell Checker, Spell Checking API
- To learn how it works: Analysis Pipeline Overview, Out-of-Vocabulary (OOV) Handling