Kuromoji analyzer
출처: 문서
본문
Kuromoji 분석기
kuromoji 분석기는 IPAdic 사전을 기반으로 하는 Kuromoji 라이브러리를 사용해 일본어 텍스트에 대한 형태소 분석을 제공해요. 일본어 문장을 의미 있는 토큰으로 분절하고, 흔한 불용어와 문법적 조사를 제거하며, 토큰을 사전 기본형으로 반환해요.
kuromoji 분석기나 Kuromoji 컴포넌트를 사용하려면 먼저 analysis-kuromoji 플러그인을 설치해야 해요.
플러그인 설치
모든 노드에 플러그인을 설치한 다음 클러스터를 재시작하세요:
bin/opensearch-plugin install analysis-kuromoji
{% include copy.html %}
플러그인 설치에 대한 자세한 내용은 OpenSearch 플러그인 관리를 참고하세요.
Kuromoji 플러그인 컴포넌트
analysis-kuromoji 플러그인은 다음과 같은 컴포넌트를 제공하며, 이 컴포넌트들을 독립적으로 사용하거나 커스텀 분석기에서 조합할 수 있어요.
분석기
| 분석기 | 설명 |
|---|---|
kuromoji |
내장 일본어 분석기예요. 텍스트를 분절하고, 불용어를 제거하며, 토큰을 기본형으로 정규화해요. |
kuromoji_completion |
일본어 텍스트 자동완성을 위해 설계된 분석기예요. 원본 일본어 토큰과 함께 로마자 읽기 변형을 생성해요. |
토크나이저
| 토크나이저 | 설명 |
|---|---|
kuromoji_tokenizer |
분절 모드를 설정할 수 있는, 사전 기반 일본어 토크나이저예요. |
캐릭터 필터
| 캐릭터 필터 | 설명 |
|---|---|
kuromoji_iteration_mark |
일본어 반복 기호(々, ゝ, ゞ, ヽ, ヾ)를 반복되는 문자로 풀어써서 정규화해요. |
토큰 필터
| 토큰 필터 | 설명 |
|---|---|
kuromoji_baseform |
활용된 토큰을 사전 기본형으로 바꿔요. |
kuromoji_part_of_speech |
품사 태그가 설정된 스톱 태그 목록에 포함된 토큰을 제거해요. |
kuromoji_readingform |
각 토큰을 가타카나 또는 로마자 읽기로 바꿔요. |
kuromoji_stemmer |
가타카나 단어 끝의 장음 기호(ー)를 제거해요. |
ja_stop |
토큰 스트림에서 일본어 불용어를 제거해요. |
kuromoji_number |
일본어 숫자 표현을 표준 아라비아 숫자로 변환해요. |
kuromoji_completion |
자동완성을 지원하기 위해 가타카나 토큰의 로마자 읽기 변형을 생성해요. |
분석 파이프라인
kuromoji 분석기는 입력 텍스트에 다음 컴포넌트를 순서대로 적용해요:
cjk_width캐릭터 필터가 토큰화 전에 전각 ASCII 변형 문자를 표준 ASCII로, 반각 가타카나 변형 문자를 전각 가타카나로 변환해요.search모드의kuromoji_tokenizer가 IPAdic 사전을 사용해 텍스트를 분절하고, 긴 복합어를 하위 토큰으로 나눠요.kuromoji_baseform토큰 필터가 활용된 동사와 형용사 형태를 사전형으로 바꿔요 (예: 食べた → 食べる).kuromoji_part_of_speech토큰 필터가 조사(助詞), 보조 동사(助動詞), 구두점(記号) 등 스톱 태그에 해당하는 토큰을 제거해요.ja_stop토큰 필터가 흔한 일본어 불용어를 제거해요.kuromoji_stemmer토큰 필터가 네 글자 이상의 가타카나 단어에서 끝의 장음 기호(ー)를 제거해요 (예: コンピューター → コンピュータ).lowercase토큰 필터가 라틴 문자를 모두 소문자로 변환해요.
파라미터
다음 표는 kuromoji 분석기의 파라미터를 정리한 거예요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
mode |
String | 토큰화 모드예요. 유효한 값은 normal, search (기본값), extended예요. 자세한 내용은 토큰화 모드를 참고하세요. |
user_dictionary |
String | OpenSearch config 디렉터리에 두는 커스텀 사용자 사전 파일(CSV 형식)의 경로예요. 선택 사항이에요. |
user_dictionary_rules |
Array of strings | CSV 형식의 인라인 커스텀 사전 규칙이에요. 각 항목은 <text>,<subtokens>,<readings>,<part of speech> 형태예요. 선택 사항이고, user_dictionary와 함께 사용할 수는 없어요. |
stopwords |
String or array of strings | 사용할 불용어예요. _japanese_(내장 일본어 스톱 셋), 불용어 배열, 불용어 파일 경로를 지정할 수 있어요. 기본값은 _japanese_예요. |
내장 스톱 셋의 불용어 전체 목록은 Lucene 저장소의 stopwords.txt를 참고하세요.
토큰화 모드
토크나이저 모드는 복합어와 미등록어를 어떻게 분절할지 결정해요.
| 모드 | 효과 |
|---|---|
normal |
표준 사전 기반 분절 방식이에요. 복합어는 하나의 토큰으로 유지되고, 미등록어도 하나의 토큰으로 유지돼요. |
search (기본값) |
normal과 비슷하지만, 복합어(예: 지명)도 하위 구성 요소로 분리해서 검색 쿼리의 재현율을 높여요. |
extended |
normal과 비슷하지만, 미등록어를 유니그램(개별 문자)으로 분리해서 모든 문자가 색인되도록 해요. |
예제: 기본 사용법
다음 예제는 내장 kuromoji 분석기를 사용하는 인덱스를 만들어요:
PUT /japanese-index
{
"mappings": {
"properties": {
"content": {
"type": "text",
"analyzer": "kuromoji"
}
}
}
}
{% include copy-curl.html %}
"도쿄 도서관에서 공부했다"라는 뜻의 일본어 문장으로 분석기를 테스트해 보세요:
POST /_analyze
{
"analyzer": "kuromoji",
"text": "東京の図書館で勉強しました"
}
{% include copy-curl.html %}
분석기는 조사와 보조 동사가 제거된 기본형 토큰을 반환해요:
{
"tokens": [
{
"token": "東京",
"start_offset": 0,
"end_offset": 2,
"type": "word",
"position": 0
},
{
"token": "図書館",
"start_offset": 3,
"end_offset": 6,
"type": "word",
"position": 2
},
{
"token": "勉強",
"start_offset": 7,
"end_offset": 9,
"type": "word",
"position": 4
}
]
}
예제: 커스텀 Kuromoji 분석기
다음 예제는 user_dictionary_rules를 사용해 인라인 커스텀 용어를 등록하는 커스텀 kuromoji 분석기를 만들어요:
PUT /japanese-custom-index
{
"settings": {
"analysis": {
"analyzer": {
"my_kuromoji": {
"type": "kuromoji",
"mode": "search",
"user_dictionary_rules": [
"東京スカイツリー,東京 スカイツリー,トウキョウ スカイツリー,カスタム名詞"
]
}
}
}
},
"mappings": {
"properties": {
"title": {
"type": "text",
"analyzer": "my_kuromoji"
}
}
}
}
{% include copy-curl.html %}
등록한 용어가 포함된 문장("도쿄 스카이트리에 갔다")으로 커스텀 분석기를 테스트해 보세요:
POST /japanese-custom-index/_analyze
{
"analyzer": "my_kuromoji",
"text": "東京スカイツリーに行きました"
}
{% include copy-curl.html %}
분석기는 커스텀 사전 규칙을 사용해 東京スカイツリー를 東京과 スカイツリー로 분절해요. 기본 가타카나 스테머(kuromoji_stemmer)는 スカイツリー에서 끝의 장음 기호를 제거해 スカイツリ를 만들어요. kuromoji_part_of_speech 필터는 조사 に와 보조 동사 まし, た를 제거하고, kuromoji_baseform은 行き를 기본형인 行く로 정규화해요:
{
"tokens": [
{
"token": "東京",
"start_offset": 0,
"end_offset": 2,
"type": "word",
"position": 0
},
{
"token": "スカイツリ",
"start_offset": 2,
"end_offset": 8,
"type": "word",
"position": 1
},
{
"token": "行く",
"start_offset": 9,
"end_offset": 11,
"type": "word",
"position": 3
}
]
}
Kuromoji completion 분석기
kuromoji_completion 분석기는 자동완성 사용 사례를 위해 설계됐어요. 원본 일본어 토큰과 로마자(라틴 문자) 읽기 변형을 모두 생성해서, 사용자가 일본어 문자나 그 로마자 표기 중 어느 쪽으로 입력해도 일본어 콘텐츠를 검색할 수 있어요. query 모드에서는 분석기가 입력기(IME)의 부분 입력을 로마자로 변환하기 전에 하나의 토큰으로 조합해요.
다음 표는 kuromoji_completion 분석기의 파라미터를 정리한 거예요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
mode |
String | 토큰 생성 방식을 결정해요. 유효한 값은 index (기본값)와 query예요. 두 모드 모두 가타카나 토큰을 원래 형태와 모든 로마자 변형으로 확장해요. query 모드는 부분 IME 입력을 처리하기 위한 규칙을 두 가지 더 적용해요. 로마자로 변환하기 전에 연속된 가나 토큰을 하나의 토큰으로 이어 붙이고, 부분 입력된 IME 키 입력을 나타내는 소문자 알파벳 토큰이 뒤에 붙은 가나 토큰을 병합해요 (예: サッ 뒤에 k가 오면 サッk가 돼요). |
user_dictionary |
String | 커스텀 사용자 사전 파일의 경로예요. 선택 사항이에요. |
user_dictionary_rules |
Array of strings | 인라인 커스텀 사전 규칙이에요. 선택 사항이에요. |
검색 분석기에는 query 모드를 사용하세요. 그래야 사용자가 입력한 부분 IME 입력이 로마자 변환 전에 올바르게 조합돼요.
{: .tip}
예제: Kuromoji completion 분석기를 활용한 자동완성
다음 예제는 색인 시점과 검색 시점에 서로 다른 completion 분석기를 사용하도록 인덱스를 설정해요:
PUT /autocomplete-index
{
"settings": {
"analysis": {
"analyzer": {
"kuromoji_index_analyzer": {
"type": "kuromoji_completion",
"mode": "index"
},
"kuromoji_search_analyzer": {
"type": "kuromoji_completion",
"mode": "query"
}
}
}
},
"mappings": {
"properties": {
"suggest": {
"type": "text",
"analyzer": "kuromoji_index_analyzer",
"search_analyzer": "kuromoji_search_analyzer"
}
}
}
}
{% include copy-curl.html %}
completion 토큰 필터에 대한 자세한 내용은 Kuromoji completion 토큰 필터를 참고하세요.
Kuromoji 플러그인과 ICU 플러그인 함께 사용하기
가장 철저한 일본어 텍스트 분석을 위해서는 analysis-kuromoji 플러그인과 analysis-icu 플러그인을 함께 사용하세요. ICU는 전각/반각 문자에 대한 유니코드 정규화와 포괄적인 character folding을 제공하는데, 이런 기능은 Kuromoji 컴포넌트만으로는 얻을 수 없어요.
두 플러그인의 컴포넌트를 모두 사용하는 인덱스를 만들기 전에 analysis-kuromoji와 analysis-icu를 모두 설치해야 해요.
{: .note}
다음 예제는 두 플러그인을 조합한 커스텀 분석기를 만들어요. icu_normalizer 캐릭터 필터는 토큰화 전에 전각 문자를 ASCII 등가 문자로 변환하고 (예: ３００ → 300), 숫자 시퀀스가 하나의 토큰으로 유지되도록 해요. kuromoji_iteration_mark 캐릭터 필터는 일본어 반복 기호를 풀어써서 (예: 時々 → 時時) 토크나이저가 사전에서 정확히 조회할 수 있게 해줘요:
PUT /japanese-icu-index
{
"settings": {
"index": {
"analysis": {
"analyzer": {
"japanese_icu_analyzer": {
"char_filter": [
"icu_normalizer",
"kuromoji_iteration_mark"
],
"tokenizer": "kuromoji_tokenizer",
"filter": [
"kuromoji_baseform",
"kuromoji_part_of_speech",
"ja_stop",
"kuromoji_stemmer",
"lowercase"
]
}
}
}
}
}
}
{% include copy-curl.html %}
전각 숫자와 장음 기호가 포함된 문장("컴퓨터가 문서 300개를 처리한다")으로 조합 분석기를 테스트해 보세요:
POST /japanese-icu-index/_analyze
{
"analyzer": "japanese_icu_analyzer",
"text": "コンピューターは３００件の文書を処理します"
}
{% include copy-curl.html %}
분석기는 다음과 같은 변환을 적용해요:
icu_normalizer가 토큰화 전에 전각 숫자３００을300으로 변환해요.kuromoji_stemmer가 끝의 장음 기호를 제거해서コンピューター를コンピュータ로 바꿔요.kuromoji_part_of_speech가 조사は,の,を와 보조 동사ます를 제거해요.ja_stop이_japanese_스톱 셋에 포함되어 있는し를 제거해요.300은 하나의 토큰으로 유지되고,文書와処理는 기본형으로 반환돼요.
응답은 다음과 같아요:
{
"tokens": [
{
"token": "コンピュータ",
"start_offset": 0,
"end_offset": 7,
"type": "word",
"position": 0
},
{
"token": "300",
"start_offset": 8,
"end_offset": 11,
"type": "word",
"position": 2
},
{
"token": "件",
"start_offset": 11,
"end_offset": 12,
"type": "word",
"position": 3
},
{
"token": "文書",
"start_offset": 13,
"end_offset": 15,
"type": "word",
"position": 5
},
{
"token": "処理",
"start_offset": 16,
"end_offset": 18,
"type": "word",
"position": 7
}
]
}