콘텐츠로 이동

Elasticsearch 플러그인

Elasticsearch 에 바른 형태소 분석기 꽂기

Elasticsearch 의 분석기(analyzer)로 바른을 직접 씁니다. 색인할 때와 검색할 때 같은 분석기가 돌기 때문에, 응용 프로그램에서 미리 토큰을 만들어 넣는 방식보다 운영이 단순합니다.

지원 버전

Elasticsearch 는 플러그인의 elasticsearch.version 이 노드 버전과 정확히 같아야 로드합니다. 그래서 대상 버전마다 파일이 따로 나옵니다.

Elasticsearch 파일
8.19.21 elasticsearch-analysis-bareun-1.0.0-es8.19.21.zip
9.5.2 elasticsearch-analysis-bareun-1.0.0-es9.5.2.zip

다른 버전이 필요하면 저장소를 받아 mvn -Delasticsearch.version=9.4.6 package 로 직접 빌드합니다. 8.19 는 JDK 17, 9.x 는 JDK 21 이 필요합니다.

노드 버전과 정확히 맞춰야 합니다

9.5.1 노드에 9.5.2 용 파일을 설치하면 노드가 뜨지 않습니다. 버전을 올릴 때는 플러그인도 함께 바꿔야 합니다.

설치

Releases 에서 노드 버전에 맞는 파일을 받아 설치합니다. 모든 노드에 설치해야 합니다.

bin/elasticsearch-plugin install file:///path/to/elasticsearch-analysis-bareun-1.0.0-es8.19.21.zip

설정

노드 단위 기본값은 elasticsearch.yml 에, API 키는 keystore 에 넣습니다.

# elasticsearch.yml
bareun.host: nlp.bareun.ai
bareun.port: 5656
bareun.tls: false
bareun.timeout: 10s
bareun.stoptags: [E, IC, J, MAG, MAJ, MM, NA, NF, NV, SE, SF, SO, SP, SS, SW, VC, VX, XPN, XS]

bin/elasticsearch-keystore add bareun.api_key

설정을 바꾸면 노드를 다시 시작합니다.

API 키는 인덱스 설정에 넣을 수 없습니다

인덱스 설정은 클러스터 상태에 평문으로 저장됩니다. 키는 keystore 만 받습니다.

쓰기

가장 간단한 형태입니다.

PUT /my-index
{
  "settings": {
    "analysis": {
      "analyzer": {
        "korean": { "type": "bareun" }
      }
    }
  }
}

POST /my-index/_analyze
{ "analyzer": "korean", "text": "아버지가 방에 들어가신다." }

아버지/NNG  방/NNG  들어가/VV  들어가신다./VV

필드에 붙입니다.

PUT /my-index/_mapping
{
  "properties": {
    "content": { "type": "text", "analyzer": "korean" }
  }
}

등록되는 이름

종류 이름 옛 이름
analyzer bareun baikal_analyzer
tokenizer bareun_tokenizer baikal_tokenizer
token filter bareun_part_of_speech baikal_token

옛 이름도 그대로 동작합니다. 이미 만들어진 인덱스가 깨지지 않게 한동안 함께 둡니다. 새 인덱스에는 bareun_* 를 쓰세요.

옵션

analyzer 설정에서 노드 기본값을 덮어쓸 수 있습니다.

PUT /my-index
{
  "settings": {
    "analysis": {
      "tokenizer": {
        "my_bareun": {
          "type": "bareun_tokenizer",
          "decompound_mode": "mixed",
          "stoptags": ["E", "J", "SF"],
          "custom_dict_names": ["mydict"]
        }
      },
      "analyzer": {
        "korean": { "type": "custom", "tokenizer": "my_bareun" }
      }
    }
  }
}
옵션 뜻 기본값
decompound_mode none·discard·mixed mixed
stoptags 색인에서 뺄 품사 태그 접두사 노드 설정
custom_dict_names 쓸 사용자 사전 이름들 노드 설정
host·port·tls·timeout 서버 접속 노드 설정

decompound_mode

"아버지가 방에 들어가신다." 를 넣었을 때의 차이입니다.

모드 결과
mixed(기본) 아버지 방 들어가 들어가신다.
discard 아버지 방 들어가
none 아버지가 방에 들어가신다.

mixed 는 용언 어절을 원형과 같은 자리(position)에 함께 넣습니다. 들어가다 로 찾는 사용자와 들어가신다 로 찾는 사용자를 모두 맞추기 위해서입니다.

stoptags

접두사로 비교합니다. J 하나로 모든 조사(JKS·JKB·JX 등)가 빠집니다. 품사 태그는 품사 태그표 를 보세요.

품사 필터

색인용과 검색용 analyzer 에서 다른 품사를 거르고 싶을 때 씁니다.

"filter": {
  "my_pos": { "type": "bareun_part_of_speech", "stoptags": ["J", "E"] }
},
"analyzer": {
  "korean": { "type": "custom", "tokenizer": "bareun_tokenizer", "filter": ["my_pos"] }
}

사용자 사전

바른 서버의 사용자 사전 을 그대로 씁니다. 사전을 고쳐도 Elasticsearch 노드를 다시 시작할 필요가 없습니다. nori 와 다른 점입니다.

nori 와 견주면

nori 바른 플러그인
분석 위치 노드 안에서 바른 서버에 요청
사전 갱신 노드 재시작 필요 서버에서 즉시 반영
신조어·고유명사 사용자 사전을 직접 관리 바른 모델 + 사용자 사전
띄어쓰기 보정 없음 서버가 처리
외부 의존 없음 바른 서버가 떠 있어야 함

바른 플러그인은 분석마다 서버를 호출합니다. 서버가 멎으면 색인과 검색이 함께 실패하므로, 서버를 이중화하거나 앞에 로드밸런서를 두는 편이 안전합니다.

도커에서

examples/docker/ 에 플러그인을 미리 설치한 이미지를 만드는 예시가 있습니다. 설정은 환경변수로 주고, 키는 컨테이너를 띄운 뒤 keystore 에 넣습니다.

docker run -d --name es \
  -e discovery.type=single-node \
  -e bareun.host=nlp.bareun.ai -e bareun.port=5656 \
  -p 9200:9200 elasticsearch-bareun:8.19.21

docker exec -i es bash -c 'echo "koba-..." | bin/elasticsearch-keystore add -x -f bareun.api_key'
docker restart es

자주 묻는 질문

Q. 노드가 뜨지 않습니다. A. 플러그인 파일의 대상 버전과 노드 버전이 정확히 같은지 확인하세요. 다르면 Elasticsearch 가 플러그인을 거부합니다.

Q. 분석 결과가 비어 있거나 오류가 납니다. A. 바른 서버에 닿는지, API 키가 keystore 에 들어 있는지 확인하세요. 설정을 바꾼 뒤에는 노드를 다시 시작해야 반영됩니다.

Q. 옛 baikal_analyzer 로 만든 인덱스가 있는데 그대로 둬도 되나요? A. 됩니다. 옛 이름을 별칭으로 남겨 두었습니다. 새 인덱스부터 bareun 을 쓰세요.

Q. Elasticsearch 7.x 에서도 되나요? A. 지원하지 않습니다. 8.19 와 9.x 를 대상으로 합니다.

도움이 되었나요?