KiwiJava, 한국어 형태소 분석기 Kiwi의 Java 바인딩

Kiwi v0.16.0에서부터는 자체적으로 Kiwi의 Java 바인딩인 KiwiJava를 제공합니다. KiwiJava는 최신 Release에서 kiwi-java-*.jar라는 이름으로 제공됩니다. jar 파일 내부에 OS에 종속적인 바이너리가 포함되어 있으므로 JVM이 구동되는 가상머신의 환경(win(Windows), lnx(Linux), mac(macOS))에 맞춰서 적합한 jar파일을 받아야 합니다.

KiwiJava는 Java 1.8 이상과 호환됩니다.

시작하기

KiwiJava의 jar 파일은 자체적으로 실행 가능한 main함수를 가지고 있습니다. 따라서 jar 파일과 모델 파일을 받고 다음과 같이 jar 파일을 구동하여 KiwiJava가 정상적으로 작동하는지 확인할 수 있습니다.

# Linux x86-64 환경을 가정

# 모델 파일 다운로드
$ wget https://github.com/bab2min/Kiwi/releases/download/v0.19.0/kiwi_model_v0.19.0_base.tgz
$ tar -zxvf kiwi_model_v0.19.0_base.tgz # 압축 해제. 모델을 포함한 models/base라는 폴더가 생성됨

# KiwiJava 다운로드
$ wget https://github.com/bab2min/Kiwi/releases/download/v0.19.0/kiwi-java-v0.19.0-lnx-x86-64.jar

# 모델 파일은 Patch가 다르더라도 Major, Minor 버전이 동일하면 호환됩니다.
# 즉, kiwi_model_v0.19.0은 kiwi-java-v0.19.* 전부에서 사용가능합니다.

# jar 구동. 구동 인자로 모델 경로를 입력해주어야 함
$ java -jar kiwi-java-v0.19.0-lnx-x86-64.jar models/base/
Kiwi 0.19.0 is loaded!
>> 안녕하세요?
[Token(form=안녕, tag=NNG, position=0, length=2),
 Token(form=하, tag=XSA, position=2, length=1),
 Token(form=세요, tag=EF, position=3, length=2),
 Token(form=?, tag=SF, position=5, length=1)]

Java API

import java.util.Arrays;

import kr.pe.bab2min.Kiwi;
import kr.pe.bab2min.KiwiBuilder;

public class KiwiExample {
  public static void main(String[] args) throws Exception {
    // Kiwi 인스턴스 생성 방법 (1)
    Kiwi kiwi = Kiwi.init("path_to_kiwi_model");

    /*
    // Kiwi 인스턴스 생성 방법 (2)
    try(KiwiBuilder builder = new KiwiBuilder("path_to_kiwi_model")) {
      // 기본 옵션으로 Kiwi 인스턴스 생성
      kiwi = builder.build();
        
      // 오타 교정 기능을 사용하여 Kiwi 인스턴스 생성
      kiwi = builder.build(KiwiBuilder.basicTypoSet, 2.0f);
    }
    */

    // 형태소 분석
    // Kiwi.Match에 대한 자세한 설명은
    // https://github.com/bab2min/Kiwi/blob/c849ee06f788ca07b6c924f3497bcce89e9dfa9a/include/kiwi/PatternMatcher.h
    // 를 참고하세요.
    Kiwi.Token[] tokens = kiwi.tokenize("분석할 텍스트", Kiwi.Match.allWithNormalizing);
    System.out.println(Arrays.deepToString(tokens));
    /* Output:
       [Token(form=분석, tag=NNG, position=0, length=2), 
        Token(form=하, tag=XSV, position=2, length=1), 
        Token(form=ᆯ, tag=ETM, position=2, length=1), 
        Token(form=텍스트, tag=NNG, position=4, length=3)]*/

    // 문장 분할
    Kiwi.Sentence[] sents = kiwi.splitIntoSents("텍스트를 문장별로 분할합니다. 잘 분할됩니까?", Kiwi.Match.allWithNormalizing);
    System.out.println(Arrays.deepToString(sents));
    /* Output:
       [Sentence(text=텍스트를 문장별로 분할합니다., start=0, end=16, subSents=[]), 
        Sentence(text=잘 분할됩니까?, start=17, end=25, subSents=[])]*/

    // 형태소 결합
    Kiwi.JoinableToken[] joinableTokens = new Kiwi.JoinableToken[]{
      new Kiwi.JoinableToken("키위", Kiwi.POSTag.nnp),
      new Kiwi.JoinableToken("을", Kiwi.POSTag.jko),
      new Kiwi.JoinableToken("사용", Kiwi.POSTag.nng),
      new Kiwi.JoinableToken("하", Kiwi.POSTag.xsv),
      new Kiwi.JoinableToken("었", Kiwi.POSTag.ep),
      new Kiwi.JoinableToken("다", Kiwi.POSTag.ef),
    };
    String joined = kiwi.join(joinableTokens);
    System.out.println(joined);
    /* Output:
       키위를 사용했다*/
  }
}

자세한 예시는 src/kr/pe/bab2min/ 내의 Kiwi.java, KiwiBuilder.java 및 test/ 내의 KiwiTest.java 파일을 참조해주세요.

Android에서 사용하기

1. AAR 파일 사용

GitHub Releases에서 kiwi-android-VERSION.aar 파일을 다운로드하고 프로젝트에 추가:

다운로드한 AAR 파일을 app/libs/ 폴더에 복사
app/build.gradle에 다음 추가:

android {
    ...
}

dependencies {
    implementation files('libs/kiwi-android-VERSION.aar')
    ...
}

2. 소스에서 빌드

이 디렉토리에서 직접 빌드할 수도 있습니다:

cd bindings/java
./gradlew assembleRelease

빌드된 AAR 파일은 build/outputs/aar/ 디렉토리에 생성됩니다.

사용 방법

package example

import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity

import kr.pe.bab2min.Kiwi
import kr.pe.bab2min.KiwiBuilder

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        try {
            // 모델 파일을 assets 내의 kiwi_model/ 폴더에 넣었다고 가정
            val streamProvider = KiwiBuilder.StreamProvider { filename ->
                try {
                    // assets 내의 kiwi_model/ 폴더 내의 파일을 연다.
                    assets.open("kiwi_model/$filename")
                } catch (e: Exception) {
                    null // 파일이 없으면 null 반환
                }
            }

            val kiwi = KiwiBuilder(streamProvider).build()
            val res = kiwi.tokenize("안드로이드에서도 Kiwi를!", Kiwi.Match.allWithNormalizing)
            for (token in res) {
                Log.d("Kiwi", "${token.form} / ${Kiwi.POSTag.toString(token.tag)}")
            }
            /* 다음과 같이 출력됨
            안드로이드 / NNG
            에서 / JKB
            도 / JX
            Kiwi / SL
            를 / JKO
            ! / SF
            */
        } catch (e: Exception) {
            Log.e("Kiwi", "Error", e)
        }
    }
}

요구사항

Android API Level 21+ (Android 5.0)
ARM64-v8a 아키텍처
Java 8+

모델 파일

모델 파일은 별도로 다운로드해야 합니다:

GitHub Releases에서 kiwi_model_VERSION_base.tgz 다운로드
압축 해제 후 Android 앱의 assets 폴더에 복사
런타임에 내부 저장소로 복사한 뒤 파일 경로로 접근하거나 KiwiBuilder.StreamProvider를 사용하여 assets에서 직접 읽도록 설정

6.5 KiB Raw Permalink Blame History