mecab-ko-dict

한국어 형태소 분석을 위한 사전 관리 라이브러리

주요 기능

• SystemDictionary: Trie + Matrix + Features를 통합한 시스템 사전
• UserDictionary: 사용자 정의 단어 추가 지원
• Double-Array Trie: 빠른 형태소 검색
• 연접 비용 행렬: 형태소 간 연결 비용 계산
• 메모리 맵 지원: 효율적인 메모리 사용 (NEW)
• 지연 로딩: 첫 접근 시에만 사전 로드 (NEW)
• 압축 지원: zstd 압축 자동 해제 (NEW)

설치

[dependencies]
mecab-ko-dict = "0.1.0"

사용 예제

시스템 사전 로드

use mecab_ko_dict::{MmapDictionary, Dictionary};

// 기본 로드 (mmap 활성화)
let dict = MmapDictionary::load("./dict")?;

// 형태소 검색
let entries = dict.lookup("안녕");
for entry in entries {
    println!("{}: {}", entry.surface, entry.feature);
}

// 연접 비용 조회
let cost = dict.get_connection_cost(left_id, right_id);

고급 로딩 옵션

use mecab_ko_dict::loader::{DictionaryLoader, LoaderConfig};

// 설정 커스터마이징
let dict = DictionaryLoader::new("./dict")
    .use_mmap(true)          // 메모리 맵 사용
    .auto_decompress(true)    // 자동 압축 해제
    .lazy_load(false)         // 즉시 로드
    .load()?;

// 지연 로딩
let lazy_dict = DictionaryLoader::new("./dict")
    .lazy_load(true)
    .load()?;

사용자 사전

use mecab_ko_dict::UserDictionaryBuilder;

// 빌더 패턴으로 생성
let user_dict = UserDictionaryBuilder::new()
    .default_cost(-1000)
    .add("딥러닝", "NNG")
    .add_with_cost("머신러닝", "NNG", -800)
    .add_full("챗GPT", "NNP", -1000, Some("챗지피티"))
    .build_with_trie()?;

// 검색
let entries = user_dict.lookup("딥러닝");

CSV 파일에서 로드

use mecab_ko_dict::UserDictionaryBuilder;

let user_dict = UserDictionaryBuilder::new()
    .load_csv("user_dict.csv")?
    .build_with_trie()?;

CSV 포맷:

# 사용자 사전
표면형,품사,비용,읽기
딥러닝,NNG,-1000,딥러닝
챗GPT,NNP,-1000,챗지피티

시스템 사전 + 사용자 사전

use mecab_ko_dict::{DictionaryLoader, UserDictionaryBuilder};

// 시스템 사전 로드
let mut system_dict = DictionaryLoader::load_default()?;

// 사용자 사전 추가
let user_dict = UserDictionaryBuilder::new()
    .add("딥러닝", "NNG")
    .build();

system_dict.set_user_dictionary(user_dict);

// 통합 검색
let entries = system_dict.lookup_combined("딥러닝");

사전 구조

파일 구조

mecab-ko-dic/
├── sys.dic          # Trie 데이터
├── matrix.bin       # 연접 비용 행렬 (바이너리)
└── matrix.def       # 연접 비용 행렬 (텍스트)

환경 변수

• MECAB_DICDIR: 사전 디렉토리 경로

기본 경로:

• /usr/local/lib/mecab/dic/mecab-ko-dic
• /usr/lib/mecab/dic/mecab-ko-dic
• /opt/mecab/dic/mecab-ko-dic
• ./dic/mecab-ko-dic

API 문서

Dictionary Trait

pub trait Dictionary {
    fn lookup(&self, surface: &str) -> Vec<Entry>;
    fn get_connection_cost(&self, left_id: u16, right_id: u16) -> i16;
}

SystemDictionary

pub struct SystemDictionary { /* ... */ }

impl SystemDictionary {
    pub fn load_default() -> Result<Self>;
    pub fn load<P: AsRef<Path>>(dicdir: P) -> Result<Self>;
    pub fn with_user_dictionary(self, user_dict: UserDictionary) -> Self;
    pub fn lookup_combined(&self, surface: &str) -> Vec<Entry>;
    pub fn common_prefix_search(&self, text: &str) -> Vec<(&DictEntry, usize)>;
}

UserDictionary

pub struct UserDictionary { /* ... */ }

impl UserDictionary {
    pub fn new() -> Self;
    pub fn add_entry(&mut self, surface: &str, pos: &str, cost: Option<i16>, reading: Option<String>) -> &mut Self;
    pub fn load_from_csv<P: AsRef<Path>>(&mut self, path: P) -> Result<&mut Self>;
    pub fn lookup(&self, surface: &str) -> Vec<&UserEntry>;
    pub fn build_trie(&mut self) -> Result<&[u8]>;
}

성능

• Trie 검색: O(m) (m = 검색 키 길이)
• 연접 비용 조회: O(1)
• 메모리 사용: 사전 크기에 비례 (mmap 사용 시 효율적)

테스트

# 단위 테스트
cargo test -p mecab-ko-dict

# 통합 테스트
cargo test -p mecab-ko-dict --test integration_test

# 예제 실행
cargo run -p mecab-ko-dict --example dictionary_usage

라이선스

MIT OR Apache-2.0

기여

이슈와 풀 리퀘스트는 언제나 환영합니다!