Lindera

Rust製の形態素解析ライブラリです。Linderaは kuromoji-rs からフォークされ、複数言語のテキストトークナイズに対して、簡単なインストールと簡潔なAPIの提供を目指しています。

主な機能

トークナイズの流れ

graph LR
    subgraph Your Application
        T["Text"]
    end
    subgraph Lindera
        CF["Character Filters"]
        SEG["Segmenter\n(Dictionary + Viterbi)"]
        TF["Token Filters"]
    end
    T --> CF --> SEG --> TF --> R["Tokens"]

ドキュメントマップ

パフォーマンス

Linderaは日本語テキスト（IPADIC）を、シングルスレッドで概ね10〜20 MB/sの速度でトークナイズします（速度はハードウェアや、Viterbiラティスを呼び出しをまたいで再利用するかどうかに依存します）。ベンチマークスイート（lindera/benches/）を自分のマシンで再現するにはmake benchを実行してください。詳細な計測方法と比較データは#875を参照してください。

クイック例

use lindera::dictionary::load_dictionary;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera_analysis::tokenizer::Tokenizer;
use lindera::LinderaResult;

fn main() -> LinderaResult<()> {
    let dictionary = load_dictionary("embedded://ipadic")?;
    let segmenter = Segmenter::new(Mode::Normal, dictionary, None);
    let tokenizer = Tokenizer::new(segmenter);

    let text = "関西国際空港限定トートバッグ";
    let mut tokens = tokenizer.tokenize(text)?;
    println!("text:\t{}", text);
    for token in tokens.iter_mut() {
        let details = token.details().join(",");
        println!("token:\t{}\t{}", token.surface.as_ref(), details);
    }

    Ok(())
}

上記の例は以下のように実行できます：

cargo run -p lindera-analysis --features=embed-ipadic --example=tokenize

実行結果は以下のようになります：

text:   関西国際空港限定トートバッグ
token:  関西国際空港    名詞,固有名詞,組織,*,*,*,関西国際空港,カンサイコクサイクウコウ,カンサイコクサイクーコー
token:  限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
token:  トートバッグ    名詞,一般,*,*,*,*,*,*,*

ライセンス

Linderaは MITライセンス の下で公開されています。

アーキテクチャ

Linderaは複数のクレートで構成されるCargo workspaceとして構成されています。各クレートは、低レベルのCRF計算から高レベルのCLIや言語バインディングまで、それぞれ明確な責務を持っています。

クレート依存関係図

graph TB
    CRF["lindera-crf\n(CRF Engine)"]
    DICT["lindera-dictionary\n(Dictionary Base)"]
    TRAINER["lindera-trainer\n(CRF Training)"]
    IPADIC["lindera-ipadic"]
    UNIDIC["lindera-unidic"]
    SUDACHIDICT["lindera-sudachidict"]
    KODIC["lindera-ko-dic"]
    CCCEDICT["lindera-cc-cedict"]
    JIEBA["lindera-jieba"]
    NEOLOGD["lindera-ipadic-neologd"]
    LIB["lindera\n(Segmenter)"]
    ANALYSIS["lindera-analysis\n(Analysis Chain)"]
    CLI["lindera-cli\n(CLI)"]
    BINDINGCORE["lindera-binding-core"]
    PY["lindera-python"]
    NODEJS["lindera-nodejs"]
    RUBY["lindera-ruby"]
    PHP["lindera-php"]
    WASM["lindera-wasm"]

    CRF --> TRAINER
    DICT --> TRAINER
    TRAINER -.->|"train feature"| LIB
    DICT --> IPADIC
    DICT --> UNIDIC
    DICT --> SUDACHIDICT
    DICT --> KODIC
    DICT --> CCCEDICT
    DICT --> JIEBA
    DICT --> NEOLOGD
    DICT --> LIB
    DICT --> ANALYSIS
    DICT --> WASM
    IPADIC --> LIB
    UNIDIC --> LIB
    SUDACHIDICT --> LIB
    KODIC --> LIB
    CCCEDICT --> LIB
    JIEBA --> LIB
    NEOLOGD --> LIB
    LIB --> ANALYSIS
    LIB --> CLI
    ANALYSIS --> CLI
    LIB --> BINDINGCORE
    ANALYSIS --> BINDINGCORE
    BINDINGCORE --> PY
    BINDINGCORE --> NODEJS
    BINDINGCORE --> RUBY
    BINDINGCORE --> PHP
    BINDINGCORE --> WASM

クレート一覧

トークナイズパイプライン

Linderaは複数段階のパイプラインでテキストを処理します：

Input Text
  |
  v
Character Filters    -- Normalize characters (e.g., Unicode normalization, mapping)
  |
  v
Segmenter            -- Segment text into tokens using a dictionary and the Viterbi algorithm
  |
  v
Token Filters        -- Transform tokens (e.g., POS filtering, stop words, stemming)
  |
  v
Output Tokens

Segmenterがコアコンポーネントです。辞書から候補トークンのラティスを構築し、Viterbiアルゴリズムを適用して最小コストのパスを見つけ、最も適切な分割結果を生成します。辞書検索は、所有権を持つ構造体へのデシリアライズを行わず、dict.trieのシリアライズ済みバイト列上を直接走査する文字単位のダブル配列トライ（crawdadでビルド）を使用します。繰り返しトークナイズを行う場合は、Segmenter::new_worker()が返すSegmentWorkerがラティスとスクラッチバッファの割り当てを呼び出しをまたいで再利用し、保持メモリを自動収縮ポリシーで制限します。

Featureフラグ

詳細

• はじめに -- インストールと最初のステップ
• 基本概念 -- 辞書、トークナイズ、フィルター
• Linderaライブラリ -- セグメンター、API
• Lindera Analysis -- 文字フィルタ、トークンフィルタ、Tokenizer
• Lindera Dictionary -- 辞書の読み込みとビルド
• Lindera Trainer -- CRFベースの辞書学習
• Lindera CRF -- CRFエンジン
• Lindera CLI -- コマンドラインインターフェース
• 開発ガイド -- ビルド、テスト、コントリビュート

はじめに

このセクションでは、Linderaのインストールから最初の形態素解析の実行までをガイドします。

• インストール -- プロジェクトへのLinderaの追加と環境変数の設定
• クイックスタート -- わずか数行のコードで最初のテキストをトークナイズ
• サンプル -- 一般的なユースケースのサンプルプログラムを探索

インストール

動作要件

Rust 1.88 以降。ワークスペースが rust-version として宣言しているため、 古いツールチェインではコンパイルエラーではなく cargo のエラーとして報告されます。

依存関係の追加

Cargo.tomlに以下を追加してください：

[dependencies]
lindera = "5"

[!NOTE] v4 からアップグレードする場合はv4からv5への移行を参照してください。

辞書のセットアップ

Linderaの実行にはビルド済み辞書が必要です。GitHub Releases から辞書をダウンロードし、読み込み時にそのパスを指定してください：

#![allow(unused)]
fn main() {
let dictionary = load_dictionary("/path/to/ipadic")?;
}

[!TIP] 辞書をバイナリに直接埋め込みたい場合（上級者向け）は、対応する embed-* feature フラグを有効にしてビルドし、embedded:// スキームでロードしてください：

#![allow(unused)]
fn main() {
// Cargo.toml: lindera = { version = "5", features = ["embed-ipadic"] }
let dictionary = load_dictionary("embedded://ipadic")?;
}

詳細は Feature フラグ を参照してください。

環境変数

LINDERA_BUILD_DICTIONARY_CACHE_DIR

LINDERA_BUILD_DICTIONARY_CACHE_DIR 環境変数は、埋め込み辞書ビルドパイプラインのビルド時キャッシュディレクトリを指定します。辞書クレートの build script のみが読み取り、実行時の動作には影響しません。

設定すると、各ビルドは $LINDERA_BUILD_DICTIONARY_CACHE_DIR/<version>-fmt<format>/（<version> は辞書クレートのバージョン、<format> は辞書フォーマットバージョン）配下に 2 種類のファイルを保存します：

• ダウンロードした配布アーカイブ（MD5 で検証。無効なファイルは自動的に再ダウンロード）
• クレートに埋め込まれるビルド済みバイナリ辞書

フォーマットバージョンをパスに含めているのは、オンディスクレイアウトが異なるビルドが書いたキャッシュを「古いまま再利用」ではなく「キャッシュミス」にするためです。再利用の直前にはキャッシュディレクトリ内の記録済みフォーマットバージョンも再確認するので、中断されたビルドが残した不完全なディレクトリも弾かれます。古いフォーマットバージョンのディレクトリは自動削除されないため、キャッシュが肥大化する場合は手動で削除してください。

これにより以下のメリットがあります：

• オフラインビルド: 一度キャッシュされれば、以降のビルドにネットワークアクセスは不要です
• ビルドの高速化: 有効なキャッシュがあればダウンロードと辞書ビルドがスキップされます
• 再現可能なビルド: ビルド間での辞書バージョンの一貫性を保ちます

使用方法：

export LINDERA_BUILD_DICTIONARY_CACHE_DIR=/path/to/cache
cargo build --features=embed-ipadic

注意点：

• このディレクトリは自動管理されており、削除しても安全です（必要に応じて再ダウンロード・再ビルドされます）
• バージョンごとのサブディレクトリはアップグレードのたびに蓄積され、自動削除されません。古いものは自由に削除できます
• この変数を設定すると、embed-* feature が無効でも辞書クレートはダウンロードとビルドを実行します（キャッシュの事前準備に便利です）

非推奨: 旧名 LINDERA_DICTIONARIES_PATH はフォールバックとして引き続き動作しますが（両方設定時は新名が優先）、v6.0.0 で削除されます。

LINDERA_CONFIG_PATH

LINDERA_CONFIG_PATH 環境変数は、トークナイザーの設定ファイル（YAML形式）へのパスを指定します。これにより、Rustコードを変更せずにトークナイザーの動作を設定できます。

export LINDERA_CONFIG_PATH=./resources/config/lindera.yml

設定フォーマットの詳細は 設定 セクションを参照してください。

DOCS_RS

DOCS_RS 環境変数は、docs.rsでドキュメントをビルドする際に自動的に設定されます。この変数が検出されると、Linderaは実際の辞書データをダウンロードする代わりにダミーの辞書ファイルを作成します。これにより、ネットワークアクセスや大容量ファイルのダウンロードなしでドキュメントをビルドできます。

これは主にdocs.rs内部で使用されるものであり、通常ユーザーが設定する必要はありません。

LINDERA_WORKDIR

LINDERA_WORKDIR 環境変数は、ビルドプロセス中に lindera-dictionary クレートによって自動的に設定されます。これはビルドされた辞書データファイルを含むディレクトリを指し、辞書クレートがデータファイルの場所を特定するために内部で使用されます。

この変数は自動的に設定されるため、ユーザーが変更する必要はありません。

クイックスタート

この例では、Linderaの基本的な使い方を説明します。

以下の処理を行います：

• Normalモードでセグメンターを作成
• 入力テキストを分割（形態素解析）
• トークンを出力

この例では embed-ipadic feature を使用します。この feature はビルド時にIPADIC辞書を自動的にダウンロードしてバイナリに埋め込むため、辞書を手動でダウンロードする必要はありません。

use std::borrow::Cow;

use lindera::dictionary::load_dictionary;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera::LinderaResult;

fn main() -> LinderaResult<()> {
    let dictionary = load_dictionary("embedded://ipadic")?;
    let segmenter = Segmenter::new(Mode::Normal, dictionary, None);

    let text = "関西国際空港限定トートバッグ";
    let mut tokens = segmenter.segment(Cow::Borrowed(text))?;
    println!("text:\t{}", text);
    for token in tokens.iter_mut() {
        let details = token.details().join(",");
        println!("token:\t{}\t{}", token.surface.as_ref(), details);
    }

    Ok(())
}

上記の例は以下のように実行できます：

% cargo run --features embed-ipadic --example=segment

[!TIP] 辞書をバイナリに埋め込みたくない場合は、GitHub Releases からビルド済みIPADIC辞書をダウンロードしてローカルディレクトリ（例: /path/to/ipadic）に展開し、代わりに load_dictionary("/path/to/ipadic") を呼び出してください。この場合、embed-ipadic feature は不要です。詳細は Feature フラグ を参照してください。

実行結果は以下のようになります：

text:   関西国際空港限定トートバッグ
token:  関西国際空港    名詞,固有名詞,組織,*,*,*,関西国際空港,カンサイコクサイクウコウ,カンサイコクサイクーコー
token:  限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
token:  トートバッグ    名詞,一般,*,*,*,*,*,*,*

[!NOTE] character filter・token filter・Tokenizer API は独立クレート lindera-analysis が提供します（v5.0 以降）。分析チェーンが必要な場合は 依存定義に lindera-analysis = "5" を追加してください。

サンプル

Linderaには、一般的なユースケースを示すいくつかのサンプルプログラムが含まれています。ソースコードはGitHubの examplesディレクトリ で確認できます。

以下のサンプルはすべて embed-ipadic feature を有効にして実行します。この feature はビルド時にIPADIC辞書を自動的にダウンロードしてバイナリに埋め込むため、辞書を手動でダウンロードする必要はありません。

利用可能なサンプル

segment

Segmenter API による基本的な形態素分割です。lindera クレート単体で動作します。

cargo run -p lindera --features=embed-ipadic --example=segment

tokenize

外部IPADIC辞書を使用した基本的なトークナイズです。入力テキストを分割し、各トークンの品詞情報を表示します。

cargo run -p lindera-analysis --features=embed-ipadic --example=tokenize

tokenize_with_user_dict

ユーザー辞書を使用したトークナイズです。ドメイン固有の用語のために、辞書をカスタムエントリで補完する方法を示します。

cargo run -p lindera-analysis --features=embed-ipadic --example=tokenize_with_user_dict

tokenize_with_filters

キャラクターフィルターとトークンフィルターを使用したトークナイズです。Unicode正規化、品詞フィルタリングなどの変換を含むテキスト処理パイプラインを実演します。

cargo run -p lindera-analysis --features=embed-ipadic --example=tokenize_with_filters

tokenize_with_config

YAML設定ファイルを使用したトークナイズです。プログラムではなく宣言的にトークナイザーを設定する方法を示します。

cargo run -p lindera-analysis --features=embed-ipadic --example=tokenize_with_config

基本概念

このセクションでは、Linderaの形態素解析システムの基本的な概念について説明します。

• 形態素解析 - Linderaがテキストを分割・解析する仕組み。
• 辞書 - Linderaがサポートする辞書フォーマット。
• トークナイズ - トークナイズモードとN-Best解析。
• ユーザー辞書 - ユーザー辞書によるカスタム単語の追加。
• フィルタ - 文字フィルタによるテキスト前処理とトークンフィルタによるトークン後処理。

形態素解析

形態素解析とは

形態素解析とは、テキストを最小の意味単位（形態素）に分割し、その文法的特性を同定する処理です。日本語、中国語、韓国語のように単語がスペースで区切られない言語では、形態素解析は検索インデックス作成、テキスト分類、機械翻訳などの自然言語処理タスクにおいて不可欠な最初のステップです。

Linderaの仕組み

Linderaは辞書ベースの形態素解析器です。既知の単語とそのコストを含む事前コンパイル済みのシステム辞書を使用し、Viterbiアルゴリズムを適用して入力テキストの最適な分割を見つけます。

解析処理は以下のように動作します：

1. 文分割: ラティスを構築する前に、Linderaは入力テキストを区切り文字（\n、\t、。、、）で文単位に分割し、1文ずつ処理します。文の先頭からおよそ 32 KiB 以内に区切り文字が見つからない場合、Linderaはその位置で強制的に文の境界を区切り、警告をログに出力します。これはラティスのメモリ・CPU コストを制限するためです。区切り文字を含まない病的な入力（minify されたテキストや base64 エンコードされたデータなど）に対しては、この人為的な分割位置でトークナイズ結果に影響が出ることがあります。
2. ラティス構築: Linderaは各文をスキャンし、各位置で辞書内のすべての候補単語を検索して、候補分割の有向非巡回グラフ（ラティス）を構築します。
3. コスト割り当て: 各候補単語には（辞書からの）単語コストが関連付けられており、隣接する単語のペアには（連接コスト行列からの）連接コストが関連付けられています。
4. 最適パス探索: Viterbiアルゴリズムがラティスを通る最小総コストのパスを見つけ、最適な分割結果を生成します。

主な用語

コストベースの分割

Viterbiアルゴリズムは総コストが最小となる分割パスを選択します。パスの総コストは以下の合計です：

• 単語コスト: 辞書内の各単語に関連付けられたコスト。コストが低いほど、その単語が出現する可能性が高いことを意味します。一般的な単語はコストが低く、まれな単語はコストが高い傾向があります。
• 連接コスト: 隣接する2つの単語を接続するコスト。左側の単語の右文脈IDと右側の単語の左文脈IDによって決定されます。

アルゴリズムは以下を計算します：

Total cost = sum of word costs + sum of connection costs

この総コストを最小化することで、Linderaは入力テキストの最も自然な分割を見つけます。

連接コスト行列

連接コスト行列は、ある単語から別の単語への遷移コストを格納します。以下でインデックスされる2次元行列です：

• 先行する単語の右文脈ID
• 後続する単語の左文脈ID

これらの文脈IDは、単語境界に関する文法的情報をエンコードしています。例えば、名詞と助詞の間の連接コストは通常低く（自然な並び）、2つの動詞の基本形の間の連接コストは高くなります（不自然な並び）。

連接コスト行列は辞書ビルドプロセスの一部としてバイナリ形式にコンパイルされ、実行時に効率的な参照のために読み込まれます。

辞書

Linderaは、日本語・韓国語・中国語の形態素解析のための様々な辞書をサポートしています。各辞書は個別のクレートとして提供されます。

辞書の入手方法

ビルド済み辞書は GitHub Releases からダウンロードできます。対象言語の辞書アーカイブをダウンロードし、ローカルディレクトリに展開してください。

#![allow(unused)]
fn main() {
// ローカルパスから外部辞書を読み込む
let dictionary = load_dictionary("/path/to/ipadic")?;
}

[!TIP] 外部辞書ファイルなしの自己完結型バイナリが必要な場合は、embed-* feature フラグを使って辞書を埋め込み、embedded:// スキームでロードできます：

#![allow(unused)]
fn main() {
let dictionary = load_dictionary("embedded://ipadic")?;
}

詳細は Feature フラグ を参照してください。

各辞書クレートのドキュメントで、フォーマット詳細、ビルド手順、使用例を参照してください。

トークナイズ

Linderaは複数のトークナイズモードを提供し、代替の分割候補を列挙するためのN-Best解析をサポートしています。

トークナイズモード

Normalモード

Normalモードは辞書エントリに基づく標準的なトークナイズを実行します。辞書に単一エントリとして存在する複合語はそのまま保持されます。

例 -- "関西国際空港限定トートバッグ" をNormalモードでトークナイズ：

関西国際空港 | 限定 | トートバッグ

複合名詞 "関西国際空港"（Kansai International Airport）は辞書に1つのエントリとして存在するため、単一トークンとして保持されます。

Decomposeモード

Decomposeモードは、複合語が辞書エントリとして存在する場合でも、さらに構成要素に分解します。

例 -- "関西国際空港限定トートバッグ" をDecomposeモードでトークナイズ：

関西 | 国際 | 空港 | 限定 | トートバッグ

複合語 "関西国際空港" は "関西"、"国際"、"空港" に分解されます。

モードの選択

Rustでは、Segmenterの作成時にモードを指定します：

#![allow(unused)]
fn main() {
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera::dictionary::load_dictionary;

let dictionary = load_dictionary("embedded://ipadic")?;

// Normal mode
let segmenter = Segmenter::new(Mode::Normal, dictionary, None);

// Decompose mode
let segmenter = Segmenter::new(Mode::Decompose(Default::default()), dictionary, None);
}

CLIでは、--modeフラグを使用します：

echo "関西国際空港限定トートバッグ" | lindera tokenize --dict embedded://ipadic --mode normal
echo "関西国際空港限定トートバッグ" | lindera tokenize --dict embedded://ipadic --mode decompose

[!NOTE] embedded:// スキームを使用するには、lindera-cli を対応する embed-* feature 付きでビルドする必要があります（例: cargo install lindera-cli --features=embed-ipadic）。デフォルトビルドの lindera-cli はどの embed-* feature も有効化していないため、 embed-* feature なしで --dict embedded://ipadic を指定すると Invalid dictionary scheme: embedded エラーになります。

N-Bestトークナイズ

N-Bestトークナイズは、総パスコスト順（低コスト = より良い分割）に上位N件のトークナイズ候補を列挙します。最良の結果が曖昧な場合や、入力テキストの代替解釈を探索したい場合に有用です。

アルゴリズム

N-Bestトークナイズは**Forward-DP Backward-A***アルゴリズムに基づいており、MeCabのN-Best実装と互換性があります。フォワードパスは動的計画法で最適コストを計算し、バックワードパスはA*探索を使用して総コストの昇順にパスを列挙します。

パラメータ

tokenize_nbestメソッドは以下のパラメータを受け付けます：

Rust APIの例

use lindera::dictionary::load_dictionary;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera_analysis::tokenizer::Tokenizer;
use lindera::LinderaResult;

fn main() -> LinderaResult<()> {
    let dictionary = load_dictionary("embedded://ipadic")?;
    let segmenter = Segmenter::new(Mode::Normal, dictionary, None);
    let tokenizer = Tokenizer::new(segmenter);

    let text = "すもももももももものうち";

    // Get top 3 tokenization results
    let results = tokenizer.tokenize_nbest(text, 3, false, None)?;

    for (rank, (tokens, cost)) in results.iter().enumerate() {
        println!("--- NBEST {} (cost={}) ---", rank + 1, cost);
        for token in tokens {
            let details = token.details().join(",");
            println!("{}\t{}", token.surface.as_ref(), details);
        }
    }

    Ok(())
}

実行結果は以下のようになります：

--- NBEST 1 (cost=21245) ---
すもも  名詞,一般,*,*,*,*,すもも,スモモ,スモモ
も      助詞,係助詞,*,*,*,*,も,モ,モ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
も      助詞,係助詞,*,*,*,*,も,モ,モ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
うち    名詞,非自立,副詞可能,*,*,*,うち,ウチ,ウチ
--- NBEST 2 (cost=24541) ---
...

CLIの例

echo "すもももももももものうち" | lindera tokenize --dict embedded://ipadic -N 3

Latticeの再利用

繰り返しトークナイズを行う場合、Latticeを再利用してメモリ割り当てを削減できます：

#![allow(unused)]
fn main() {
use lindera_dictionary::viterbi::Lattice;

let mut lattice = Lattice::default();
let results = tokenizer.tokenize_nbest_with_lattice(text, &mut lattice, 3, false, None)?;
}

セグメンターのレベルでは、SegmentWorker（Segmenter::new_worker で作成）がこのパターンをラティスとスクラッチバッファを所有するセッションオブジェクトとしてまとめており、さらに自動縮小ポリシーで保持メモリも制限します。詳細は Segmenter のページを参照してください。

ユーザー辞書

ユーザー辞書は、システム辞書と併用してカスタム単語を登録できる補助辞書です。ドメイン固有の用語、ブランド名、固有名詞、またはデフォルトのシステム辞書に含まれていない単語を登録する場合に有用です。

CSVフォーマット

最もシンプルなユーザー辞書フォーマットは、3つのカラムを持つCSVファイルです：

<surface>,<part_of_speech>,<reading>

CSV内容の例

東京スカイツリー,カスタム名詞,トウキョウスカイツリー
東武スカイツリーライン,カスタム名詞,トウブスカイツリーライン
とうきょうスカイツリー駅,カスタム名詞,トウキョウスカイツリーエキ

各辞書タイプ（IPADIC、UniDic、ko-dicなど）は、文脈ID、コスト、すべての素性フィールドを完全に制御できる詳細CSVフォーマットもサポートしています。各辞書タイプの詳細フォーマットについては 辞書 セクションを参照してください。

Rust APIの例

use std::fs::File;
use std::path::PathBuf;

use lindera::dictionary::{Metadata, load_dictionary, load_user_dictionary};
use lindera::error::LinderaErrorKind;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera_analysis::tokenizer::Tokenizer;
use lindera::LinderaResult;

fn main() -> LinderaResult<()> {
    let user_dict_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("../resources")
        .join("user_dict")
        .join("ipadic_simple_userdic.csv");

    let metadata_file = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("../lindera-ipadic")
        .join("metadata.json");
    let metadata: Metadata = serde_json::from_reader(
        File::open(metadata_file)
            .map_err(|err| LinderaErrorKind::Io.with_error(anyhow::anyhow!(err)))
            .unwrap(),
    )
    .map_err(|err| LinderaErrorKind::Io.with_error(anyhow::anyhow!(err)))
    .unwrap();

    let dictionary = load_dictionary("embedded://ipadic")?;
    let user_dictionary = load_user_dictionary(user_dict_path.to_str().unwrap(), &metadata)?;
    let segmenter = Segmenter::new(
        Mode::Normal,
        dictionary,
        Some(user_dictionary), // Using the loaded user dictionary
    );

    // Create a tokenizer.
    let tokenizer = Tokenizer::new(segmenter);

    // Tokenize a text.
    let text = "東京スカイツリーの最寄り駅はとうきょうスカイツリー駅です";
    let mut tokens = tokenizer.tokenize(text)?;

    // Print the text and tokens.
    println!("text:\t{}", text);
    for token in tokens.iter_mut() {
        let details = token.details().join(",");
        println!("token:\t{}\t{}", token.surface.as_ref(), details);
    }

    Ok(())
}

実行結果は以下のようになります：

text:   東京スカイツリーの最寄り駅はとうきょうスカイツリー駅です
token:  東京スカイツリー        カスタム名詞,*,*,*,*,*,*,トウキョウスカイツリー,*
token:  の      助詞,連体化,*,*,*,*,の,ノ,ノ
token:  最寄り駅        名詞,一般,*,*,*,*,最寄り駅,モヨリエキ,モヨリエキ
token:  は      助詞,係助詞,*,*,*,*,は,ハ,ワ
token:  とうきょうスカイツリー駅        カスタム名詞,*,*,*,*,*,*,トウキョウスカイツリーエキ,*
token:  です    助動詞,*,*,*,特殊・デス,基本形,です,デス,デス

base_formフィールド（CSV/詳細情報の7番目のフィールド）が表層形ではなく*になっている点に注意してください。 シンプルな3カラムのユーザー辞書スキーマでは surface、part_of_speech、reading の3つしか指定できず、 base_form を含むそれ以外のフィールドはすべて辞書の metadata.default_field_value （IPADICの場合は*）で埋められます。

CLIでのユーザー辞書ビルド

CLIを使用して、CSVからバイナリ形式のユーザー辞書をビルドできます：

lindera build --src <source_dir> --dest <dest_dir> --metadata <metadata.json> --user

バイナリとCSVのユーザー辞書

• CSVフォーマット: 実行時に読み込み・パースされます。開発時や小規模な辞書に便利です。
• バイナリフォーマット: 高速な読み込みのために事前コンパイルされます。大規模なユーザー辞書を本番環境で使用する場合に推奨されます。

どちらのフォーマットもSegmenterの作成時に指定できます。バイナリフォーマットはCSVのパースステップをスキップするため、起動時間が短縮されます。

フィルタ

Linderaの解析パイプライン（lindera-analysisクレートが提供するTokenizer）には、Segmenterの前後に2つの拡張ポイントがあります。トークナイズ前の生テキストを変換する文字フィルタと、トークナイズ後のトークン列を変換するトークンフィルタです。

Input Text
  --> Character Filters (preprocessing)
  --> Tokenization
  --> Token Filters (postprocessing)
  --> Output Tokens

文字フィルタ

文字フィルタは、入力テキストがSegmenterに渡される前に前処理を行います。全角文字を半角に変換する、Unicode表現を正準化する、日本語の踊り字を展開形に変換するなど、トークナイズの一貫性を高めるためのテキスト正規化に主に使われます。文字フィルタはテキストの長さを変えることがあるため、Linderaはすべての変換を記録し、各トークンのバイトオフセットを元の（フィルタ適用前の）テキストにおける位置へ補正します。

トークンフィルタ

トークンフィルタは、Segmenterが生成したトークン列に対して後処理を行います。トークンを基本形（辞書形）に置き換える、トークンの表層形をひらがな・カタカナ間で変換する、品詞タグでトークンを除去する、ストップワードを除去するなど、検索や解析のためにトークン列を正規化・削減する目的で主に使われます。

フィルタの設定方法

文字フィルタ・トークンフィルタのいずれも、kind文字列で識別され、フィルタ固有のパラメータを持つJSONのargsオブジェクトで設定します。フィルタは追加された順序で実行され、追加方法は2通りあります。

• YAML設定ファイル: character_filtersキーとtoken_filtersキーの下にフィルタを列挙する。

  character_filters:
    - kind: unicode_normalize
      args:
        kind: nfkc
  
  token_filters:
    - kind: japanese_base_form
  

• Rust API: append_character_filterとappend_token_filterでTokenizerに順番にフィルタを追加する。

  #![allow(unused)]
  fn main() {
  // Character filters run first, transforming the raw input text;
  // token filters run last, transforming the resulting token list.
  tokenizer
      .append_character_filter(BoxCharacterFilter::from(unicode_normalize_char_filter))
      .append_token_filter(BoxTokenFilter::from(japanese_base_form_filter));
  }

利用可能なフィルタ

Linderaは4種類の文字フィルタと18種類のトークンフィルタを提供しており、日本語・韓国語・汎用的なテキスト正規化をカバーしています。

各フィルタの説明・パラメータ・実行可能なYAML/Rust APIの例はフィルターリファレンスを参照してください。

Lindera CRF

Lindera CRFは、rucrfからフォークされたConditional Random Fields（CRF）のpure Rust実装です。ラティス構造をサポートしたCRFの学習器と推定器を提供します。

主な特徴

• 可変長エッジを持つラティス構造
• L1、L2、およびElastic Net正則化
• マルチスレッド学習
• rkyvによるゼロコピーデシリアライゼーション
• --no-default-features --features allocによるno_stdサポート

目次

• アーキテクチャ -- 内部構造と主要コンポーネント
• APIリファレンス -- APIドキュメント

rucrfからの変更点

• シリアライゼーションバックエンド: ゼロコピーデシリアライゼーションのため、bincodeからrkyvに変更
• Elastic Net正則化: L1とL2のペナルティを組み合わせたRegularization::ElasticNetを追加
• Rust 2024 edition: Rust 2024 editionに更新
• 依存クレートの更新: argmin、argmin-math、hashbrownなどを更新

アーキテクチャ

モジュール構成

lindera-crf/src/
├── lib.rs                # パブリックAPIの再エクスポート
├── feature.rs            # FeatureSet, FeatureProvider
├── lattice.rs            # Edge, Node, Lattice
├── model.rs              # RawModel, MergedModel, Model trait
├── trainer.rs            # Trainer, Regularization enum
├── errors.rs             # エラー型
├── forward_backward.rs   # 前向き・後向きアルゴリズム
├── math.rs               # 数学ユーティリティ (logsumexp)
├── optimizers.rs         # optimizersモジュールの宣言
├── optimizers/
│   └── lbfgs.rs          # L-BFGS最適化
└── utils.rs              # ユーティリティtrait

主要コンポーネント

FeatureProvider / FeatureSet

ラベルごとの素性セットを管理します。各FeatureSetは、指定されたラベルのユニグラム素性と左右のバイグラム素性を保持します（保持するのは素性IDのみで、重みは持ちません）。FeatureProviderはラベルIDをFeatureSetインスタンスにマッピングします。重みはRawModel側で別途保持されます（weights、unigram_weight_indices、bigram_weight_indices）。

Lattice / Edge / Node

系列ラベリングのための可変長エッジを持つラティス構造です。Edgeはラベル付きの候補スパンを表し、Nodeは特定の位置にあるエッジを集約します。Latticeは入力データから構築され、モデルが最適パスを探索するために使用されます。

Trainer

設定可能な正則化を用いたL-BFGS最適化によりCRFモデルを学習します。Trainerはラベル付きラティスの例を受け取り、前向き・後向きアルゴリズムで勾配を計算し、反復的にモデルの重みを更新します。

Regularization

設定可能な正則化戦略：

• L1: L1ペナルティによるスパースモデル
• L2: L2ペナルティによる滑らかなモデル
• ElasticNet: L1とL2を設定可能なl1_ratioで組み合わせ

Model (trait)

ラティスを通じて最適パスを探索するためのインターフェースです。2つの実装が提供されています：

• RawModel: 素性IDでインデックスされたフラットベクトルに重みを格納
• MergedModel: 推論に最適化され、素性の重みをrkyvでシリアライズ可能なコンパクトな表現にマージ。ラベルごとの要素型としてMergedFeatureSetを使用

MergedFeatureSetは、ラベルの事前合計済みユニグラムweightと、MergedModelのバイグラム重み行列を参照するleft_id/right_id接続IDを保持します。

前向き・後向きアルゴリズム

ラティス上でアルファ（前向き）とベータ（後向き）の値を計算します。学習時に期待素性カウントと勾配の計算に使用されます。

Feature フラグ

* defaultに直接列挙されているわけではありませんが、デフォルトで有効なtrainがstdを有効化し、stdがさらにallocを有効化するため、実際にはデフォルトビルドでalloc／stdは有効になっています。

APIリファレンス

APIリファレンスは以下で公開されています：

• lindera-crf

Lindera Dictionary

Lindera Dictionaryは、形態素解析辞書のベースライブラリです。辞書の読み込み、ビルド、Viterbiベースのセグメンテーションを提供します。CRFベースの辞書学習機能は、別クレートのlindera-trainerが提供します。

主な特徴

• ファイルシステムまたは埋め込みデータからの辞書読み込み
• MeCab形式のCSVソースファイルからの辞書ビルド
• 最適なセグメンテーションのためのViterbiアルゴリズム
• N-bestパス生成（Forward-DP Backward-A*）
• メモリマップドファイルサポート

目次

• アーキテクチャ -- 内部構造と主要コンポーネント
• APIリファレンス -- APIドキュメント

アーキテクチャ

モジュール構成

lindera-dictionary/src/
├── lib.rs               # パブリックAPI
├── dictionary.rs        # Dictionary, UserDictionary
├── builder.rs           # DictionaryBuilder
├── loader.rs            # DictionaryLoader trait, FSDictionaryLoader
├── viterbi.rs           # Lattice, Edge, Viterbiセグメンテーション
├── nbest.rs             # NBestGenerator (Forward-DP Backward-A*)
├── mode.rs              # Mode (Normal/Decompose), Penalty
├── error.rs             # LinderaError, LinderaErrorKind
├── assets.rs            # ダウンロードとファイル管理
├── macros.rs            # 辞書クレート共通の embedded_dictionary! マクロ
├── dictionary/
│   ├── character_definition.rs    # 文字種定義
│   ├── connection_cost_matrix.rs  # 連接コスト行列
│   ├── context_id_map.rs          # ContextIdMap（連接コストのコンテキストID再割り当て）
│   ├── prefix_dictionary.rs       # 前方一致辞書（crawdad トライをバイト列上で直接走査）
│   ├── unknown_dictionary.rs      # 未知語処理
│   ├── metadata.rs                # 辞書メタデータ
│   └── schema.rs                  # スキーマ定義

主要コンポーネント

Dictionary / UserDictionary

コンパイル済み辞書データを保持する主要データ構造です。Dictionaryは文字種定義、連接コスト行列、前方一致辞書（文字単位のダブル配列トライ）、および未知語辞書を含みます。システム辞書のトライはビルド時にcrawdadで構築され、実行時はdict.trieのシリアライズ済みバイト列上を直接走査します（デシリアライズなしのゼロコピー。ロードは O(1) のヘッダ検査のみ）。UserDictionaryを使用すると、システム辞書の上にカスタム語彙を追加できます。ユーザー辞書の前方一致検索は従来どおり rkyv アーカイブ内のdaachorseオートマトンを使用します。

DictionaryBuilder

ソースCSVファイルから辞書をビルドするためのFluent APIです。MeCab形式の辞書ソースを、実行時に使用されるバイナリ形式にコンパイルします。4つのビルドステージ（メタデータ、未知語辞書、前方一致辞書、連接コスト行列）は、wasm以外のターゲットではスコープ付きスレッド上で並行実行され、OSスレッドを持たないwasmでは逐次ビルドにフォールバックします。並行実行パスでは4ステージすべての作業データを同時に保持するため、ピークメモリ使用量が大きくなります。

DictionaryLoader / FSDictionaryLoader

DictionaryLoaderはコンパイル済み辞書を読み込むためのtraitです。FSDictionaryLoaderはファイルシステムベースの実装で、ディレクトリから辞書ファイルを読み込みます。オプションでメモリマップドファイルをサポートします。

埋め込み辞書マクロ

embedded_dictionary!マクロ（lindera-dictionary/src/macros.rs、#[macro_export]）は、各辞書クレートがコンパイル済み辞書をバイナリに埋め込むために必要なボイラープレートを生成します。具体的には、include_bytes!経由で辞書コンポーネントを読み込むload()関数と、DictionaryLoaderを実装するローダー構造体です。各辞書クレート（lindera-ipadic、lindera-ipadic-neologd、lindera-unidic、lindera-ko-dic、lindera-cc-cedict、lindera-jieba）のembedded.rsは、読み込みロジックを重複実装する代わりにこのマクロを呼び出します。

Viterbi (Lattice, Edge)

入力テキストから候補トークンのラティスを構築し、Viterbiアルゴリズムを使用して最適なセグメンテーションパスを探索します。ラティス内の各Edgeは、関連するコスト（単語コスト + 連接コスト）を持つ候補トークンを表します。

NBestGenerator

Forward-DP Backward-A*アルゴリズムを使用してN-bestセグメンテーションパスを生成します。これにより、アプリケーションは単一の最適パスを超えた代替セグメンテーションを検討できます。

Mode

トークナイゼーションの動作を制御します：

• Normal: 最適なViterbiパスを使用した標準的なトークナイゼーション
• Decompose: 設定可能なPenalty閾値に基づいて複合名詞をさらに分割

辞書フォーマットバージョン

ビルド済み辞書ディレクトリは、自身が書かれたオンディスクレイアウトを metadata.json の format_version として記録します。値は DictionaryBuilder::build_metadata が DICTIONARY_FORMAT_VERSION（lindera-dictionary/src/dictionary/metadata.rs）から刻印します。いま何を書いたのかを正しく主張できるのはビルダだけなので、ソース metadata.json 側の値は無視されます。辞書ディレクトリのロード時には記録されたバージョンを検証し、一致しなければ対処方法を含むエラーを返します。

この検証が重要なのは、ほとんどの成果物が自前のヘッダを持たないためです。matrix.mtx・dict.vals・dict.words は生の配列なので、古いレイアウトの辞書でも長さが辻褄の合う範囲ならエラーにならず異常な値として解釈されます。各辞書クレートに手書きでチェックインされているソース metadata.json はビルドの入力を記述するもので、format_version を持たず、フォーマット検証の対象にもなりません。

ビルド済み成果物のバイト列が変わる変更では必ず DICTIONARY_FORMAT_VERSION を上げてください。シリアライズ形式をそのまま書き出している依存クレートの更新（dict.trie の crawdad、char_def.bin / unk.bin の rkyv、ユーザー辞書 .bin 内の daachorse）も対象で、本クレートのコードが 1 行も変わらないため見落としやすい箇所です。ビルドキャッシュがフォーマットバージョンをキーに含めているのは、まさにこのためです。

現在のフォーマットバージョンは 2 です。バージョン 2 では、システム前方一致辞書のバイト単位 daachorse Aho-Corasick オートマトン（dict.da）が、文字単位のダブル配列トライ（dict.trie）と u32 の累積和インデックス（dict.valsidx）に置き換えられました。バージョン 1 以前の辞書はロード時に対処方法を含むエラーで拒否されます。ユーザー辞書の .bin はこの変更の影響を受けませんが、daachorse によって書き出されているため daachorse の更新では無効化されます。上記のリストに daachorse が含まれているのはそのためです。

コンテキストIDリマッピング

辞書メタデータ（lindera-dictionary/src/dictionary/metadata.rs）は、connection_id_mapping: boolフラグとオプションのcontext_id_map: Option<ContextIdMap>を持ちます。辞書クレート（例: lindera-unidic）がconnection_id_mappingを有効にすると、DictionaryBuilderはビルド時にアクセス頻度に基づいて連接行列の左右コンテキストIDを再割り当てし、頻繁に使用される連接コストのセルが近くに集まるようにしてキャッシュ局所性を高めます。DictionaryBuilder::with_context_id_freqは、IDのランク付けに使用するバンドル済み頻度ヒストグラムを（任意で）アタッチするためのメソッドで、再割り当て自体はlindera-dictionary/src/builder/context_id_remap.rsで計算されます。ContextIdMap（lindera-dictionary/src/dictionary/context_id_map.rs）は結果として得られるleft/rightの置換を保持し、同じマッピングを後から再適用できるようにビルド済みのmetadata.jsonに永続化されます。ユーザー辞書は常に元の（再割り当てされていない）ID空間でコンパイルされるため、UserDictionary::remap_context_ids（lindera-dictionary/src/dictionary.rs）は永続化されたContextIdMapを使って、ユーザー辞書のコンテキストIDを、それが紐付くシステム辞書と同じ空間に再割り当てします。この再割り当ては全単射（bijective）な付け替えであるため、トークナイゼーションの出力は変わらず、ルックアップの局所性のみが変化します。

学習

CRFベースの辞書学習パイプラインは、本クレートのランタイム型の上に構築された独立クレート lindera-trainer に含まれます。詳細は学習パイプラインのドキュメントを参照してください。

Featureフラグ

APIリファレンス

APIリファレンスは以下で公開されています：

• lindera-dictionary

Lindera Trainer

Lindera Trainerは、CRFベースの辞書学習パイプライン（lindera train）を実装するクレートです。アノテーション付きコーパスと種辞書から学習済みモデルを生成し、そのモデルをMeCab形式の辞書ソースファイルにエクスポートしてバイナリ辞書としてビルドできるようにします。内部ではlindera-dictionaryのランタイム型とlindera-crfのCRFコアを利用しています。このクレートは直接利用することも、linderaファサードのtrain feature経由（lindera::dictionary::trainerとして再エクスポート）で利用することもできます。

主な特徴

• lindera-crfによるCRFベースの重み学習（L1、L2、Elastic Net正則化に対応）
• MeCab互換の素性テンプレート解析（feature.def: %F[n]、%L[n]、%R[n]、%w、%u、%l、%r、およびそれぞれの?付きオプション形式）
• MeCab互換の3セクション形式による素性書き換え（rewrite.def: ユニグラム／左文脈／右文脈の書き換えルール）
• 辞書形式に依存しない設計: surface,left_id,right_id,cost,feature...の列構成に従う辞書であれば任意のもの（IPADIC、UniDic、ko-dic、CC-CEDICTなど）を扱える
• char.defの文字カテゴリに基づく未知語の自動カテゴリ分類
• 学習されたCRFの重みから連接コスト行列を生成し、MeCab互換のコスト変換（tocost）を適用
• ゼロコピーのrkyvバイナリ形式によるモデルのシリアライズ（読み込み時はレガシーJSON形式へのフォールバックにも対応）
• Lindera／MeCab辞書ソースファイル（lex.csv、matrix.def、unk.def、char.def、feature.def、rewrite.def、left-id.def、right-id.def）の直接エクスポート

目次

• アーキテクチャ -- 内部構造と主要コンポーネント
• APIリファレンス -- APIドキュメント

アーキテクチャ

モジュール構成

lindera-trainer/src/
├── lib.rs                # Trainer: CRF学習の実行制御。パブリックAPIの再エクスポート
├── config.rs             # TrainerConfig: 種辞書・char.def・feature.def・rewrite.defのパース
├── corpus.rs              # Corpus, Example, Word: 学習データの表現
├── feature_extractor.rs  # FeatureExtractor: 素性テンプレート解析と素性ID管理
├── feature_rewriter.rs   # DictionaryRewriter: MeCab互換の3セクション書き換え
└── model.rs               # Model, SerializableModel: 学習済みモデルの保持・シリアライズ・辞書出力

主要コンポーネント

TrainerConfig

学習に必要な5つの入力ファイル――種辞書（lex.csv）、文字定義（char.def）、未知語定義（unk.def）、素性テンプレート（feature.def）、書き換えルール（rewrite.def）――をパースし、Trainerが利用する設定情報にまとめます。TrainerConfig::from_readers（またはファイルパスを直接渡せるラッパーのfrom_paths）は、種辞書から表層形と素性の語彙を抽出し、パースした素性テンプレートからFeatureExtractorを構築し、書き換えルールからDictionaryRewriterを構築し、さらにchar.defから実際にパースした文字定義をもとに最小限のインメモリlindera_dictionary::dictionary::Dictionaryを組み立てます。注意: このDictionaryのprefix_dictionary（システム辞書）フィールドとunknown_dictionaryフィールドは、空のスタブとして構築されるだけです――学習時に実際に使われる種辞書の語彙や未知語カテゴリの素性は、このDictionaryオブジェクトではなく、TrainerConfig自身のsurfaces / features / unk_categories / unk_costsフィールドに別途保持されています。また、surfaces()、surface_features()、get_features()に加え、user_lexicon() / add_user_lexicon_entry() / load_user_lexicon_from_content()によるユーザー辞書へのアクセス、metadata()も提供します。

Corpus / Example / Word

アノテーション付き学習データを表現します。Wordは表層形とその素性文字列（カンマ区切り）のペアです。Exampleは1つの学習用の文であり、Vec<Word>から構築され、各語の表層形を連結して元の文を復元します。CorpusはExampleの集合です。Corpus::from_readerはタブ区切りのsurface<TAB>features形式の行をパースし、空行またはEOSのみの行を文の区切りとして扱います。

FeatureExtractor

MeCab互換の素性テンプレートを解析し、生成された素性文字列から内部で採番されるNonZeroU32型の素性IDへのマッピングを管理します。サポートされるテンプレートのプレースホルダは、%F[n] / %F?[n]（インデックスnの素性フィールド。?付きは値が*の場合にスキップ）、%t（文字カテゴリ）、%w（表層形、ユニグラムのみ）、%u / %l / %r（書き換え後のユニグラム／左文脈／右文脈の素性文字列全体）、およびバイグラムの左右文脈フィールド用の%L[n] / %L?[n] / %R[n] / %R?[n]です。extract_unigram_feature_ids[_with_ctx]、extract_left_feature_ids[_with_ctx]、extract_right_feature_ids[_with_ctx]は、パース済みテンプレートを素性の配列（バイグラム抽出の場合は表層形／ufeature／lfeature／rfeatureを保持するオプションのTemplateContextも併せて）に適用し、対応する素性IDを返します。初回利用時には新しいIDが割り当てられます。

DictionaryRewriter

MeCabの3セクション形式rewrite.def（[unigram rewrite]、[left rewrite]、[right rewrite]）を実装します。各セクションはpattern<TAB>replacement形式のルールの並びを持ち、内部のFeatureRewriterBuilderによってFeatureRewriterというprefix trie（前方一致木）に構築されます。DictionaryRewriter::from_readerは3セクションすべてをパースしますが、セクションヘッダのないファイルは後方互換性のため（右文脈書き換えのみのレガシー形式として）扱います。rewrite()は素性文字列に3つの書き換え器すべてを適用し、(ufeature, lfeature, rfeature)を返します。マッチするルールがないセクションは入力をそのまま通過させます。（かつてのrewrite_cached()は素性文字列全体をキーにメモ化していましたが、実辞書の素性は行ごとにほぼ一意でキャッシュが一度もヒットしないため削除されました — #975。）

Model / SerializableModel

ModelはTrainer::trainが生成する学習済みモデルです。学習されたlindera_crf::RawModel、学習に用いたTrainerConfig、抽出済みの素性の重みとラベル、そして学習後にread_user_lexiconで追加されたユーザー辞書エントリを保持します。学習されたCRFの重みは、MeCab互換の整数コストに変換されます（tocost(weight, cost_factor) = clamp(round(-weight * cost_factor), i16::MIN, i16::MAX)、すなわち[-32768, 32767]の範囲にクランプされます）。この際のコストファクターは、i16の値域を最大限活用できるよう計算されます（calculate_cost_factor）。Modelは自身をシリアライズでき（write_model）、辞書ソースファイルを直接エクスポートすることもできます。

SerializableModelは、Model::read_modelがリーダーから以前学習したモデルを読み込んだ際に返される、rkyvでシリアライズ可能な素のデータ型です（lindera export CLIコマンドで使用されます）。Modelと同じ学習結果の情報――素性の重み、ラベル、品詞情報、連接コスト行列、未知語カテゴリ、保存されているchar.def / feature.def / rewrite.defの内容、コストファクター、左右文脈IDマッピング――をTrainerConfigを持たない所有データとして保持し、辞書エクスポートファイルを生成するための独自のライターメソッド群を提供します。

Modelのパブリックメソッド

SerializableModelのパブリックメソッド

Model::read_modelが返す値に対して利用できるメソッド群で、以前に学習・シリアライズされたモデルから辞書ソースファイルを再エクスポートするために使用します（lindera export CLIコマンドで利用されます）。

ModelMetadataとFeatureSetInfo

ModelMetadataは学習実行に関する要約情報を保持します: version、regularization（使用した正則化コスト係数）、iterations（設定された最大イテレーション数）、feature_count、label_countです。SerializableModel::metadataに格納されます。

FeatureSetInfoは、学習後にマージされたCRFモデルから抽出された、ラベルごとの連接情報を保持します: left_id、right_id、weightです。SerializableModel::feature_setsには、labelsと同じ順序で各ラベルに対応する1エントリが格納されます。

APIリファレンス

APIリファレンスは以下で公開されています：

• lindera-trainer

Lindera ライブラリ

lindera クレートは純粋な形態素セグメンターです。辞書クレートを統合し、Segmenter API を提供します。デフォルトでは lindera-analysis・lindera-crf・lindera-trainer に依存しません。このセクションでは、セグメンテーション、エラーハンドリング、APIリファレンスについて説明します。

Tokenizer や文字フィルタ・トークンフィルタ（Segmenter の上に構築されたLucene風の分析チェーン）が必要な場合は、別クレートのLindera Analysis（設定・フィルタページを含む）を参照してください。

• Segmenter - Viterbi アルゴリズムを使用するコアセグメンテーションコンポーネント
• エラーハンドリング - エラー型とハンドリングパターン
• APIリファレンス - 生成されたAPIドキュメントへのリンク

Segmenter

Segmenter は形態素解析を実行するコアコンポーネントです。辞書とコストモデルに基づいて、入力テキストの最適な分割を Viterbi アルゴリズムで探索します。

Segmenter の作成

Segmenter には以下の3つのコンポーネントが必要です：

• Mode - トークナイズ戦略（Normal または Decompose）
• Dictionary - 形態素解析用のシステム辞書
• UserDictionary（オプション） - カスタム単語用の補助辞書

#![allow(unused)]
fn main() {
use lindera::dictionary::load_dictionary;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;

let dictionary = load_dictionary("embedded://ipadic")?;
let segmenter = Segmenter::new(Mode::Normal, dictionary, None);
}

トークナイズモード

Mode::Normal

辞書に登録されたエントリに基づく標準的なトークナイズです。辞書に登録された単語に忠実に分割します。

#![allow(unused)]
fn main() {
use lindera::mode::Mode;

let mode = Mode::Normal;
}

Mode::Decompose

複合名詞を構成要素に分解します。このモードでは、長い複合語にペナルティを適用し、Segmenter がより短い構成要素に分割するよう促します。

例えば、「関西国際空港限定トートバッグ」という文中の複合語「関西国際空港」は、Mode::Normal では1つのトークンの一部のままですが、Mode::Decompose では「関西」「国際」「空港」に分割されます（分割されるかどうかは前後の文脈にも依存し、同じ文字列単独では同じ結果にならない場合があります）。

#![allow(unused)]
fn main() {
use lindera::mode::Mode;

let mode = Mode::Decompose(Default::default());
}

辞書の読み込み

Lindera は様々なソースから辞書を読み込むための load_dictionary 関数を提供しています。

埋め込み辞書

適切な Feature フラグ（例: embed-ipadic）を指定してビルドすると、バイナリから直接辞書を読み込むことができます：

#![allow(unused)]
fn main() {
use lindera::dictionary::load_dictionary;

let dictionary = load_dictionary("embedded://ipadic")?;
}

利用可能な埋め込み辞書URI：

• embedded://ipadic - IPADIC（日本語）
• embedded://ipadic-neologd - IPADIC NEologd（日本語）
• embedded://unidic - UniDic（日本語）
• embedded://ko-dic - ko-dic（韓国語）
• embedded://cc-cedict - CC-CEDICT（中国語）
• embedded://jieba - Jieba（中国語）

外部辞書

ビルド済みの辞書ディレクトリをファイルシステムから読み込むことができます：

#![allow(unused)]
fn main() {
use lindera::dictionary::load_dictionary;

let dictionary = load_dictionary("/path/to/dictionary")?;
}

Tokenizer との連携

Segmenter は通常、Character Filter と Token Filter のサポートを追加する Tokenizer を通じて使用されます：

use lindera::dictionary::load_dictionary;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera_analysis::tokenizer::Tokenizer;
use lindera::LinderaResult;

fn main() -> LinderaResult<()> {
    let dictionary = load_dictionary("embedded://ipadic")?;
    let segmenter = Segmenter::new(Mode::Normal, dictionary, None);
    let tokenizer = Tokenizer::new(segmenter);

    let text = "日本語の形態素解析を行うことができます。";
    let tokens = tokenizer.tokenize(text)?;

    for mut token in tokens {
        let details = token.details().join(",");
        println!("{}\t{}", token.surface.as_ref(), details);
    }

    Ok(())
}

token を mut で束縛している点に注意してください。Token::details は &mut self を取るため、単純な for token in tokens ではコンパイルエラー（E0596: 可変として借用できません）になります。

Config からの構築

Segmenter::from_config は、Tokenizer/TokenizerBuilder と同じ設定フォーマット（設定を参照）のうち segmenter: セクション相当を受け取り、SegmenterConfig（serde_json::Value）から Segmenter を構築します：

#![allow(unused)]
fn main() {
use serde_json::json;
use lindera::segmenter::{Segmenter, SegmenterConfig};

let config: SegmenterConfig = json!({
    "mode": "normal",
    "dictionary": "embedded://ipadic",
    "keep_whitespace": false,
    "use_mmap": false
});
let segmenter = Segmenter::from_config(&config)?;
}

注: ここでは use_mmap を明示的に示すためにあえて false を指定していますが、省略した場合も後述のデフォルト（true）と同じ挙動になります。

メモリマップド読み込み

ファイルシステム辞書（embedded:// ではない辞書）に対しては、mmap cargo feature がコンパイルに含まれている場合（デフォルトで含まれます）、 use_mmap はデフォルトで true になり、メモリマップド読み込みが自動的に 使用されます。単純なファイル読み込み（非メモリマップド）を強制したい場合は false を指定してください。 辞書フォーマットバージョン 2 以降、トライ・単語リストファイル・接続コスト 行列はいずれもマップしたバイト列上で直接参照されるため、大きなコンポーネント はすべて遅延読み込みされ、ロード時に所有メモリへ全体展開されるものは ありません。 use_mmap は embedded:// 辞書に対しては無視されます（埋め込みデータは 既に静的なゼロコピーバイトスライスであるため）。mmap cargo feature （デフォルトで有効）が必要です。

空白文字の扱い

デフォルトでは、MeCab互換のため空白のみのトークンは出力から除外されます。Segmenter に対して keep_whitespace(true) を呼び出すと、これらを保持できます：

#![allow(unused)]
fn main() {
let segmenter = Segmenter::new(Mode::Normal, dictionary, None).keep_whitespace(true);
}

未知語のグルーピング

未知語のグルーピングはデフォルトでは無制限です。max_grouping_len(Some(n)) で MeCab の max-grouping-size と同じ意味論（先頭を除いた文字数で数え、MeCab のデフォルトは 24）の上限を設定できます。上限を超えるランは 1 文字ずつの未知語になります:

#![allow(unused)]
fn main() {
let segmenter = Segmenter::new(Mode::Normal, dictionary, None).max_grouping_len(Some(24));
}

グルーピングとは独立に、Lindera はデフォルトで MeCab/Vibrato 由来の 「候補ラダー（length ladder）」も生成します。各カテゴリの char.def の LENGTH フィールドまでの短い未知語候補を段階的に生成し、Viterbi 探索が 最もコストの低い長さを選べるようにします。v6 以前と同一の出力にするには unknown_word_ladder(false) で無効化してください:

#![allow(unused)]
fn main() {
let segmenter = Segmenter::new(Mode::Normal, dictionary, None).unknown_word_ladder(false);
}

N-Best セグメンテーション

segment_nbest は、コストの合計で並べた上位 n 件の分割結果を、それぞれのコストと共に返します。unique を指定すると、単語境界は同じで品詞タグのみ異なる結果を重複排除できます。cost_threshold を指定すると、best_cost + threshold を超えるコストのパスを除外できます：

#![allow(unused)]
fn main() {
let results = segmenter.segment_nbest(Cow::Borrowed("すもももももももものうち"), 3, false, None)?;
for (tokens, cost) in results {
    println!("cost={cost}");
    for token in tokens {
        println!("  {}", token.surface.as_ref());
    }
}
}

segment_nbest_with_lattice は同じ処理を行いますが、呼び出しごとの Lattice バッファの再確保を避けるために、再利用可能な Lattice を自分で渡すことができます。

文分割

ラティスを構築する前に、Linderaは入力テキストを区切り文字（\n、\t、。、、）で文単位に分割し、1文ずつ処理します。文の先頭からおよそ 32 KiB 以内に区切り文字が見つからない場合、Linderaはその位置で強制的に文の境界を区切り、警告をログに出力します。これは、その文に対して構築される Viterbi ラティスのサイズ（ひいてはメモリ・CPU コスト）を制限するためです。通常のテキストに対してはこの挙動は意識する必要がありませんが、区切り文字を含まない病的な入力（例えば minify されたテキストや base64 エンコードされたデータなど）に対しては、この人為的な分割位置でトークナイズ結果に影響が出ることがあります。

再利用可能な Worker

SegmentWorker は、Viterbi ラティスとバックトレース用スクラッチバッファを所有する再利用可能なセグメンテーションセッションです。呼び出しのたびに segment が支払うアロケーションを回避できます。new_worker（セグメンターを clone）または into_worker（セグメンターを消費し、ユーザー辞書のコピーを回避）で作成し、segment/segment_nbest を呼び出します：

#![allow(unused)]
fn main() {
let mut worker = segmenter.new_worker();
for line in lines {
    let tokens = worker.segment(line)?;
    for token in &tokens {
        println!("{}", token.surface.as_ref());
    }
}
}

返されるトークンは worker を借用するため、次の呼び出しの前に消費する必要があります（上記のような行単位のループはそのままコンパイルできます）。set_mode と set_keep_whitespace で呼び出しごとに設定を切り替えられます。segmenter() は内部の Segmenter への共有参照を返します。&mut でのアクセサは意図的に提供されていません。再利用中のラティスの下で辞書を差し替えてしまうと、この worker が保証する辞書とラティスの対応関係が壊れてしまうためです。

Worker は保持メモリも制限します。区切り文字のない最大長の文を 1 回処理するとラティスは数 MB まで成長し（32 KiB の ASCII 文で約 18 MB、32 KiB の CJK 文では文字索引ラティスのスロット数が 1/3 のため約 6 MB）、素の Lattice はそれを保持し続けます。Worker は一定回数の呼び出し窓で容量が過大と判明した場合に自動でラティスを縮小し、shrink_to(text_len_hint) で即時に縮小することもできます。reset() は内部バッファを破棄して新しいものに置き換えます。これは、例えばパニックによって worker を保持する Mutex がポイズニングされた場合など、バッファが不整合な中間状態を保持している可能性がある回復経路のために用意されています。Segmenter の設定（mode や空白の扱いなど）自体は保持されます。

Worker は作成元セグメンターの辞書に恒久的に紐付けられ、稼働中の worker の辞書を差し替える手段はありません。これにより、ラティス再利用に起因するバグの一群を構造的に排除しています。マルチスレッドで使う場合は、共有の Segmenter からスレッドごとに worker を 1 つ作成してください。

エラーハンドリング

Lindera はライブラリ全体で使いやすいエラーハンドリングを実現するため、anyhow と thiserror に基づく構造化されたエラーシステムを使用しています。

LinderaResult

LinderaResult<T> 型エイリアスは、Lindera における失敗する可能性のある操作の標準的な戻り値型です：

#![allow(unused)]
fn main() {
pub type LinderaResult<T> = Result<T, LinderaError>;
}

LinderaError

LinderaError はメインのエラー型で、エラー種別と完全なコンテキストを持つソースエラーを含みます：

#![allow(unused)]
fn main() {
pub struct LinderaError {
    pub kind: LinderaErrorKind,
    source: anyhow::Error,
}
}

add_context メソッドを使用して、エラーに追加のコンテキストを付与できます：

#![allow(unused)]
fn main() {
let error = error.add_context("failed to load dictionary from /path/to/dict");
}

LinderaErrorKind

LinderaErrorKind はエラーを分類する列挙型です：

エラーの作成

LinderaErrorKind::with_error を使用して、種別とソースからエラーを作成します：

#![allow(unused)]
fn main() {
use lindera::error::LinderaErrorKind;

let error = LinderaErrorKind::Io.with_error(anyhow::anyhow!("file not found: config.yml"));
}

? 演算子の使用

Lindera の関数は LinderaResult を返すため、? 演算子で自然にエラーを伝播できます：

#![allow(unused)]
fn main() {
use lindera::dictionary::load_dictionary;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera_analysis::tokenizer::Tokenizer;
use lindera::LinderaResult;

fn analyze(text: &str) -> LinderaResult<Vec<String>> {
    let dictionary = load_dictionary("embedded://ipadic")?;
    let segmenter = Segmenter::new(Mode::Normal, dictionary, None);
    let tokenizer = Tokenizer::new(segmenter);

    let tokens = tokenizer.tokenize(text)?;
    Ok(tokens.iter().map(|t| t.surface.as_ref().to_string()).collect())
}
}

エラーハンドリングパターン

エラー種別によるマッチング

#![allow(unused)]
fn main() {
use lindera::dictionary::load_dictionary;
use lindera::error::LinderaErrorKind;

match load_dictionary("/path/to/dictionary") {
    Ok(dict) => { /* 辞書を使用 */ }
    Err(e) if e.kind() == LinderaErrorKind::NotFound => {
        eprintln!("Dictionary not found: {}", e);
    }
    Err(e) if e.kind() == LinderaErrorKind::Io => {
        eprintln!("I/O error loading dictionary: {}", e);
    }
    Err(e) => {
        eprintln!("Unexpected error: {}", e);
    }
}
}

外部エラーからの変換

#![allow(unused)]
fn main() {
use lindera::error::LinderaErrorKind;

let content = std::fs::read_to_string("config.yml")
    .map_err(|err| LinderaErrorKind::Io.with_error(anyhow::anyhow!(err)))?;
}

APIリファレンス

APIリファレンスは以下で公開されています：

• lindera
• lindera-analysis

Lindera Analysis

Lindera Analysisは、linderaクレートが提供する純粋な形態素解析器（Segmenter）の上に、Lucene流のテキスト解析チェーンを重ねるクレートです。文字フィルタ、Segmenter、トークンフィルタを1つのTokenizerパイプラインとして組み合わせ、Rustコードから組み立てることも、YAML設定ファイルだけで組み立てることもできます。

主な特徴

• 文字フィルタ: セグメンテーション前に入力テキストを変換し、バイトオフセットは元のテキストに対して自動的に補正される
• トークンフィルタ: Segmenterが生成したトークンの変換・結合・除去・並べ替えを行う
• Tokenizer / TokenizerBuilder: Rustコード、またはYAMLファイル（LINDERA_CONFIG_PATH）から解析パイプライン全体を組み立てる
• 日本語・韓国語・汎用のテキスト正規化をカバーする豊富な組み込みフィルタ

目次

• 設定 -- TokenizerのYAML設定ファイル形式
• フィルタ -- すべての文字フィルタ・トークンフィルタのリファレンス
• アーキテクチャ -- 内部構造と主要コンポーネント
• APIリファレンス -- APIドキュメント

設定

LinderaはYAML形式の設定ファイルを読み込むことができます。 環境変数 LINDERA_CONFIG_PATH にファイルのパスを指定してください。Rustコードでトークナイザーの動作をコーディングすることなく、簡単に利用できます。

segmenter:
  mode: "normal"
  dictionary: "embedded://ipadic"
  # user_dictionary: "./resources/user_dict/ipadic_simple_userdic.csv"
  # keep_whitespace: false
  # use_mmap: false # ファイルシステム辞書（embedded:// ではない辞書）にのみ意味がある
  # max_grouping_len: 24 # 未知語のグルーピング長の上限。省略または 0 で無制限
  # unknown_word_ladder: true # 短い未知語候補も生成する（デフォルト: true）

character_filters:
  - kind: "unicode_normalize"
    args:
      kind: "nfkc"
  - kind: "japanese_iteration_mark"
    args:
      normalize_kanji: true
      normalize_kana: true
  - kind: mapping
    args:
       mapping:
         リンデラ: Lindera

token_filters:
  - kind: "japanese_compound_word"
    args:
      tags:
        - "名詞,数"
        - "名詞,接尾,助数詞"
      new_tag: "名詞,数"
  - kind: "japanese_number"
    args:
      tags:
        - "名詞,数"
  - kind: "japanese_stop_tags"
    args:
      tags:
        - "接続詞"
        - "助詞"
        - "助詞,格助詞"
        - "助詞,格助詞,一般"
        - "助詞,格助詞,引用"
        - "助詞,格助詞,連語"
        - "助詞,係助詞"
        - "助詞,副助詞"
        - "助詞,間投助詞"
        - "助詞,並立助詞"
        - "助詞,終助詞"
        - "助詞,副助詞／並立助詞／終助詞"
        - "助詞,連体化"
        - "助詞,副詞化"
        - "助詞,特殊"
        - "助動詞"
        - "記号"
        - "記号,一般"
        - "記号,読点"
        - "記号,句点"
        - "記号,空白"
        - "記号,括弧閉"
        - "その他,間投"
        - "フィラー"
        - "非言語音"
  - kind: "japanese_katakana_stem"
    args:
      min: 3
  - kind: "remove_diacritical_mark"
    args:
      japanese: false

Segmenter のオプション

% export LINDERA_CONFIG_PATH=./resources/config/lindera.yml

use std::path::PathBuf;

use lindera_analysis::tokenizer::TokenizerBuilder;
use lindera::LinderaResult;

fn main() -> LinderaResult<()> {
    // 設定ファイルからトークナイザーの設定を読み込む
    let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("../resources")
        .join("config")
        .join("lindera.yml");

    let builder = TokenizerBuilder::from_file(&path)?;

    let tokenizer = builder.build()?;

    let text = "Ｌｉｎｄｅｒａは形態素解析ｴﾝｼﾞﾝです。ユーザー辞書も利用可能です。".to_string();
    println!("text: {text}");

    let tokens = tokenizer.tokenize(&text)?;

    for token in tokens {
        println!(
            "token: {:?}, start: {:?}, end: {:?}, details: {:?}",
            token.surface, token.byte_start, token.byte_end, token.details
        );
    }

    Ok(())
}

フィルタ

文字フィルタ（Character Filter）とトークンフィルタ（Token Filter）は、lindera-analysisのTokenizerパイプラインにおける前処理・後処理の2つの段階です。

• 文字フィルタはセグメンテーションの前に入力テキストを変換します。バイトオフセットは自動的に補正されるため、変換後のテキストに対して生成されたトークンでも、元のフィルタ前のテキストにおける位置が正しく報告されます。
• トークンフィルタはSegmenterが生成したトークンのリストをセグメンテーションの後に変換します。

どちらのフィルタも設定方法は共通で、kind文字列（CLIの--character-filter / --token-filterフラグでもkind:{"json": "args"}という形式で使用されます）と、フィルタ固有のパラメータを持つJSONのargsオブジェクトで構成されます。

文字フィルタ

文字フィルタはYAML設定ファイルのcharacter_filtersキーで設定します。各エントリは順番に適用され、あるフィルタの出力が次のフィルタの入力になります。

unicode_normalize

4種類の標準的なUnicode正規化形式のいずれかを使って入力テキストを正規化します。

パラメータ:

例:

{
  "kind": "unicode_normalize",
  "args": {
    "kind": "nfkc"
  }
}

japanese_iteration_mark

日本語の踊り字（繰り返し記号）である々、ゝ、ゞ、ヽ、ヾを、それぞれが繰り返す文字に置き換えて正規化します。ひらがな・カタカナの繰り返し記号については、必要に応じて濁点の付与・除去も行います。

パラメータ:

例:

{
  "kind": "japanese_iteration_mark",
  "args": {
    "normalize_kanji": true,
    "normalize_kana": true
  }
}

mapping（文字フィルタ）

mappingのキーに一致する部分を対応する値に置き換えます。入力テキスト全体に対して、Aho-Corasickオートマトンによる最長一致検索を行います。

パラメータ:

例:

{
  "kind": "mapping",
  "args": {
    "mapping": {
      "リンデラ": "Lindera"
    }
  }
}

regex

正規表現にマッチした箇所をすべて、リテラルな置換文字列で置き換えます。キャプチャグループの内容は置換文字列に展開されません。

パラメータ:

例:

{
  "kind": "regex",
  "args": {
    "pattern": "\\s{2,}",
    "replacement": " "
  }
}

トークンフィルタ

トークンフィルタはYAML設定ファイルのtoken_filtersキーで設定します。各フィルタは、Segmenterが生成したトークンリストに対して順番に適用されます。

japanese_base_form

トークンの表層形を、辞書のbase_form（またはorthographic_base_form）フィールドに登録された原形（辞書形）に置き換えます。動詞・形容詞のレンマ化（見出し語化）として機能します。未知語処理によって生成されたトークン（token.word_id.is_unknown()）は変更されません。

このフィルタに設定パラメータはありません。

例:

{
  "kind": "japanese_base_form"
}

japanese_compound_word

品詞タグがtagsのいずれかに一致する連続したトークンを、1つの複合語トークンに結合します。

パラメータ:

例:

{
  "kind": "japanese_compound_word",
  "args": {
    "tags": [
      "名詞,数",
      "名詞,接尾,助数詞"
    ],
    "new_tag": "名詞,数"
  }
}

japanese_kana

トークンテキストをひらがなとカタカナの間で相互変換します。

パラメータ:

例:

{
  "kind": "japanese_kana",
  "args": {
    "kind": "hiragana"
  }
}

japanese_katakana_stem

カタカナのトークンの末尾にある長音記号（ー、U+30FC）を除去します。ただし、トークンの文字数がminより大きい場合のみ除去されます。

パラメータ:

例:

{
  "kind": "japanese_katakana_stem",
  "args": {
    "min": 3
  }
}

japanese_keep_tags

品詞タグがtagsのいずれかに一致するトークンのみを保持し、それ以外を除去します。

タグは 4 階層のカンマ区切りに正規化され（不足分は * で補完）、各トークンの先頭 4 つの品詞詳細と完全一致で比較されます。IPADIC の助詞トークンは必ず 助詞,係助詞 のようにサブカテゴリを持つため、助詞 単独では一致しません。一方、助動詞はサブカテゴリを持たないため（助動詞,*,*,*）、助動詞 単独で一致します。この動作は japanese_stop_tags も同様です。

パラメータ:

例:

{
  "kind": "japanese_keep_tags",
  "args": {
    "tags": [
      "名詞,一般"
    ]
  }
}

japanese_number

トークンの表層テキストに含まれる日本語の数値表現（漢数字、大字、全角数字）をアラビア数字に変換します。

パラメータ:

例:

{
  "kind": "japanese_number",
  "args": {
    "tags": [
      "名詞,数"
    ]
  }
}

japanese_reading_form

トークンの表層テキストを、辞書のreadingフィールドに登録された読み（カタカナ）に置き換えます。未知語処理によって生成されたトークン（token.word_id.is_unknown()）は変更されません。

このフィルタに設定パラメータはありません。

例:

{
  "kind": "japanese_reading_form"
}

japanese_stop_tags

品詞タグがtagsのいずれかに一致するトークンを除去します。

パラメータ:

例:

{
  "kind": "japanese_stop_tags",
  "args": {
    "tags": [
      "助詞,格助詞,一般",
      "助詞,係助詞",
      "助詞,連体化",
      "助動詞"
    ]
  }
}

keep_words

表層テキストがwordsのいずれかに完全一致するトークンのみを保持します。

パラメータ:

例:

{
  "kind": "keep_words",
  "args": {
    "words": [
      "すもも",
      "もも"
    ]
  }
}

korean_keep_tags

最初の品詞タグがtagsのいずれかに一致する韓国語トークンのみを保持します。

パラメータ:

例:

{
  "kind": "korean_keep_tags",
  "args": {
    "tags": [
      "NNG"
    ]
  }
}

korean_reading_form

トークンの表層テキストを、辞書のreadingフィールドに登録された読みに置き換えます。未知語処理によって生成されたトークン（token.word_id.is_unknown()）は変更されません。

このフィルタに設定パラメータはありません。

例:

{
  "kind": "korean_reading_form"
}

korean_stop_tags

最初の品詞タグがtagsのいずれかに一致する韓国語トークンを除去します。

パラメータ:

例:

{
  "kind": "korean_stop_tags",
  "args": {
    "tags": [
      "EP",
      "EF",
      "JKG"
    ]
  }
}

length

表層テキストの文字数が[min, max]の範囲に収まるトークンのみを保持します。

パラメータ:

例:

{
  "kind": "length",
  "args": {
    "min": 2,
    "max": 3
  }
}

lowercase

トークンの表層テキストを小文字に変換します。

このフィルタに設定パラメータはありません。

例:

{
  "kind": "lowercase"
}

mapping（トークンフィルタ）

mappingのキーに一致する部分を、各トークンの表層テキスト内で対応する値に置き換えます。Aho-Corasickオートマトンによる最長一致検索を使用します。文字フィルタのmappingのトークン版に相当します。

パラメータ:

例:

{
  "kind": "mapping",
  "args": {
    "mapping": {
      "籠": "篭"
    }
  }
}

remove_diacritical_mark

トークンの表層テキストからダイアクリティカルマーク（発音区別符号）を除去し、その後テキストの元のUnicode正規化形式を再適用します。

パラメータ:

例:

{
  "kind": "remove_diacritical_mark",
  "args": {
    "japanese": false
  }
}

stop_words

表層テキストがwordsのいずれかに完全一致するトークンを除去します。

パラメータ:

例:

{
  "kind": "stop_words",
  "args": {
    "words": [
      "も",
      "の"
    ]
  }
}

uppercase

トークンの表層テキストを大文字に変換します。

このフィルタに設定パラメータはありません。

例:

{
  "kind": "uppercase"
}

YAML設定

文字フィルタとトークンフィルタは、Segmenterと一緒に1つのYAMLファイルで設定します。ファイル全体の形式は設定を参照してください。関連する部分だけを抜粋すると次のようになります。

character_filters:
  - kind: "unicode_normalize"
    args:
      kind: "nfkc"
  - kind: "japanese_iteration_mark"
    args:
      normalize_kanji: true
      normalize_kana: true

token_filters:
  - kind: "japanese_stop_tags"
    args:
      tags:
        - "助詞,格助詞,一般"
        - "助詞,係助詞"
        - "助詞,連体化"
        - "助動詞"
  - kind: "japanese_katakana_stem"
    args:
      min: 3
  - kind: "lowercase"
  - kind: "length"
    args:
      min: 2

Rust API

文字フィルタとトークンフィルタは、プログラムから作成・適用することもできます。

use lindera::dictionary::load_dictionary;
use lindera::mode::Mode;
use lindera::segmenter::Segmenter;
use lindera_analysis::character_filter::BoxCharacterFilter;
use lindera_analysis::character_filter::unicode_normalize::{
    UnicodeNormalizeCharacterFilter, UnicodeNormalizeKind,
};
use lindera_analysis::token_filter::BoxTokenFilter;
use lindera_analysis::token_filter::japanese_stop_tags::JapaneseStopTagsTokenFilter;
use lindera_analysis::token_filter::japanese_katakana_stem::JapaneseKatakanaStemTokenFilter;
use lindera_analysis::tokenizer::Tokenizer;
use lindera::LinderaResult;

fn main() -> LinderaResult<()> {
    let dictionary = load_dictionary("embedded://ipadic")?;
    let segmenter = Segmenter::new(Mode::Normal, dictionary, None);

    let mut tokenizer = Tokenizer::new(segmenter);

    // 文字フィルタを追加
    let normalize_filter = UnicodeNormalizeCharacterFilter::new(UnicodeNormalizeKind::NFKC);
    tokenizer.append_character_filter(BoxCharacterFilter::from(normalize_filter));

    // トークンフィルタを追加
    let stop_tags_filter = JapaneseStopTagsTokenFilter::new(
        vec![
            "助詞,格助詞,一般".to_string(),
            "助詞,係助詞".to_string(),
            "助詞,連体化".to_string(),
            "助動詞".to_string(),
        ]
        .into_iter()
        .collect(),
    );
    tokenizer.append_token_filter(BoxTokenFilter::from(stop_tags_filter));

    let katakana_stem_filter =
        JapaneseKatakanaStemTokenFilter::new(std::num::NonZeroUsize::new(3).unwrap());
    tokenizer.append_token_filter(BoxTokenFilter::from(katakana_stem_filter));

    // フィルタを適用してトークナイズ
    let tokens = tokenizer.tokenize("Linderaは形態素解析エンジンです。")?;

    for token in tokens {
        println!(
            "token: {:?}, details: {:?}",
            token.surface, token.details
        );
    }

    Ok(())
}

append_character_filterとappend_token_filterメソッドは、フィルタを追加した順番で登録します。文字フィルタはセグメンテーション前のテキストに対して順次適用され、トークンフィルタはセグメンテーション後のトークンリストに対して順次適用されます。

アーキテクチャ

モジュール構成

lindera-analysis/src/
├── lib.rs                          # パブリックAPIの再エクスポート、CLIフラグ解析ヘルパー
├── character_filter.rs              # CharacterFilter trait、OffsetMapping、CharacterFilterLoader
├── character_filter/
│   ├── unicode_normalize.rs         # Unicode正規化（NFC/NFD/NFKC/NFKD）
│   ├── japanese_iteration_mark.rs   # 日本語の踊り字（繰り返し記号）正規化
│   ├── mapping.rs                   # マッピングによるテキスト置換
│   └── regex.rs                     # 正規表現によるテキスト置換
├── token_filter.rs                  # TokenFilter trait、TokenFilterLoader
├── token_filter/
│   ├── japanese_base_form.rs
│   ├── japanese_compound_word.rs
│   ├── japanese_kana.rs
│   ├── japanese_katakana_stem.rs
│   ├── japanese_keep_tags.rs
│   ├── japanese_number.rs
│   ├── japanese_reading_form.rs
│   ├── japanese_stop_tags.rs
│   ├── keep_words.rs
│   ├── korean_keep_tags.rs
│   ├── korean_reading_form.rs
│   ├── korean_stop_tags.rs
│   ├── length.rs
│   ├── lowercase.rs
│   ├── mapping.rs
│   ├── remove_diacritical_mark.rs
│   ├── stop_words.rs
│   ├── tags.rs                      # keep/stop系タグフィルタが共有するヘルパー（非公開）
│   └── uppercase.rs
└── tokenizer.rs                      # Tokenizer、TokenizerBuilder

主要コンポーネント

CharacterFilter

セグメンテーション前にテキストを前処理するフィルタのtraitです。各実装はname()と、textをその場で書き換えて実施した変換内容をOffsetMappingとして返すapply(&self, text: &mut String) -> LinderaResult<OffsetMapping>を提供します。

OffsetMapping（Transformationレコードのリストから構築される）により、複数のフィルタを順に適用した後でも、Tokenizerはフィルタ後のテキストに対して計算されたトークンのバイトオフセットを、元の入力テキストにおけるバイトオフセットへ変換できます。BoxCharacterFilterは任意のCharacterFilter実装をボックス化・クローン可能なトレイトオブジェクトとしてラップし、CharacterFilterLoaderはkind文字列とserde_json::Valueの引数からフィルタを構築します（YAML設定の読み込みとCLIフラグ解析の両方で利用されます）。

TokenFilter

Segmenterが生成したトークンを後処理するフィルタのtraitです。各実装はname()と、トークンをその場で変換・結合・並べ替え・除去するapply(&self, tokens: &mut Vec<Token<'_>>) -> LinderaResult<()>を提供します。BoxTokenFilterは任意のTokenFilter実装をボックス化・クローン可能なトレイトオブジェクトとしてラップし、TokenFilterLoaderはCharacterFilterLoaderと同様に、kind文字列とserde_json::Valueの引数からフィルタを構築します。

Tokenizer / TokenizerBuilder

Tokenizerは、文字フィルタ、lindera::segmenter::Segmenter、トークンフィルタを1つの解析パイプラインとして組み合わせます。tokenizeを呼び出すと、入力テキストに文字フィルタを適用し、フィルタ後のテキストをセグメンテーションし、得られたトークンにトークンフィルタを適用したうえで、記録済みのOffsetMappingを使って各トークンのバイトオフセットを元のテキストに対する値へ補正します。

TokenizerBuilderはTokenizerConfig（serde_json::Value）からTokenizerを組み立てます。この設定はプログラムから直接構築することも、YAMLファイルから読み込むこと（TokenizerBuilder::from_file、または環境変数LINDERA_CONFIG_PATH経由で自動的に読み込むTokenizerBuilder::new）も、set_segmenter_mode・set_segmenter_dictionary・append_character_filter・append_token_filterで段階的に組み立てることもできます。YAMLファイルの形式は設定を、フィルタの完全なリファレンスはフィルタを参照してください。

AnalysisWorker

AnalysisWorker（Tokenizer::new_workerまたはTokenizer::into_workerで作成）は、解析チェーン全体に対する再利用可能なセッションです。呼び出しごとのバッファ — Viterbiラティスとバックトレース用スクラッチ（SegmentWorker経由）、文字フィルタが操作する正規化テキストバッファ、オフセットマッピング用スクラッチ — をすべて所有するため、tokenizeを繰り返し呼び出してもTokenizer::tokenizeが支払う呼び出しごとのアロケーションを回避できます。文字フィルタが設定されている場合、トークンのsurfaceはトークンごとのStringにコピーされる代わりにワーカーのバッファを借用します。返されるトークンはワーカーを借用するため、次の呼び出しの前に消費する必要があります。マルチスレッドで使う場合はスレッドごとにワーカーを作成してください（あるいはlindera-binding-coreのようにMutexで保護します）。基盤となるSegmentWorkerと自動メモリ縮小ポリシーについてはSegmenterのページを参照してください。

AnalysisWorkerの主なpublicメソッド:

• tokenize(&mut self, text: &str) — ワーカーの内部バッファを再利用しながら、解析チェーン全体を通してtextをトークナイズします。同じ入力・設定であればTokenizer::tokenizeとまったく同じトークンを返します。
• tokenize_nbest(&mut self, text: &str, n, unique, cost_threshold) — ワーカーの内部バッファを再利用しながら、コスト付きの上位N件の結果をトークナイズして返します。Tokenizer::tokenize_nbestとまったく同じ結果を返します。
• set_mode(&mut self, mode: Mode) — 以降の呼び出しで使用するセグメンテーションモードを設定します。
• set_keep_whitespace(&mut self, keep: bool) — 以降の呼び出しで空白トークンを出力に残すかどうかを設定します。
• shrink_to(&mut self, text_len_hint: usize) — ワーカーの内部バッファを、text_len_hintバイトの入力に必要なサイズまで直ちに縮小します。
• reset(&mut self) — すべての内部バッファを破棄し、新しいバッファに置き換えます。（例えばワーカーを保持するMutexがパニックでpoisonedになった場合の）リカバリ用途を想定しており、設定（辞書・フィルタ・モード）は保持されます。

Feature フラグ

APIリファレンス

APIリファレンスは以下で公開されています：

• lindera-analysis

Lindera CLI

Lindera のための形態素解析コマンドラインインターフェースです。

• インストール - CLIのインストールまたはビルド
• コマンド - list、tokenize、build、download、train、export のコマンドリファレンス
• チュートリアル - はじめの一歩のステップバイステップガイド

インストール

cargo経由でインストール

cargo経由でバイナリをインストールできます：

% cargo install lindera-cli

GitHub Releasesからダウンロード

または、以下のリリースページからビルド済みバイナリをダウンロードすることもできます：

• https://github.com/lindera/lindera/releases

辞書の入手

Lindera はバイナリに辞書を同梱していません。最も簡単な入手方法は download サブコマンドで、CLI と同じバージョンのビルド済み辞書を取得して OS 標準のアプリケーションデータディレクトリにインストールします：

% lindera download ipadic

ダウンロード後は辞書名で参照できます：

% echo "関西国際空港限定トートバッグ" | lindera tokenize --dict ipadic

利用可能な辞書名と保存場所についてはコマンドを参照してください。

または、GitHub Releases ページからビルド済み辞書を手動でダウンロードすることもできます：

# 例: IPADIC 辞書のダウンロードと展開
% curl -LO https://github.com/lindera/lindera/releases/download/<version>/lindera-ipadic-<version>.zip
% unzip lindera-ipadic-<version>.zip -d /path/to/ipadic

CLI 使用時に展開した辞書パスを指定します（アーカイブには lindera-ipadic ディレクトリが含まれる点に注意）：

% echo "関西国際空港限定トートバッグ" | lindera tokenize --dict /path/to/ipadic/lindera-ipadic

ソースからビルド

辞書なしでビルド（デフォルト）

辞書を埋め込まず、トークナイザーとトレーナーのみを含むバイナリをビルドします：

% cargo build --release

全機能を含めてビルド

% cargo build --release --all-features

辞書埋め込みビルド（上級者向け）

辞書をバイナリに直接埋め込みたい上級者向けに、embed-* feature フラグを使用できます。実行時の外部辞書ファイルが不要になりますが、バイナリサイズが増加します。

IPADIC（日本語辞書）

% cargo build --release --features=embed-ipadic

IPADIC NEologd（日本語辞書）

% cargo build --release --features=embed-ipadic-neologd

UniDic（日本語辞書）

% cargo build --release --features=embed-unidic

SudachiDict（日本語辞書）

% cargo build --release --features=embed-sudachidict

ko-dic（韓国語辞書）

% cargo build --release --features=embed-ko-dic

CC-CEDICT（中国語辞書）

% cargo build --release --features=embed-cc-cedict

Jieba（中国語辞書）

% cargo build --release --features=embed-jieba

[!TIP] embed-* feature フラグ付きでビルドした後、embedded:// スキームで埋め込み辞書をロードできます：

% echo "関西国際空港限定トートバッグ" | lindera tokenize --dict embedded://ipadic

詳細は Feature フラグ を参照してください。

コマンド

Lindera CLI は6つのメインコマンドを提供します：

• list - 形態素解析辞書の一覧と状態を表示
• tokenize - テキストに対して形態素解析を実行
• build - ソースCSVファイルから辞書をビルド
• download - GitHub リリースページから学習済み辞書をダウンロード
• train - 注釈付きコーパスデータからCRFモデルを学習
• export - 学習済みモデルを辞書フォーマットにエクスポート

list

既知の形態素解析辞書の一覧を表示し、各辞書について（embed-* feature フラグ経由で）バイナリに埋め込まれているか、および lindera download で学習済み辞書がローカルにダウンロード済みかを表示します。

list パラメータ

このコマンドは引数を取りません。環境変数 LINDERA_DATA_DIR を設定すると、ダウンロード済み辞書を探すアプリケーションデータディレクトリを上書きできます（lindera download と同じ挙動です）。

list の使用方法

% lindera list

NAME            EMBEDDED  DOWNLOADED  PATH
ipadic          yes       yes         /home/user/.local/share/lindera/dictionaries/5.1.0/lindera-ipadic
ipadic-neologd  no        no          -
unidic          no        incomplete  /home/user/.local/share/lindera/dictionaries/5.1.0/lindera-unidic
sudachidict     no        no          -
ko-dic          no        no          -
cc-cedict       no        no          -
jieba           no        no          -

出力は1行につき1辞書です：

• EMBEDDED は、ビルド時に辞書が埋め込まれている場合（例: --features=embed-ipadic）に yes になります。
• DOWNLOADED は、実行中の CLI バージョンに対応する lindera download でインストールされた完全な辞書が存在する場合に yes、インストールディレクトリは存在するが必要なファイルが欠けている場合に incomplete になります（lindera download <name> --force で再ダウンロードしてください）。
• PATH は、インストールディレクトリが存在する場合はそのパス、存在しない場合は - を表示します。

tokenize

様々な辞書を使用して、日本語、中国語、または韓国語のテキストに対して形態素解析（トークナイズ）を行います。

パラメータ

• --dict / -d: 辞書のパス、URI、またはダウンロード済み辞書名（必須）
  • ファイルパス: /path/to/dictionary
  • 埋め込み: embedded://ipadic, embedded://unidic, etc.
  • ダウンロード済み辞書名: ipadic, unidic など。lindera download でインストールした辞書に解決されます。同名のファイルパスが実在する場合はパスが優先されます。
• --output / -o: 出力形式 (デフォルト: mecab)
  • mecab: 品詞情報を含むMeCab互換形式
  • wakati: スペース区切りのトークンのみ
  • json: すべてのトークン情報を含む詳細なJSON形式
• --user-dict / -u: ユーザー辞書のパス（オプション）
• --mode / -m: トークナイズモード (デフォルト: normal)
  • normal: 標準的なトークナイズ
  • decompose: 複合語を分解する
• --char-filter / -c: 文字フィルタ設定 (JSON)
• --token-filter / -t: トークンフィルタ設定 (JSON)
• --keep-whitespace: 空白文字のトークンを出力に含める（デフォルトでは MeCab 互換のため空白は除去されます）
• --max-grouping-len: 未知語グルーピングの上限（先頭を除いた文字数。MeCab の max-grouping-size に相当し、MeCab のデフォルトは 24）。上限を超えるランは 1 文字ずつの未知語になります。デフォルト: 無制限
• --disable-unknown-word-ladder: MeCab/Vibrato 由来の未知語候補ラダー（char.def の LENGTH フィールド）を無効化する。デフォルトで有効。v6 以前の Lindera と同一の出力にするには無効化する
• --mmap: 辞書ディレクトリの単語リストにメモリマップドファイル読み込みを使用する。embedded:// 辞書、および mmap feature が無効な場合は無視される。プロセスがマップを保持している間に辞書ディレクトリを再ビルド・切り詰めると、次回のルックアップで SIGBUS を引き起こす可能性がある。
• --nbest / -N: 返す N-best 結果の数（デフォルト: 1）。2以上に設定すると N-best 出力が有効になります。
• --nbest-unique: 同じ分割を生成するパスの重複を排除します。
• --nbest-cost-threshold: 最良パスからの最大コスト差。best_cost + threshold 以内のコストを持つパスのみが返されます。
• 入力ファイル: オプションのファイルパス (デフォルト: 標準入力)

基本的な使用方法

# 辞書ディレクトリを指定してトークナイズ
echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict /path/to/dictionary

# 埋め込み辞書を指定してトークナイズ
echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict embedded://ipadic

# 出力形式を指定してトークナイズ
echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict embedded://ipadic \
  --output json

# ファイルからテキストを読み込んでトークナイズ
lindera tokenize \
  --dict /path/to/dictionary \
  --output wakati \
  input.txt

外部辞書を使用した例

外部IPADIC（日本語辞書）を使用したトークナイズ

% echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict /tmp/lindera-ipadic-2.7.0-20250920

日本語  名詞,一般,*,*,*,*,日本語,ニホンゴ,ニホンゴ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
形態素  名詞,一般,*,*,*,*,形態素,ケイタイソ,ケイタイソ
解析    名詞,サ変接続,*,*,*,*,解析,カイセキ,カイセキ
を      助詞,格助詞,一般,*,*,*,を,ヲ,ヲ
行う    動詞,自立,*,*,五段・ワ行促音便,基本形,行う,オコナウ,オコナウ
こと    名詞,非自立,一般,*,*,*,こと,コト,コト
が      助詞,格助詞,一般,*,*,*,が,ガ,ガ
でき    動詞,自立,*,*,一段,連用形,できる,デキ,デキ
ます    助動詞,*,*,*,特殊・マス,基本形,ます,マス,マス
。      記号,句点,*,*,*,*,。,。,。
EOS

外部IPADIC NEologd（日本語辞書）を使用したトークナイズ

% echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict /tmp/lindera-ipadic-neologd-0.0.7-20200820

日本語  名詞,一般,*,*,*,*,日本語,ニホンゴ,ニホンゴ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
形態素解析      名詞,固有名詞,一般,*,*,*,形態素解析,ケイタイソカイセキ,ケイタイソカイセキ
を      助詞,格助詞,一般,*,*,*,を,ヲ,ヲ
行う    動詞,自立,*,*,五段・ワ行促音便,基本形,行う,オコナウ,オコナウ
こと    名詞,非自立,一般,*,*,*,こと,コト,コト
が      助詞,格助詞,一般,*,*,*,が,ガ,ガ
でき    動詞,自立,*,*,一段,連用形,できる,デキ,デキ
ます    助動詞,*,*,*,特殊・マス,基本形,ます,マス,マス
。      記号,句点,*,*,*,*,。,。,。
EOS

外部UniDic（日本語辞書）を使用したトークナイズ

% echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict /tmp/lindera-unidic-2.1.2

日本    名詞,固有名詞,地名,国,*,*,ニッポン,日本,日本,ニッポン,日本,ニッポン,固,*,*,*,*
語      名詞,普通名詞,一般,*,*,*,ゴ,語,語,ゴ,語,ゴ,漢,*,*,*,*
の      助詞,格助詞,*,*,*,*,ノ,の,の,ノ,の,ノ,和,*,*,*,*
形態    名詞,普通名詞,一般,*,*,*,ケイタイ,形態,形態,ケータイ,形態,ケータイ,漢,*,*,*,*
素      接尾辞,名詞的,一般,*,*,*,ソ,素,素,ソ,素,ソ,漢,*,*,*,*
解析    名詞,普通名詞,サ変可能,*,*,*,カイセキ,解析,解析,カイセキ,解析,カイセキ,漢,*,*,*,*
を      助詞,格助詞,*,*,*,*,ヲ,を,を,オ,を,オ,和,*,*,*,*
行う    動詞,一般,*,*,五段-ワア行,連体形-一般,オコナウ,行う,行う,オコナウ,行う,オコナウ,和,*,*,*,*
こと    名詞,普通名詞,一般,*,*,*,コト,事,こと,コト,こと,コト,和,コ濁,基本形,*,*
が      助詞,格助詞,*,*,*,*,ガ,が,が,ガ,が,ガ,和,*,*,*,*
でき    動詞,非自立可能,*,*,上一段-カ行,連用形-一般,デキル,出来る,でき,デキ,できる,デキル,和,*,*,*,*
ます    助動詞,*,*,*,助動詞-マス,終止形-一般,マス,ます,ます,マス,ます,マス,和,*,*,*,*
。      補助記号,句点,*,*,*,*,,。,。,,。,,記号,*,*,*,*
EOS

外部ko-dic（韓国語辞書）を使用したトークナイズ

% echo "한국어의형태해석을실시할수있습니다." | lindera tokenize \
  --dict /tmp/lindera-ko-dic-2.1.1-20180720

한국어  NNG,*,F,한국어,Compound,*,*,한국/NNG/*+어/NNG/*
의      JKG,*,F,의,*,*,*,*
형태    NNG,*,F,형태,*,*,*,*
해석    NNG,행위,T,해석,*,*,*,*
을      JKO,*,T,을,*,*,*,*
실시    NNG,행위,F,실시,*,*,*,*
할      XSV+ETM,*,T,할,Inflect,XSV,ETM,하/XSV/*+ᆯ/ETM/*
수      NNB,*,F,수,*,*,*,*
있      VV,*,T,있,*,*,*,*
습니다  EF,*,F,습니다,*,*,*,*
.       SF,*,*,*,*,*,*,*
EOS

外部CC-CEDICT（中国語辞書）を使用したトークナイズ

% echo "可以进行中文形态学分析。" | lindera tokenize \
  --dict /tmp/lindera-cc-cedict-0.1.0-20200409

可以    *,*,*,*,ke3 yi3,可以,可以,can/may/possible/able to/not bad/pretty good/
进行    *,*,*,*,jin4 xing2,進行,进行,to advance/to conduct/underway/in progress/to do/to carry out/to carry on/to execute/
中文    *,*,*,*,Zhong1 wen2,中文,中文,Chinese language/
形态学  *,*,*,*,xing2 tai4 xue2,形態學,形态学,morphology (in biology or linguistics)/
分析    *,*,*,*,fen1 xi1,分析,分析,to analyze/analysis/CL:個|个[ge4]/
。      *,*,*,*,*,*,*,*
EOS

外部Jieba（中国語辞書）を使用したトークナイズ

% echo "可以进行中文形态学分析。" | lindera tokenize \
  --dict /tmp/lindera-jieba-0.1.1

埋め込み辞書を使用した例

Linderaは、特定の機能フラグを指定してビルドすることで、バイナリに辞書を直接含めることができます。これにより、外部辞書ファイルなしでトークナイズが可能になります。

埋め込みIPADIC（日本語辞書）を使用したトークナイズ

% echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict embedded://ipadic

日本語  名詞,一般,*,*,*,*,日本語,ニホンゴ,ニホンゴ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
形態素  名詞,一般,*,*,*,*,形態素,ケイタイソ,ケイタイソ
解析    名詞,サ変接続,*,*,*,*,解析,カイセキ,カイセキ
を      助詞,格助詞,一般,*,*,*,を,ヲ,ヲ
行う    動詞,自立,*,*,五段・ワ行促音便,基本形,行う,オコナウ,オコナウ
こと    名詞,非自立,一般,*,*,*,こと,コト,コト
が      助詞,格助詞,一般,*,*,*,が,ガ,ガ
でき    動詞,自立,*,*,一段,連用形,できる,デキ,デキ
ます    助動詞,*,*,*,特殊・マス,基本形,ます,マス,マス
。      記号,句点,*,*,*,*,。,。,。
EOS

注意: IPADIC辞書をバイナリに含めるには、--features=embed-ipadic オプションを使用してビルドする必要があります。

埋め込みUniDic（日本語辞書）を使用したトークナイズ

% echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict embedded://unidic

日本    名詞,固有名詞,地名,国,*,*,ニッポン,日本,日本,ニッポン,日本,ニッポン,固,*,*,*,*
語      名詞,普通名詞,一般,*,*,*,ゴ,語,語,ゴ,語,ゴ,漢,*,*,*,*
の      助詞,格助詞,*,*,*,*,ノ,の,の,ノ,の,ノ,和,*,*,*,*
形態    名詞,普通名詞,一般,*,*,*,ケイタイ,形態,形態,ケータイ,形態,ケータイ,漢,*,*,*,*
素      接尾辞,名詞的,一般,*,*,*,ソ,素,素,ソ,素,ソ,漢,*,*,*,*
解析    名詞,普通名詞,サ変可能,*,*,*,カイセキ,解析,解析,カイセキ,解析,カイセキ,漢,*,*,*,*
を      助詞,格助詞,*,*,*,*,ヲ,を,を,オ,を,オ,和,*,*,*,*
行う    動詞,一般,*,*,五段-ワア行,連体形-一般,オコナウ,行う,行う,オコナウ,行う,オコナウ,和,*,*,*,*
こと    名詞,普通名詞,一般,*,*,*,コト,事,こと,コト,こと,コト,和,コ濁,基本形,*,*
が      助詞,格助詞,*,*,*,*,ガ,が,が,ガ,が,ガ,和,*,*,*,*
でき    動詞,非自立可能,*,*,上一段-カ行,連用形-一般,デキル,出来る,でき,デキ,できる,デキル,和,*,*,*,*
ます    助動詞,*,*,*,助動詞-マス,終止形-一般,マス,ます,ます,マス,ます,マス,和,*,*,*,*
。      補助記号,句点,*,*,*,*,,。,。,,。,,記号,*,*,*,*
EOS

注意: UniDic辞書をバイナリに含めるには、--features=embed-unidic オプションを使用してビルドする必要があります。

埋め込みIPADIC NEologd（日本語辞書）を使用したトークナイズ

% echo "日本語の形態素解析を行うことができます。" | lindera tokenize \
  --dict embedded://ipadic-neologd

日本語  名詞,一般,*,*,*,*,日本語,ニホンゴ,ニホンゴ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
形態素解析      名詞,固有名詞,一般,*,*,*,形態素解析,ケイタイソカイセキ,ケイタイソカイセキ
を      助詞,格助詞,一般,*,*,*,を,ヲ,ヲ
行う    動詞,自立,*,*,五段・ワ行促音便,基本形,行う,オコナウ,オコナウ
こと    名詞,非自立,一般,*,*,*,こと,コト,コト
が      助詞,格助詞,一般,*,*,*,が,ガ,ガ
でき    動詞,自立,*,*,一段,連用形,できる,デキ,デキ
ます    助動詞,*,*,*,特殊・マス,基本形,ます,マス,マス
。      記号,句点,*,*,*,*,。,。,。
EOS

注意: IPADIC NEologd辞書をバイナリに含めるには、--features=embed-ipadic-neologd オプションを使用してビルドする必要があります。

埋め込みko-dic（韓国語辞書）を使用したトークナイズ

% echo "한국어의형태해석을실시할수있습니다." | lindera tokenize \
  --dict embedded://ko-dic

한국어  NNG,*,F,한국어,Compound,*,*,한국/NNG/*+어/NNG/*
의      JKG,*,F,의,*,*,*,*
형태    NNG,*,F,형태,*,*,*,*
해석    NNG,행위,T,해석,*,*,*,*
을      JKO,*,T,을,*,*,*,*
실시    NNG,행위,F,실시,*,*,*,*
할      XSV+ETM,*,T,할,Inflect,XSV,ETM,하/XSV/*+ᆯ/ETM/*
수      NNB,*,F,수,*,*,*,*
있      VV,*,T,있,*,*,*,*
습니다  EF,*,F,습니다,*,*,*,*
.       SF,*,*,*,*,*,*,*
EOS

注意: ko-dic辞書をバイナリに含めるには、--features=embed-ko-dic オプションを使用してビルドする必要があります。

埋め込みCC-CEDICT（中国語辞書）を使用したトークナイズ

% echo "可以进行中文形态学分析。" | lindera tokenize \
  --dict embedded://cc-cedict

可以    *,*,*,*,ke3 yi3,可以,可以,can/may/possible/able to/not bad/pretty good/
进行    *,*,*,*,jin4 xing2,進行,进行,to advance/to conduct/underway/in progress/to do/to carry out/to carry on/to execute/
中文    *,*,*,*,Zhong1 wen2,中文,中文,Chinese language/
形态学  *,*,*,*,xing2 tai4 xue2,形態學,形态学,morphology (in biology or linguistics)/
分析    *,*,*,*,fen1 xi1,分析,分析,to analyze/analysis/CL:個|个[ge4]/
。      *,*,*,*,*,*,*,*
EOS

注意: CC-CEDICT辞書をバイナリに含めるには、--features=embed-cc-cedict オプションを使用してビルドする必要があります。

埋め込みJieba（中国語辞書）を使用したトークナイズ

% echo "可以进行中文形态学分析。" | lindera tokenize \
  --dict embedded://jieba

注意: Jieba辞書をバイナリに含めるには、--features=embed-jieba オプションを使用してビルドする必要があります。

ユーザー辞書の例

Linderaは、システム辞書と一緒にカスタム単語を追加するためのユーザー辞書をサポートしています。ユーザー辞書はCSVまたはバイナリ形式にすることができます。

ユーザー辞書の使用（CSV形式）

% echo "東京スカイツリーの最寄り駅はとうきょうスカイツリー駅です" | lindera tokenize \
  --dict embedded://ipadic \
  --user-dict ./resources/user_dict/ipadic_simple_userdic.csv

東京スカイツリー        カスタム名詞,*,*,*,*,*,東京スカイツリー,トウキョウスカイツリー,*
の      助詞,連体化,*,*,*,*,の,ノ,ノ
最寄り駅        名詞,一般,*,*,*,*,最寄り駅,モヨリエキ,モヨリエキ
は      助詞,係助詞,*,*,*,*,は,ハ,ワ
とうきょうスカイツリー駅        カスタム名詞,*,*,*,*,*,とうきょうスカイツリー駅,トウキョウスカイツリーエキ,*
です    助動詞,*,*,*,特殊・デス,基本形,です,デス,デス
EOS

ユーザー辞書の使用（バイナリ形式）

% echo "東京スカイツリーの最寄り駅はとうきょうスカイツリー駅です" | lindera tokenize \
  --dict /tmp/lindera-ipadic-2.7.0-20250920 \
  --user-dict ./resources/user_dict/ipadic_simple_userdic.bin

東京スカイツリー        カスタム名詞,*,*,*,*,*,東京スカイツリー,トウキョウスカイツリー,*
の      助詞,連体化,*,*,*,*,の,ノ,ノ
最寄り駅        名詞,一般,*,*,*,*,最寄り駅,モヨリエキ,モヨリエキ
は      助詞,係助詞,*,*,*,*,は,ハ,ワ
とうきょうスカイツリー駅        カスタム名詞,*,*,*,*,*,とうきょうスカイツリー駅,トウキョウスカイツリーエキ,*
です    助動詞,*,*,*,特殊・デス,基本形,です,デス,デス
EOS

トークナイズモード

Linderaは2つのトークナイズモードを提供します：normal と decompose です。

Normal モード（デフォルト）

辞書に登録された単語に基づいて忠実にトークナイズします：

% echo "関西国際空港限定トートバッグ" | lindera tokenize \
  --dict embedded://ipadic \
  --mode normal

関西国際空港    名詞,固有名詞,組織,*,*,*,関西国際空港,カンサイコクサイクウコウ,カンサイコクサイクーコー
限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
トートバッグ    名詞,一般,*,*,*,*,*,*,*
EOS

Decompose モード

複合語をさらに分解してトークナイズします：

% echo "関西国際空港限定トートバッグ" | lindera tokenize \
  --dict embedded://ipadic \
  --mode decompose

関西    名詞,固有名詞,地域,一般,*,*,関西,カンサイ,カンサイ
国際    名詞,一般,*,*,*,*,国際,コクサイ,コクサイ
空港    名詞,一般,*,*,*,*,空港,クウコウ,クーコー
限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
トートバッグ    名詞,一般,*,*,*,*,*,*,*
EOS

出力形式

Linderaは3つの出力形式を提供します：mecab, wakati, json。

MeCab 形式（デフォルト）

品詞情報を含むMeCab互換形式で結果を出力します：

% echo "お待ちしております。" | lindera tokenize \
  --dict embedded://ipadic \
  --output mecab

お待ち  名詞,サ変接続,*,*,*,*,お待ち,オマチ,オマチ
し  動詞,自立,*,*,サ変・スル,連用形,する,シ,シ
て  助詞,接続助詞,*,*,*,*,て,テ,テ
おり  動詞,非自立,*,*,五段・ラ行,連用形,おる,オリ,オリ
ます  助動詞,*,*,*,特殊・マス,基本形,ます,マス,マス
。  記号,句点,*,*,*,*,。,。,。
EOS

Wakati 形式

トークンテキストのみをスペース区切りで出力します：

% echo "お待ちしております。" | lindera tokenize \
  --dict embedded://ipadic \
  --output wakati

お待ち し て おり ます 。

JSON 形式

すべてのトークン情報を含む詳細なJSON形式で出力します：

% echo "お待ちしております。" | lindera tokenize \
  --dict embedded://ipadic \
  --output json

[
  {
    "base_form": "お待ち",
    "byte_end": 9,
    "byte_start": 0,
    "conjugation_form": "*",
    "conjugation_type": "*",
    "part_of_speech": "名詞",
    "part_of_speech_subcategory_1": "サ変接続",
    "part_of_speech_subcategory_2": "*",
    "part_of_speech_subcategory_3": "*",
    "pronunciation": "オマチ",
    "reading": "オマチ",
    "surface": "お待ち",
    "word_id": 14698
  },
  ...
]

N-Best トークナイズ

Linderaは N-Best トークナイズをサポートしており、コスト順（低コスト＝高精度）に上位 N 件のトークナイズ候補を返します。これは MeCab の N-Best 実装と互換性のある Forward-DP Backward-A* アルゴリズムに基づいています。

基本的な N-Best の例

% echo "すもももももももものうち" | lindera tokenize \
  --dict embedded://ipadic \
  -N 3

NBEST 1 (cost=7546)
すもも  名詞,一般,*,*,*,*,すもも,スモモ,スモモ
も      助詞,係助詞,*,*,*,*,も,モ,モ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
も      助詞,係助詞,*,*,*,*,も,モ,モ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
うち    名詞,非自立,副詞可能,*,*,*,うち,ウチ,ウチ
EOS
NBEST 2 (cost=7914)
すもも  名詞,一般,*,*,*,*,すもも,スモモ,スモモ
も      助詞,係助詞,*,*,*,*,も,モ,モ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
うち    名詞,非自立,副詞可能,*,*,*,うち,ウチ,ウチ
EOS
NBEST 3 (cost=10060)
すもも  名詞,一般,*,*,*,*,すもも,スモモ,スモモ
も      助詞,係助詞,*,*,*,*,も,モ,モ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
も      助詞,係助詞,*,*,*,*,も,モ,モ
も      助詞,係助詞,*,*,*,*,も,モ,モ
の      助詞,連体化,*,*,*,*,の,ノ,ノ
うち    名詞,非自立,副詞可能,*,*,*,うち,ウチ,ウチ
EOS

ユニーク結果を使用した N-Best

同じ分割が複数のパスに現れる場合（内部的な Viterbi 状態のみが異なる場合）、--nbest-unique を使用して重複を排除します:

% echo "営業部長谷川です" | lindera tokenize \
  --dict embedded://ipadic \
  -N 5 --nbest-unique -o wakati

NBEST 1 (cost=15760)
営業 部長 谷川 です
NBEST 2 (cost=17758)
営業 部長 谷 川 です
NBEST 3 (cost=18816)
営業 部 長谷川 です
NBEST 4 (cost=19320)
営業 部長 谷川 で す
NBEST 5 (cost=20814)
営業 部 長谷 川 です

コスト閾値を使用した N-Best

--nbest-cost-threshold を使用して、最良パスから一定のコスト範囲内の結果に制限します:

% echo "営業部長谷川です" | lindera tokenize \
  --dict embedded://ipadic \
  -N 10 --nbest-unique --nbest-cost-threshold 5000 -o wakati

NBEST 1 (cost=15760)
営業 部長 谷川 です
NBEST 2 (cost=17758)
営業 部長 谷 川 です
NBEST 3 (cost=18816)
営業 部 長谷川 です

残りの候補は 15760 + 5000 = 20760 を超えるため、3件の結果のみが返されます。

フィルタを使用した高度なトークナイズ

Linderaは、文字フィルタ、トークナイザー、トークンフィルタを組み合わせた分析フレームワークを提供します。フィルタはJSONを使用して構成します。

% echo "すもももももももものうち" | lindera tokenize \
  --dict embedded://ipadic \
  --char-filter 'unicode_normalize:{"kind":"nfkc"}' \
  --token-filter 'japanese_keep_tags:{"tags":["名詞,一般"]}'

すもも  名詞,一般,*,*,*,*,すもも,スモモ,スモモ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
もも    名詞,一般,*,*,*,*,もも,モモ,モモ
EOS

build

Linderaで使用するための形態素解析辞書をCSVソースファイルからビルド（コンパイル）します。

ビルドパラメータ

• --src / -s: 辞書CSVファイルを含むソースディレクトリ（ユーザー辞書の場合は単一CSVファイル）
• --dest / -d: コンパイルされた辞書の出力先ディレクトリ
• --metadata / -m: 辞書構造を定義するメタデータ設定ファイル (metadata.json)
• --user / -u: システム辞書の代わりにユーザー辞書をビルドする（オプションフラグ）
• --context-id-freq / -f: 接続コストIDの並び替えに使用するコンテキストID アクセス頻度ファイル（オプション。辞書の metadata.json で connection_id_mapping: true が設定されている場合にのみ意味を持ちます）

辞書の種類

システム辞書 (System dictionary)

以下を含む完全な形態素解析辞書です：

• 語彙エントリ（単語定義）
• 接続コスト行列
• 未知語処理ルール
• 文字種定義

ユーザー辞書 (User dictionary)

システム辞書と一緒に動作する、カスタム単語のための補助辞書です。

例

IPADIC（日本語辞書）のビルド

# IPADICソースファイルのダウンロードと展開
% curl -L -o /tmp/mecab-ipadic-2.7.0-20250920.tar.gz "https://Lindera.dev/mecab-ipadic-2.7.0-20250920.tar.gz"
% tar zxvf /tmp/mecab-ipadic-2.7.0-20250920.tar.gz -C /tmp

# 辞書のビルド
% lindera build \
  --src /tmp/mecab-ipadic-2.7.0-20250920 \
  --dest /tmp/lindera-ipadic-2.7.0-20250920 \
  --metadata ./lindera-ipadic/metadata.json

IPADIC NEologd（日本語辞書）のビルド

% curl -L -o /tmp/mecab-ipadic-neologd-0.0.7-20200820.tar.gz "https://lindera.dev/mecab-ipadic-neologd-0.0.7-20200820.tar.gz"
% tar zxvf /tmp/mecab-ipadic-neologd-0.0.7-20200820.tar.gz -C /tmp

% lindera build \
  --src /tmp/mecab-ipadic-neologd-0.0.7-20200820 \
  --dest /tmp/lindera-ipadic-neologd-0.0.7-20200820 \
  --metadata ./lindera-ipadic-neologd/metadata.json

UniDic（日本語辞書）のビルド

% curl -L -o /tmp/unidic-mecab-2.1.2.tar.gz "https://Lindera.dev/unidic-mecab-2.1.2.tar.gz"
% tar zxvf /tmp/unidic-mecab-2.1.2.tar.gz -C /tmp

% lindera build \
  --src /tmp/unidic-mecab-2.1.2 \
  --dest /tmp/lindera-unidic-2.1.2 \
  --metadata ./lindera-unidic/metadata.json

CC-CEDICT（中国語辞書）のビルド

% curl -L -o /tmp/CC-CEDICT-MeCab-0.1.0-20200409.tar.gz "https://lindera.dev/CC-CEDICT-MeCab-0.1.0-20200409.tar.gz"
% tar zxvf /tmp/CC-CEDICT-MeCab-0.1.0-20200409.tar.gz -C /tmp

% lindera build \
  --src /tmp/CC-CEDICT-MeCab-0.1.0-20200409 \
  --dest /tmp/lindera-cc-cedict-0.1.0-20200409 \
  --metadata ./lindera-cc-cedict/metadata.json

Jieba（中国語辞書）のビルド

% curl -L -o /tmp/mecab-jieba-0.1.1.tar.gz "https://lindera.dev/mecab-jieba-0.1.1.tar.gz"
% tar zxvf /tmp/mecab-jieba-0.1.1.tar.gz -C /tmp

% lindera build \
  --src /tmp/mecab-jieba-0.1.1/dict-src \
  --dest /tmp/lindera-jieba-0.1.1 \
  --metadata ./lindera-jieba/metadata.json

ko-dic（韓国語辞書）のビルド

% curl -L -o /tmp/mecab-ko-dic-2.1.1-20180720.tar.gz "https://Lindera.dev/mecab-ko-dic-2.1.1-20180720.tar.gz"
% tar zxvf /tmp/mecab-ko-dic-2.1.1-20180720.tar.gz -C /tmp

% lindera build \
  --src /tmp/mecab-ko-dic-2.1.1-20180720 \
  --dest /tmp/lindera-ko-dic-2.1.1-20180720 \
  --metadata ./lindera-ko-dic/metadata.json

ユーザー辞書のビルド

IPADICユーザー辞書（日本語）のビルド

ユーザー辞書フォーマットの詳細については、以下のURLを参照してください：

• Lindera IPADIC Builder/User Dictionary Format

% lindera build \
  --src ./resources/user_dict/ipadic_simple_userdic.csv \
  --dest ./resources/user_dict \
  --metadata ./lindera-ipadic/metadata.json \
  --user

UniDicユーザー辞書（日本語）のビルド

ユーザー辞書フォーマットの詳細については、以下のURLを参照してください：

• Lindera UniDic Builder/User Dictionary Format

% lindera build \
  --src ./resources/user_dict/unidic_simple_userdic.csv \
  --dest ./resources/user_dict \
  --metadata ./lindera-unidic/metadata.json \
  --user

SudachiDictユーザー辞書（日本語）のビルド

ユーザー辞書フォーマットの詳細については、以下のURLを参照してください：

• Lindera SudachiDict Builder/User Dictionary Format

% lindera build \
  --src ./resources/user_dict/sudachidict_simple_userdic.csv \
  --dest ./resources/user_dict \
  --metadata ./lindera-sudachidict/metadata.json \
  --user

CC-CEDICTユーザー辞書（中国語）のビルド

ユーザー辞書フォーマットの詳細については、以下のURLを参照してください：

• Lindera CC-CEDICT Builder/User Dictionary Format

% lindera build \
  --src ./resources/user_dict/cc-cedict_simple_userdic.csv \
  --dest ./resources/user_dict \
  --metadata ./lindera-cc-cedict/metadata.json \
  --user

Jiebaユーザー辞書（中国語）のビルド

ユーザー辞書フォーマットの詳細については、以下のURLを参照してください：

• Lindera Jieba Builder/User Dictionary Format

% lindera build \
  --src ./resources/user_dict/jieba_simple_userdic.csv \
  --dest ./resources/user_dict \
  --metadata ./lindera-jieba/metadata.json \
  --user

ko-dicユーザー辞書（韓国語）のビルド

ユーザー辞書フォーマットの詳細については、以下のURLを参照してください：

• Lindera ko-dic Builder/User Dictionary Format

% lindera build \
  --src ./resources/user_dict/ko-dic_simple_userdic.csv \
  --dest ./resources/user_dict \
  --metadata ./lindera-ko-dic/metadata.json \
  --user

download

CLI と同じバージョンの学習済み辞書アーカイブを GitHub リリースページからダウンロードし、OS 標準のアプリケーションデータディレクトリにインストールします。

download パラメータ

• 辞書名（必須）: ipadic, ipadic-neologd, unidic, sudachidict, ko-dic, cc-cedict, jieba のいずれか
• --force: 既存の辞書を再ダウンロードして置き換える

保存場所

辞書はバージョン付きレイアウト <データディレクトリ>/dictionaries/<バージョン>/lindera-<辞書名>/ にインストールされます。OS ごとのデフォルトのベースディレクトリ：

環境変数 LINDERA_DATA_DIR を設定するとベースディレクトリを上書きできます。この変数はビルド時のソースキャッシュ用変数 LINDERA_BUILD_DICTIONARY_CACHE_DIR とは無関係です。

download の使用方法

% lindera download ipadic

Downloading https://github.com/lindera/lindera/releases/download/v5.1.0/lindera-ipadic-5.1.0.zip
100% (15.1/15.1 MiB)
Downloaded dictionary 'ipadic'
/home/user/.local/share/lindera/dictionaries/5.1.0/lindera-ipadic

インストール先のパスは標準出力に出力されるため（進捗や通知は標準エラー出力）、スクリプトで取得できます：

% DICT_DIR=$(lindera download ipadic)

ダウンロード後は tokenize で辞書名を指定して参照できます：

% echo "日本語の形態素解析を行うことができます。" | lindera tokenize --dict ipadic

注意事項：

• アーカイブのバージョンは常に CLI のバージョンと一致します。リリースが公開されていない開発版のバージョンで実行すると HTTP 404 で失敗します。
• 整合性は HTTPS トランスポートと ZIP アーカイブ内蔵のファイルごとの CRC32 チェックサムで検証されます。
• 最大の辞書（ipadic-neologd）は約 305 MB のダウンロードで、展開時にはその約 2 倍の空きディスク容量が必要です。

train

注釈付きコーパスデータから新しい形態素解析モデルを学習します。この機能を使用するには、train 機能フラグを有効にしてビルドする必要があります。（train 機能フラグはデフォルトで有効になっています。）

学習パラメータ

• --seed / -s: 重み付けを行うシード語彙ファイル（CSV形式）
• --corpus / -c: 学習用コーパス（注釈付きテキスト）
• --char-def / -C: 文字定義ファイル (char.def)
• --unk-def / -u: 未知語定義ファイル (unk.def) - 重み付けの対象
• --feature-def / -f: 素性定義ファイル (feature.def)
• --rewrite-def / -r: 書換えルール定義ファイル (rewrite.def)
• --output / -o: 出力モデルファイル
• --lambda / -l: 正則化係数 (0.0-1.0) (デフォルト: 0.01)
• --regularization / -R: 正則化の種類: l1, l2, または elasticnet (デフォルト: l1)
• --elastic-net-l1-ratio: Elastic Net 正則化時のL1比率 (0.0-1.0)。--regularization elasticnet を指定した場合のみ使用されます (デフォルト: 0.5)
• --max-iterations / -i: 学習の最大反復回数 (デフォルト: 100)
• --max-threads / -t: 最大スレッド数 (デフォルトはCPUコア数。速度のみに影響し、学習結果は変わりません)

基本的なワークフロー

1. 学習用ファイルの準備

シード語彙ファイル (seed.csv):

シード語彙ファイルは、CRFモデルの学習に使用される初期辞書エントリを含みます。各行はカンマ区切りのフィールドを持つ単語エントリを表します：

• 表層形
• 左文脈ID
• 右文脈ID
• 単語コスト
• 品詞タグ（複数のフィールド）
• 原形
• 読み（カタカナ）
• 発音

注意: 正確なフィールド定義は辞書フォーマット（IPADIC, UniDic, ko-dic, CC-CEDICT）によって異なります。詳細は各辞書のフォーマット仕様を参照してください。

外国,0,0,0,名詞,一般,*,*,*,*,外国,ガイコク,ガイコク
人,0,0,0,名詞,接尾,一般,*,*,*,人,ジン,ジン

学習用コーパス (corpus.txt):

学習用コーパスファイルは、CRFモデルの学習に使用される注釈付きテキストデータを含みます。各行は以下で構成されます：

• 表層形（単語）とそれに続くタブ文字
• カンマ区切りの形態素素性（品詞タグ、原形、読み、発音）
• 文は "EOS" (End Of Sentence) マーカーで区切られます

外国	名詞,一般,*,*,*,*,外国,ガイコク,ガイコク
人	名詞,接尾,一般,*,*,*,人,ジン,ジン
参政	名詞,サ変接続,*,*,*,*,参政,サンセイ,サンセイ
権	名詞,接尾,一般,*,*,*,権,ケン,ケン
EOS

ファイルフォーマットや高度な機能の詳細については、学習パイプライン を参照してください。

2. モデルの学習

lindera train \
  --seed ./resources/training/seed.csv \
  --corpus ./resources/training/corpus.txt \
  --unk-def ./resources/training/unk.def \
  --char-def ./resources/training/char.def \
  --feature-def ./resources/training/feature.def \
  --rewrite-def ./resources/training/rewrite.def \
  --output /tmp/lindera/training/model.dat \
  --lambda 0.01 \
  --max-iterations 100

3. 学習結果

学習済みモデルには以下が含まれます：

• 既存単語: 新しく学習された重みを持つすべてのシード辞書レコード
• 新語: シード辞書にはないがコーパスに含まれる単語（適切な重み付きで追加）

export

学習済みモデルファイルをLindera辞書フォーマットのファイルにエクスポートします。この機能を使用するには、train 機能フラグを有効にしてビルドする必要があります。

エクスポートパラメータ

• --model / -m: 学習済みモデルファイル（.dat形式）のパス
• --output / -o: 辞書ファイルの出力先ディレクトリ
• --metadata: オプションの metadata.json ファイル（学習済みモデル情報で更新されます）
• --cost-factor: 重みからコストへの変換係数を上書き（デフォルト: 学習済みモデルの値、通常は700）

出力ファイル

エクスポートコマンドは出力ディレクトリに以下の辞書ファイルを作成します：

• lex.csv: 学習された重みを持つ語彙ファイル（MeCab互換の tocost() によるコスト変換）
• matrix.def: 全 (right_id, left_id) ペアを網羅する密な接続コスト行列
• unk.def: 未知語定義
• char.def: 文字種定義
• feature.def: 素性テンプレート定義（学習済みモデルからコピー）
• rewrite.def: 素性リライトルール（学習済みモデルからコピー）
• left-id.def: 左文脈IDから素性文字列へのマッピング
• right-id.def: 右文脈IDから素性文字列へのマッピング
• metadata.json: 更新されたメタデータファイル（--metadata オプションが指定された場合）

完全なワークフロー例

1. モデルの学習

lindera train \
  --seed ./resources/training/seed.csv \
  --corpus ./resources/training/corpus.txt \
  --unk-def ./resources/training/unk.def \
  --char-def ./resources/training/char.def \
  --feature-def ./resources/training/feature.def \
  --rewrite-def ./resources/training/rewrite.def \
  --output /tmp/lindera/training/model.dat \
  --lambda 0.01 \
  --max-iterations 100

2. 辞書フォーマットへのエクスポート

lindera export \
  --model /tmp/lindera/training/model.dat \
  --metadata ./resources/training/metadata.json \
  --output /tmp/lindera/training/dictionary

3. 辞書のビルド

lindera build \
  --src /tmp/lindera/training/dictionary \
  --dest /tmp/lindera/training/compiled_dictionary \
  --metadata /tmp/lindera/training/dictionary/metadata.json

4. 学習済み辞書の使用

echo "これは外国人参政権です。" | lindera tokenize \
  -d /tmp/lindera/training/compiled_dictionary

メタデータ更新機能

--metadata オプションが指定されると、エクスポートコマンドは以下の処理を行います：

1. ベースとなる metadata.json ファイルを読み込み、既存の設定を保持します
2. 特定のフィールドを学習済みモデルの値で更新します：
   • default_word_cost: 素性重みの中央値から計算された値
   • model_info: 素性数、ラベル数、行列サイズ、反復回数、正則化、バージョンを含む学習統計情報。タイムスタンプは書き込まれないため、同じモデルを 2 回エクスポートすると同一の出力になります
3. 既存の設定を保持します（辞書名、文字エンコード設定、スキーマ定義、その他のユーザー定義設定など）

チュートリアル

このチュートリアルでは、Lindera CLIの基本的な使い方を、インストールから高度なテキスト処理まで順を追って説明します。

1. CLIのインストール

Lindera CLIをインストールします：

% cargo install lindera-cli

インストールの確認：

% lindera --help

2. 辞書のダウンロード

GitHub リリースページからビルド済みの IPADIC 辞書をダウンロードします。辞書は OS 標準のアプリケーションデータディレクトリにインストールされます：

% lindera download ipadic

利用可能な辞書名と保存場所についてはコマンドを参照してください。

3. 基本的なトークナイズ

ダウンロードした IPADIC 辞書を辞書名で参照して、日本語テキストをトークナイズします：

% echo "東京は日本の首都です。" | lindera tokenize \
  --dict ipadic

期待される出力：

東京    名詞,固有名詞,地域,一般,*,*,東京,トウキョウ,トーキョー
は      助詞,係助詞,*,*,*,*,は,ハ,ワ
日本    名詞,固有名詞,地域,国,*,*,日本,ニホン,ニホン
の      助詞,連体化,*,*,*,*,の,ノ,ノ
首都    名詞,一般,*,*,*,*,首都,シュト,シュト
です    助動詞,*,*,*,特殊・デス,基本形,です,デス,デス
。      記号,句点,*,*,*,*,。,。,。
EOS

4. 異なる出力形式を試す

Wakati 形式（分かち書きのみ）

% echo "東京は日本の首都です。" | lindera tokenize \
  --dict ipadic \
  --output wakati

期待される出力：

東京 は 日本 の 首都 です 。

JSON 形式（詳細情報）

% echo "東京は日本の首都です。" | lindera tokenize \
  --dict ipadic \
  --output json

バイトオフセット、品詞タグ、読みなどの詳細なトークン情報を含むJSON配列が出力されます。

5. Decompose モードの使用

Decompose モードは複合名詞を構成要素に分解します：

% echo "関西国際空港限定トートバッグ" | lindera tokenize \
  --dict ipadic \
  --mode decompose

期待される出力：

関西    名詞,固有名詞,地域,一般,*,*,関西,カンサイ,カンサイ
国際    名詞,一般,*,*,*,*,国際,コクサイ,コクサイ
空港    名詞,一般,*,*,*,*,空港,クウコウ,クーコー
限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
トートバッグ    名詞,一般,*,*,*,*,*,*,*
EOS

Normal モードと比較すると、「関西国際空港」が1つのトークンのままになる点が異なります。

6. 文字フィルタとトークンフィルタの適用

Unicode正規化を行い、一般名詞のみを保持します：

% echo "Ｌｉｎｄｅｒａは形態素解析ｴﾝｼﾞﾝです。" | lindera tokenize \
  --dict ipadic \
  --char-filter 'unicode_normalize:{"kind":"nfkc"}' \
  --token-filter 'japanese_keep_tags:{"tags":["名詞,一般","名詞,サ変接続","名詞,固有名詞,組織"]}'

期待される出力：

Lindera 名詞,固有名詞,組織,*,*,*,*,*,*
形態素  名詞,一般,*,*,*,*,形態素,ケイタイソ,ケイタイソ
解析    名詞,サ変接続,*,*,*,*,解析,カイセキ,カイセキ
エンジン        名詞,一般,*,*,*,*,エンジン,エンジン,エンジン
EOS

Unicode正規化により全角文字が半角に変換され、Token Filter により指定した品詞タグに一致するトークンのみが保持されます。

複数のフィルタを組み合わせることもできます：

% echo "すもももももももものうち" | lindera tokenize \
  --dict ipadic \
  --token-filter 'japanese_stop_tags:{"tags":["助詞,格助詞,一般","助詞,係助詞","助詞,連体化","助動詞"]}'

7. ユーザー辞書の使用

カスタム単語エントリを含むCSVファイル（例: my_dict.csv）を作成します：

東京スカイツリー,カスタム名詞,トウキョウスカイツリー

ユーザー辞書を使用してトークナイズします：

% echo "東京スカイツリーの最寄り駅はとうきょうスカイツリー駅です" | lindera tokenize \
  --dict ipadic \
  --user-dict ./my_dict.csv

ユーザー辞書がない場合、「東京スカイツリー」は複数のトークンに分割されます。ユーザー辞書を使用すると、1つのトークンとして認識されます。

ビルド済みのユーザー辞書の例については、以下を参照してください：

% echo "東京スカイツリーの最寄り駅はとうきょうスカイツリー駅です" | lindera tokenize \
  --dict ipadic \
  --user-dict ./resources/user_dict/ipadic_simple_userdic.csv

期待される出力：

東京スカイツリー        カスタム名詞,*,*,*,*,*,東京スカイツリー,トウキョウスカイツリー,*
の      助詞,連体化,*,*,*,*,の,ノ,ノ
最寄り駅        名詞,一般,*,*,*,*,最寄り駅,モヨリエキ,モヨリエキ
は      助詞,係助詞,*,*,*,*,は,ハ,ワ
とうきょうスカイツリー駅        カスタム名詞,*,*,*,*,*,とうきょうスカイツリー駅,トウキョウスカイツリーエキ,*
です    助動詞,*,*,*,特殊・デス,基本形,です,デス,デス
EOS

Lindera Python

Lindera Python は、PyO3 を使用して構築された Lindera 形態素解析エンジンの Python バインディングです。Python 3.10 以降をサポートし、Lindera の高性能なトークナイズ機能を Python エコシステムに提供します。

特徴

• 多言語対応: 日本語（IPADIC、IPADIC NEologd、UniDic）、韓国語（ko-dic）、中国語（CC-CEDICT、Jieba）のテキストをトークナイズ
• テキスト処理パイプライン: 文字フィルタとトークンフィルタを組み合わせて、柔軟な前処理・後処理が可能
• CRF ベースの辞書学習: アノテーション付きコーパスからカスタム形態素解析モデルを学習（train feature が必要）
• 複数のトークナイズモード: 解析粒度に応じた Normal モードと Decompose モード
• N-best トークナイズ: コスト順にランク付けされた複数のトークナイズ候補を取得
• ユーザー辞書: システム辞書をカスタム語彙で拡張

ドキュメント

• インストール -- 前提条件、ビルド手順、feature フラグ
• クイックスタート -- 最小限の使用例
• Tokenizer API -- TokenizerBuilder、Tokenizer、Token クラスリファレンス
• 辞書管理 -- 辞書の読み込み、ビルド、管理
• テキスト処理パイプライン -- 文字フィルタとトークンフィルタ
• 学習 -- カスタム CRF モデルの学習と辞書のエクスポート

インストール

PyPI からのインストール

ビルド済みホイールが PyPI で公開されています：

pip install lindera

[!NOTE] PyPI パッケージには辞書が含まれていません。下記の辞書の入手を参照してください。

辞書の入手

Lindera はパッケージに辞書を同梱していません。ビルド済み辞書を別途入手する必要があります。

GitHub Releases からのダウンロード

ビルド済み辞書は GitHub Releases ページから入手できます。辞書アーカイブをダウンロードしてローカルディレクトリに展開してください：

# 例: IPADIC 辞書のダウンロードと展開
curl -LO https://github.com/lindera/lindera/releases/download/<version>/lindera-ipadic-<version>.zip
unzip lindera-ipadic-<version>.zip -d /path/to/ipadic

ソースからのビルド

特定の feature フラグを有効にする必要がある場合など、ソースからビルドするには以下の前提条件が必要です：

• Python 3.10 以降（3.14 まで）
• Rust ツールチェーン -- rustup 経由でインストール
• maturin -- Rust ベースの Python 拡張をビルドするための Python パッケージ

maturin を pip でインストールします：

pip install maturin

開発ビルド

lindera-python を開発モードでビルドしてインストールします：

cd lindera-python
maturin develop

または、プロジェクトの Makefile を使用します：

make python-develop

学習機能付きビルド

train feature を有効にすると、CRF ベースの辞書学習機能が利用可能になります。デフォルトで有効になっています：

maturin develop --features train

Feature フラグ

複数の feature を組み合わせることができます：

maturin develop --features "train,embed-ipadic,embed-ko-dic"

[!TIP] 辞書をバイナリに直接埋め込みたい場合（上級者向け）は、対応する embed-* feature フラグを有効にしてビルドし、embedded:// スキームでロードしてください：

dictionary = load_dictionary("embedded://ipadic")

詳細は Feature フラグ を参照してください。

インストールの確認

インストール後、Python で lindera が利用可能であることを確認します：

import lindera

print(lindera.version())

クイックスタート

このガイドでは、lindera-python を使用してテキストをトークナイズする方法を紹介します。

基本的なトークナイズ

トークナイザーの作成には TokenizerBuilder の使用を推奨します：

from lindera import TokenizerBuilder

builder = TokenizerBuilder()
builder.set_mode("normal")
builder.set_dictionary("/path/to/ipadic")
tokenizer = builder.build()

tokens = tokenizer.tokenize("関西国際空港限定トートバッグ")
for token in tokens:
    print(f"{token.surface}\t{','.join(token.details)}")

注意: ビルド済み辞書を GitHub Releases からダウンロードし、展開したディレクトリのパスを指定してください。

期待される出力：

関西国際空港    名詞,固有名詞,組織,*,*,*,関西国際空港,カンサイコクサイクウコウ,カンサイコクサイクーコー
限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
トートバッグ    UNK

メソッドチェーン

TokenizerBuilder は簡潔な設定のためにメソッドチェーンをサポートしています：

from lindera import TokenizerBuilder

tokenizer = (
    TokenizerBuilder()
    .set_mode("normal")
    .set_dictionary("/path/to/ipadic")
    .build()
)

tokens = tokenizer.tokenize("すもももももももものうち")
for token in tokens:
    print(f"{token.surface}\t{token.get_detail(0)}")

トークンプロパティへのアクセス

各トークンは以下のプロパティを公開しています：

from lindera import TokenizerBuilder

tokenizer = TokenizerBuilder().set_dictionary("/path/to/ipadic").build()
tokens = tokenizer.tokenize("東京タワー")

for token in tokens:
    print(f"Surface: {token.surface}")
    print(f"Byte range: {token.byte_start}..{token.byte_end}")
    print(f"Position: {token.position}")
    print(f"Word ID: {token.word_id}")
    print(f"Unknown: {token.is_unknown}")
    print(f"Details: {token.details}")
    print()

N-best トークナイズ

コスト順にランク付けされた複数のトークナイズ候補を取得します：

from lindera import TokenizerBuilder

tokenizer = TokenizerBuilder().set_dictionary("/path/to/ipadic").build()
results = tokenizer.tokenize_nbest("すもももももももものうち", n=3)

for tokens, cost in results:
    surfaces = [t.surface for t in tokens]
    print(f"Cost {cost}: {' / '.join(surfaces)}")

Tokenizer API

TokenizerBuilder

TokenizerBuilder はビルダーパターンを使用して Tokenizer インスタンスを設定・構築します。

コンストラクタ

TokenizerBuilder()

デフォルト設定で新しいビルダーを作成します。

from lindera import TokenizerBuilder

builder = TokenizerBuilder()

TokenizerBuilder().from_file(file_path)

YAML ファイルから設定を読み込み、新しいビルダーを返します。segmenter、 character_filters、token_filters を含む完全な例は lindera-python/resources/lindera.yml を参照してください。

builder = TokenizerBuilder().from_file("lindera.yml")

設定メソッド

すべてのセッターメソッドはメソッドチェーンのために self を返します。

set_mode(mode)

トークナイズモードを設定します。

• "normal" -- 標準的なトークナイズ（デフォルト）
• "decompose" -- 複合語をより小さな単位に分解

builder.set_mode("normal")

set_dictionary(path)

システム辞書のパスまたは URI を設定します。

# 埋め込み辞書を使用
builder.set_dictionary("embedded://ipadic")

# 外部辞書を使用
builder.set_dictionary("/path/to/dictionary")

set_user_dictionary(uri)

ユーザー辞書の URI を設定します。

builder.set_user_dictionary("/path/to/user_dictionary")

set_keep_whitespace(keep)

出力に空白トークンを含めるかどうかを制御します。

builder.set_keep_whitespace(True)

append_character_filter(kind, args=None)

前処理パイプラインに文字フィルタを追加します。

builder.append_character_filter("unicode_normalize", {"kind": "nfkc"})

append_token_filter(kind, args=None)

後処理パイプラインにトークンフィルタを追加します。

builder.append_token_filter("lowercase", {})

ビルド

build()

設定された内容で Tokenizer をビルドして返します。

tokenizer = builder.build()

Tokenizer

Tokenizer はテキストに対して形態素解析を行います。

Tokenizer の作成

Tokenizer(dictionary, mode="normal", user_dictionary=None)

読み込み済みの辞書から直接トークナイザーを作成します。

from lindera import Tokenizer, load_dictionary

dictionary = load_dictionary("embedded://ipadic")
tokenizer = Tokenizer(dictionary, mode="normal")

Tokenizer メソッド

tokenize(text)

入力テキストをトークナイズし、Token オブジェクトのリストを返します。

tokens = tokenizer.tokenize("形態素解析")

パラメータ:

戻り値: list[Token]

tokenize_surfaces(text)

入力テキストをトークナイズし、トークンの surface のみを文字列のリストとして返します。分かち書き用途の高速パスです。Token オブジェクトを生成せず、形態素の詳細情報もロードしないため、surface 文字列だけが必要な場合は tokenize より大幅に高速です。結果は [t.surface for t in tokenizer.tokenize(text)] と一致します。

surfaces = tokenizer.tokenize_surfaces("形態素解析")
# ["形態素", "解析"]

パラメータ:

戻り値: list[str]

tokenize_nbest(text, n, unique=False, cost_threshold=None)

N-best トークナイズ結果を返します。各結果はトータルパスコストとペアになっています。

results = tokenizer.tokenize_nbest("すもももももももものうち", n=3)
for tokens, cost in results:
    print(cost, [t.surface for t in tokens])

パラメータ:

戻り値: list[tuple[list[Token], int]]

Mode

Mode はトークナイズモードを表します。モードの確認や比較のためのスタンドアロンな ヘルパーとして提供されています。TokenizerBuilder.set_mode() と Tokenizer の コンストラクタは、現在は Mode インスタンスではなく単純なモード文字列 （"normal" または "decompose"）のみを受け付けます（下記 Penalty の制限事項 も参照）。

Mode の作成

Mode(mode_str=None)

Mode を作成します。"normal" / "Normal"（省略時のデフォルト）または "decompose" / "Decompose" を受け付けます。それ以外の値を指定すると ValueError が発生します。

from lindera import Mode

mode = Mode("normal")
mode = Mode("decompose")
mode = Mode()  # デフォルトは "normal"

メソッド

mode = Mode("decompose")
str(mode)            # "decompose"
repr(mode)           # "Mode.Decompose"
mode.is_normal()      # False
mode.is_decompose()   # True

Penalty

Penalty は "decompose" モードのセグメンテーションで使用される、長さに基づく ペナルティの閾値を設定します。

Penalty の作成

Penalty(kanji_penalty_length_threshold=2, kanji_penalty_length_penalty=3000, other_penalty_length_threshold=7, other_penalty_length_penalty=1700)

すべての引数は省略可能で、上記の値がデフォルトとして使用されます。

from lindera import Penalty

penalty = Penalty(
    kanji_penalty_length_threshold=2,
    kanji_penalty_length_penalty=3000,
    other_penalty_length_threshold=7,
    other_penalty_length_penalty=1700,
)

Penalty のプロパティ

4 つのフィールドはすべて取得・設定の両方をサポートしています：

penalty.kanji_penalty_length_threshold = 3
print(penalty.kanji_penalty_length_threshold)  # 3

現在の制限事項: 現時点では Penalty を Tokenizer や TokenizerBuilder に 渡す方法はありません。set_mode() と Tokenizer のコンストラクタは単純な モード文字列のみを受け付け、内部的に "decompose" モードは常に Penalty の デフォルト値を使用します -- カスタムの Penalty インスタンスを作成しても、 トークナイズには反映されません。

Token

Token は単一の形態素トークンを表します。

プロパティ

Token メソッド

get_detail(index)

指定されたインデックスの詳細文字列を返します。インデックスが範囲外の場合は None を返します。

token = tokenizer.tokenize("東京")[0]
pos = token.get_detail(0)        # 例: "名詞"
subpos = token.get_detail(1)     # 例: "固有名詞"
reading = token.get_detail(7)    # 例: "トウキョウ"

パラメータ:

戻り値: str または None

to_dict()

トークンをプレーンな dict として返します。各フィールドは Python の自然な型を 保つため、独自のエンコーダなしでシリアライズできます。

import json

data = tokenizer.tokenize("東京")[0].to_dict()
# {'surface': '東京', 'byte_start': 0, 'byte_end': 6, 'position': 0,
#  'word_id': 12345, 'is_unknown': False, 'details': [...]}

json.dumps([token.to_dict() for token in tokens])

戻り値: surface、byte_start、byte_end、position、word_id、 is_unknown、details をキーに持つ dict。

details の構造は辞書によって異なります：

• IPADIC: [品詞, 品詞細分類1, 品詞細分類2, 品詞細分類3, 活用型, 活用形, 原形, 読み, 発音]
• UniDic: UniDic 仕様に準拠した詳細な形態素情報
• ko-dic / CC-CEDICT / Jieba: 各辞書固有の詳細フォーマット

エラーハンドリング

Lindera Python の関数は、カスタムの例外型ではなく標準的な Python の例外を送出します：

• IOError（OSError のエイリアス） -- ファイルが存在しない、読み込めないなどの I/O 関連の失敗
• ValueError -- それ以外のすべてのケース（不正な設定、パースエラー、 トークナイズの失敗など）

from lindera import load_dictionary

try:
    dictionary = load_dictionary("/path/that/does/not/exist")
except ValueError as e:
    print(f"Failed to load dictionary: {e}")

lindera.LinderaError クラスも登録されていますが、このクレート内のどの関数からも 送出されることはありません -- 手動で構築・送出する場合にのみ使用できます。この ライブラリのエラーを処理する際は、LinderaError ではなく IOError / ValueError（または一般的な Exception）をキャッチしてください。

辞書管理

Lindera Python は、形態素解析で使用する辞書の読み込み、ビルド、管理のための関数を提供します。

辞書の読み込み

システム辞書

load_dictionary(uri) を使用してシステム辞書を読み込みます。GitHub Releases からビルド済み辞書をダウンロードし、展開したディレクトリのパスを指定してください：

from lindera import load_dictionary

dictionary = load_dictionary("/path/to/ipadic")

埋め込み辞書（上級者向け） -- embed-* feature フラグ付きでビルドした場合、埋め込み辞書を使用できます：

dictionary = load_dictionary("embedded://ipadic")

読み込んだ Dictionary は、自身のメタデータも公開しています：

print(dictionary.metadata_name())      # 例: "ipadic"
print(dictionary.metadata_encoding())  # 例: "UTF-8"
metadata = dictionary.metadata()       # Metadata オブジェクト全体

これは、システム辞書と同じメタデータ（スキーマ、エンコーディングなど）を 共有する必要があるユーザー辞書を読み込む際に便利です。 lindera-python/examples/tokenize_with_userdict.py を参照してください：

from lindera import Tokenizer, load_dictionary, load_user_dictionary

dictionary = load_dictionary("embedded://ipadic")
metadata = dictionary.metadata()
user_dictionary = load_user_dictionary("/path/to/user_dictionary.csv", metadata)

tokenizer = Tokenizer(dictionary, mode="normal", user_dictionary=user_dictionary)

ユーザー辞書

ユーザー辞書はシステム辞書にカスタム語彙を追加します。

from lindera import load_user_dictionary, Metadata

metadata = Metadata()
user_dict = load_user_dictionary("/path/to/user_dictionary", metadata)

トークナイザーのビルド時にユーザー辞書を渡します：

from lindera import Tokenizer, load_dictionary, load_user_dictionary, Metadata

dictionary = load_dictionary("/path/to/ipadic")
metadata = Metadata()
user_dict = load_user_dictionary("/path/to/user_dictionary", metadata)

tokenizer = Tokenizer(dictionary, mode="normal", user_dictionary=user_dict)

または、ビルダー経由で設定します：

from lindera import TokenizerBuilder

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("/path/to/ipadic")
    .set_user_dictionary("/path/to/user_dictionary")
    .build()
)

辞書のビルド

システム辞書のビルド

ソースファイルからシステム辞書をビルドします：

from lindera import build_dictionary, Metadata

metadata = Metadata(name="custom", encoding="UTF-8")
build_dictionary("/path/to/input_dir", "/path/to/output_dir", metadata)

入力ディレクトリには辞書のソースファイル（CSV レキシコン、matrix.def など）が含まれている必要があります。

ユーザー辞書のビルド

CSV ファイルからユーザー辞書をビルドします：

from lindera import build_user_dictionary, Metadata

metadata = Metadata()
build_user_dictionary("ipadic", "user_words.csv", "/path/to/output_dir", metadata)

metadata パラメータは省略可能です。省略した場合はデフォルトのメタデータ値が使用されます：

build_user_dictionary("ipadic", "user_words.csv", "/path/to/output_dir")

注意: 最初の引数（上記の "ipadic"）は現在未使用で、将来のために予約されて いるものです -- ビルドの選択や設定には一切影響しません。ビルドの挙動は metadata（特に metadata.user_dictionary_schema）によってのみ制御されます。 現時点では任意の文字列を渡すことができます。

Metadata

Metadata クラスは辞書のパラメータを設定します。

Metadata の作成

from lindera import Metadata

# デフォルトのメタデータ
metadata = Metadata()

# カスタムメタデータ
metadata = Metadata(
    name="my_dictionary",
    encoding="UTF-8",
    default_word_cost=-10000,
)

JSON からの読み込み

metadata = Metadata.from_json_file("metadata.json")

プロパティ

すべてのプロパティは取得と設定の両方をサポートしています：

metadata = Metadata()
metadata.name = "custom_dict"
metadata.encoding = "EUC-JP"
print(metadata.name)  # "custom_dict"

to_dict()

メタデータの辞書表現を返します：

metadata = Metadata(name="test")
print(metadata.to_dict())

Schema

Schema、FieldDefinition、FieldType は、辞書エントリーのフィールド構成を 表します。スキーマは Metadata.dictionary_schema と Metadata.user_dictionary_schema（上記の表を参照）で使用されます。

FieldType

FieldType は単一フィールドの種別を列挙します：

• FieldType.Surface -- 表層形（単語のテキスト）
• FieldType.LeftContextId -- 左文脈 ID
• FieldType.RightContextId -- 右文脈 ID
• FieldType.Cost -- 単語コスト
• FieldType.Custom -- その他の辞書固有フィールド

FieldDefinition

FieldDefinition はスキーマ内の単一フィールドを表します。

FieldDefinition(index, name, field_type, description=None)

from lindera import FieldDefinition, FieldType

field = FieldDefinition(0, "surface", FieldType.Surface, "Surface form")

プロパティ（読み取り専用）：

Schema の作成

Schema はフィールド名の順序付きリストを保持し、フィールド名とインデックス間の 相互参照を提供します。

Schema(fields)

フィールド名のリストからスキーマを作成します。

from lindera import Schema

schema = Schema([
    "surface",
    "left_context_id",
    "right_context_id",
    "cost",
    "major_pos",
    "reading",
])

Schema.create_default()

組み込みのデフォルトスキーマを返す静的メソッドです。13 個のフィールドから成り、 IPADIC 形式のレイアウトに対応します（surface, left_context_id, right_context_id, cost, major_pos, pos_detail_1, pos_detail_2, pos_detail_3, conjugation_type, conjugation_form, base_form, reading, pronunciation）。

schema = Schema.create_default()

Schema のメソッドとプロパティ

schema = Schema.create_default()

schema.field_count()               # 13
schema.get_field_index("cost")     # 3
schema.get_field_name(0)           # "surface"
schema.get_custom_fields()         # ["major_pos", "pos_detail_1", ..., "pronunciation"]
len(schema)                        # 13

field = schema.get_field_by_name("surface")
print(field.index, field.name, field.field_type)  # 0 surface FieldType.Surface

schema.validate_record([
    "東京", "1288", "1288", "100",
    "名詞", "固有名詞", "地域", "一般", "*", "*",
    "東京", "トウキョウ", "トーキョー",
])

テキスト処理パイプライン

Lindera Python は、トークナイズ前に文字フィルタを適用し、トークナイズ後にトークンフィルタを適用する、組み合わせ可能なテキスト処理パイプラインをサポートしています。フィルタは TokenizerBuilder に追加され、追加された順序で実行されます。

Input Text
  --> Character Filters (preprocessing)
  --> Tokenization
  --> Token Filters (postprocessing)
  --> Output Tokens

文字フィルタ

文字フィルタはトークナイズ前に入力テキストを変換します。

unicode_normalize

入力テキストに Unicode 正規化を適用します。

from lindera import TokenizerBuilder

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("embedded://ipadic")
    .append_character_filter("unicode_normalize", {"kind": "nfkc"})
    .build()
)

サポートされる正規化形式: "nfc"、"nfkc"、"nfd"、"nfkd"。

mapping

マッピングテーブルに従って文字や文字列を置換します。

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("embedded://ipadic")
    .append_character_filter("mapping", {
        "mapping": {
            "\u30fc": "-",
            "\uff5e": "~",
        }
    })
    .build()
)

japanese_iteration_mark

日本語の踊り字（繰り返し記号）を完全な形に展開します。

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("embedded://ipadic")
    .append_character_filter("japanese_iteration_mark", {
        "normalize_kanji": True,
        "normalize_kana": True,
    })
    .build()
)

トークンフィルタ

トークンフィルタはトークナイズ後にトークンを変換または除去します。

lowercase

トークンの表層形を小文字に変換します。

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("embedded://ipadic")
    .append_token_filter("lowercase", {})
    .build()
)

japanese_base_form

辞書の形態素情報を使用して、活用形を基本形（辞書形）に置換します。

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("embedded://ipadic")
    .append_token_filter("japanese_base_form", {})
    .build()
)

japanese_stop_tags

指定されたタグに一致する品詞のトークンを除去します。

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("embedded://ipadic")
    .append_token_filter("japanese_stop_tags", {
        "tags": ["助詞,格助詞,一般", "助詞,係助詞", "助詞,連体化", "助動詞"],
    })
    .build()
)

タグは 4 階層のカンマ区切りに正規化され（不足分は * で補完）、各トークンの先頭 4 つの品詞詳細と完全一致で比較されます。IPADIC の助詞トークンは必ず 助詞,係助詞 のようにサブカテゴリを持つため、助詞 単独では一致しません。一方、助動詞はサブカテゴリを持たないため（助動詞,*,*,*）、助動詞 単独で一致します。

japanese_keep_tags

指定されたタグに一致する品詞のトークンのみを保持します。その他のトークンはすべて除去されます。

tokenizer = (
    TokenizerBuilder()
    .set_dictionary("embedded://ipadic")
    .append_token_filter("japanese_keep_tags", {
        "tags": ["名詞,一般"],
    })
    .build()
)

パイプラインの完全な例

以下の例では、複数の文字フィルタとトークンフィルタを1つのパイプラインに組み合わせています：

from lindera import TokenizerBuilder

tokenizer = (
    TokenizerBuilder()
    .set_mode("normal")
    .set_dictionary("embedded://ipadic")
    # Preprocessing
    .append_character_filter("unicode_normalize", {"kind": "nfkc"})
    .append_character_filter("japanese_iteration_mark", {
        "normalize_kanji": True,
        "normalize_kana": True,
    })
    # Postprocessing
    .append_token_filter("japanese_base_form", {})
    .append_token_filter("japanese_stop_tags", {
        "tags": ["助詞,格助詞,一般", "助詞,係助詞", "助詞,連体化", "助動詞", "記号,句点", "記号,読点"],
    })
    .append_token_filter("lowercase", {})
    .build()
)

tokens = tokenizer.tokenize("Ｌｉｎｄｅｒａは形態素解析を行うライブラリです。")
for token in tokens:
    print(f"{token.surface}\t{','.join(token.details)}")

このパイプラインでは：

1. unicode_normalize が全角文字を半角に変換（NFKC 正規化）
2. japanese_iteration_mark が踊り字を展開
3. japanese_base_form が活用形のトークンを基本形に変換
4. japanese_stop_tags が助詞（格助詞・係助詞・連体化）・助動詞・句読点を除去
5. lowercase がアルファベットを小文字に正規化

学習

Lindera Python は、アノテーション付きコーパスからカスタム CRF ベースの形態素解析モデルを学習する機能をサポートしています。この機能には train feature が必要です。

前提条件

train feature を有効にして lindera-python をビルドします（デフォルトで有効）：

maturin develop --features train

モデルの学習

lindera.train() を使用して、種辞書とアノテーション付きコーパスから CRF モデルを学習します：

import lindera

lindera.train(
    seed="resources/training/seed.csv",
    corpus="resources/training/corpus.txt",
    char_def="resources/training/char.def",
    unk_def="resources/training/unk.def",
    feature_def="resources/training/feature.def",
    rewrite_def="resources/training/rewrite.def",
    output="/tmp/model.dat",
    lambda_=0.01,
    max_iter=100,
    max_threads=4,
)

学習パラメータ

学習済みモデルのエクスポート

学習後、lindera.export() を使用してモデルを辞書ソースファイルにエクスポートします：

import lindera

lindera.export(
    model="/tmp/model.dat",
    output="/tmp/dictionary_source",
    metadata="resources/training/metadata.json",
)

エクスポートパラメータ

エクスポートにより、出力ディレクトリに以下のファイルが作成されます：

• lex.csv -- 学習済みコスト付きのレキシコンエントリー
• matrix.def -- 連接コスト行列
• unk.def -- 未知語定義
• char.def -- 文字カテゴリ定義
• metadata.json -- 更新されたメタデータ（metadata パラメータ指定時）

完全なワークフロー

カスタム辞書の学習と使用の完全なワークフロー：

import lindera

# Step 1: Train the CRF model
lindera.train(
    seed="resources/training/seed.csv",
    corpus="resources/training/corpus.txt",
    char_def="resources/training/char.def",
    unk_def="resources/training/unk.def",
    feature_def="resources/training/feature.def",
    rewrite_def="resources/training/rewrite.def",
    output="/tmp/model.dat",
    lambda_=0.01,
    max_iter=100,
)

# Step 2: Export to dictionary source files
lindera.export(
    model="/tmp/model.dat",
    output="/tmp/dictionary_source",
    metadata="resources/training/metadata.json",
)

# Step 3: Build the dictionary from exported source files
metadata = lindera.Metadata.from_json_file("/tmp/dictionary_source/metadata.json")
lindera.build_dictionary("/tmp/dictionary_source", "/tmp/dictionary", metadata)

# Step 4: Use the trained dictionary
tokenizer = (
    lindera.TokenizerBuilder()
    .set_dictionary("/tmp/dictionary")
    .set_mode("normal")
    .build()
)

tokens = tokenizer.tokenize("形態素解析のテスト")
for token in tokens:
    print(f"{token.surface}\t{','.join(token.details)}")

Lindera Node.js

Lindera Node.js は、NAPI-RS を使用して構築された Lindera 形態素解析エンジンの Node.js バインディングです。Node.js 18 以降をサポートし、Lindera の高性能なトークナイズ機能を Node.js エコシステムに提供します。

特徴

• 多言語対応: 日本語（IPADIC、IPADIC NEologd、UniDic）、韓国語（ko-dic）、中国語（CC-CEDICT、Jieba）のテキストをトークナイズ
• テキスト処理パイプライン: 文字フィルタとトークンフィルタを組み合わせて、柔軟な前処理・後処理が可能
• CRF ベースの辞書学習: アノテーション付きコーパスからカスタム形態素解析モデルを学習（train feature が必要）
• 複数のトークナイズモード: 解析粒度に応じた Normal モードと Decompose モード
• N-best トークナイズ: コスト順にランク付けされた複数のトークナイズ候補を取得
• ユーザー辞書: システム辞書をカスタム語彙で拡張
• TypeScript サポート: 完全な型定義を同梱

ドキュメント

• インストール -- 前提条件、ビルド手順、feature フラグ
• クイックスタート -- 最小限の使用例
• Tokenizer API -- TokenizerBuilder、Tokenizer、Token クラスリファレンス
• 辞書管理 -- 辞書の読み込み、ビルド、管理
• テキスト処理パイプライン -- 文字フィルタとトークンフィルタ
• 学習 -- カスタム CRF モデルの学習と辞書のエクスポート

インストール

npm からのインストール

ビルド済みパッケージが npm で公開予定です：

npm install lindera

[!NOTE] npm パッケージには辞書が含まれていません。下記の辞書の入手を参照してください。 ブラウザ/WASM での利用には lindera-wasm を参照してください。

ソースからのビルド

前提条件

• Node.js 18 以降（LTS バージョン推奨）
• Rust ツールチェーン -- rustup 経由でインストール
• NAPI-RS CLI -- Rust で Node.js ネイティブアドオンをビルドするための CLI ツール

NAPI-RS CLI をグローバルにインストールします：

npm install -g @napi-rs/cli

辞書の入手

Lindera はパッケージに辞書を同梱していません。ビルド済み辞書を別途入手する必要があります。

GitHub Releases からのダウンロード

ビルド済み辞書は GitHub Releases ページから入手できます。辞書アーカイブをダウンロードしてローカルディレクトリに展開してください：

# 例: IPADIC 辞書のダウンロードと展開
curl -LO https://github.com/lindera/lindera/releases/download/<version>/lindera-ipadic-<version>.zip
unzip lindera-ipadic-<version>.zip -d /path/to/ipadic

開発ビルド

lindera-nodejs を開発モードでビルドします：

cd lindera-nodejs
npm install
npm run build

または、プロジェクトの Makefile を使用します：

make nodejs-develop

学習機能付きビルド

train feature を有効にすると、CRF ベースの辞書学習機能が利用可能になります。デフォルトで有効になっています：

npm run build -- --features train

Feature フラグ

複数の feature を組み合わせることができます：

npm run build -- --features "train,embed-ipadic,embed-ko-dic"

[!TIP] 辞書をバイナリに直接埋め込みたい場合（上級者向け）は、対応する embed-* feature フラグを有効にしてビルドし、embedded:// スキームでロードしてください：

const dictionary = loadDictionary("embedded://ipadic");

詳細は Feature フラグ を参照してください。

インストールの確認

インストール後、Node.js で lindera が利用可能であることを確認します：

const lindera = require("lindera");

console.log(lindera.version());

[!NOTE] npm パッケージ lindera の exports マップは types / import / require の各条件を宣言しているため、 CommonJS（require("lindera")）からも ES モジュール（import { TokenizerBuilder } from "lindera"）からも そのまま読み込めます。

最小の ESM の例：

import { TokenizerBuilder } from "lindera";

console.log(typeof TokenizerBuilder); // "function"

クイックスタート

このガイドでは、lindera-nodejs を使用してテキストをトークナイズする方法を紹介します。

基本的なトークナイズ

トークナイザーの作成には TokenizerBuilder の使用を推奨します：

const { TokenizerBuilder } = require("lindera");

const builder = new TokenizerBuilder();
builder.setMode("normal");
builder.setDictionary("/path/to/ipadic");
const tokenizer = builder.build();

const tokens = tokenizer.tokenize("関西国際空港限定トートバッグ");
for (const token of tokens) {
  console.log(`${token.surface}\t${token.details.join(",")}`);
}

注意: ビルド済み辞書を GitHub Releases からダウンロードし、展開したディレクトリのパスを指定してください。

期待される出力：

関西国際空港    名詞,固有名詞,組織,*,*,*,関西国際空港,カンサイコクサイクウコウ,カンサイコクサイクーコー
限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
トートバッグ    名詞,一般,*,*,*,*,*,*,*

メソッドチェーン

すべてのセッターはビルダー自身（this）を返すため、設定をチェーンして記述できます：

const { TokenizerBuilder } = require("lindera");

const tokenizer = new TokenizerBuilder()
  .setMode("normal")
  .setDictionary("/path/to/ipadic")
  .build();

const tokens = tokenizer.tokenize("すもももももももものうち");
for (const token of tokens) {
  console.log(`${token.surface}\t${token.details[0]}`);
}

1 文ずつセッターを呼び出すスタイルもそのまま使えます。どちらのスタイルでも同じビルダーを設定します。

トークンプロパティへのアクセス

各トークンは以下のプロパティを公開しています：

const { TokenizerBuilder } = require("lindera");

const builder = new TokenizerBuilder();
builder.setDictionary("/path/to/ipadic");
const tokenizer = builder.build();

const tokens = tokenizer.tokenize("東京タワー");
for (const token of tokens) {
  console.log(`Surface: ${token.surface}`);
  console.log(`Byte range: ${token.byteStart}..${token.byteEnd}`);
  console.log(`Position: ${token.position}`);
  console.log(`Word ID: ${token.wordId}`);
  console.log(`Unknown: ${token.isUnknown}`);
  console.log(`Details: ${token.details}`);
  console.log();
}

N-best トークナイズ

コスト順にランク付けされた複数のトークナイズ候補を取得します：

const { TokenizerBuilder } = require("lindera");

const builder = new TokenizerBuilder();
builder.setDictionary("/path/to/ipadic");
const tokenizer = builder.build();

const results = tokenizer.tokenizeNbest("すもももももももものうち", 3);
for (const { tokens, cost } of results) {
  const surfaces = tokens.map((t) => t.surface);
  console.log(`Cost ${cost}: ${surfaces.join(" / ")}`);
}

TypeScript

Lindera Node.js には TypeScript の型定義が同梱されています。すべてのクラスと関数に完全な型が付いています。npm パッケージ lindera の exports マップは require / import の両方の条件を宣言しているため、CommonJS からも ES モジュールからもそのまま読み込めます。以下のサンプルは moduleResolution: node16 + strict でコンパイルできることを確認済みです：

import type { Token } from "lindera";
import { TokenizerBuilder } from "lindera";

const builder = new TokenizerBuilder();
builder.setMode("normal");
builder.setDictionary("/path/to/ipadic");
const tokenizer = builder.build();

const tokens: Token[] = tokenizer.tokenize("形態素解析");
for (const token of tokens) {
  console.log(`${token.surface}: ${token.details.join(",")}`);
}

Tokenizer API

TokenizerBuilder

TokenizerBuilder はビルダーパターンを使用して Tokenizer インスタンスを設定・構築します。

コンストラクタ

new TokenizerBuilder()

デフォルト設定で新しいビルダーを作成します。

const { TokenizerBuilder } = require("lindera");

const builder = new TokenizerBuilder();

new TokenizerBuilder().fromFile(filePath)

YAML ファイルから設定を読み込み、新しいビルダーを返します。

const builder = new TokenizerBuilder().fromFile("lindera.yml");

辞書、文字フィルタ、トークンフィルタの設定を含む完全な設定ファイルの例は lindera-nodejs/resources/lindera.yml を参照してください。

設定メソッド

すべてのセッターメソッドはビルダー自身（this）を返すため、メソッドチェーンでも 1 文ずつの呼び出しでも設定できます。

setMode(mode)

トークナイズモードを設定します。

• "normal" -- 標準的なトークナイズ（デフォルト）
• "decompose" -- 複合語をより小さな単位に分解

builder.setMode("normal");

setDictionary(path)

システム辞書のパスまたは URI を設定します。

// 埋め込み辞書を使用
builder.setDictionary("embedded://ipadic");

// 外部辞書を使用
builder.setDictionary("/path/to/dictionary");

setUserDictionary(uri)

ユーザー辞書の URI を設定します。

builder.setUserDictionary("/path/to/user_dictionary");

setKeepWhitespace(keep)

出力に空白トークンを含めるかどうかを制御します。

builder.setKeepWhitespace(true);

appendCharacterFilter(kind, args?)

前処理パイプラインに文字フィルタを追加します。

builder.appendCharacterFilter("unicode_normalize", { kind: "nfkc" });

appendTokenFilter(kind, args?)

後処理パイプラインにトークンフィルタを追加します。

builder.appendTokenFilter("lowercase", {});

ビルド

build()

設定された内容で Tokenizer をビルドして返します。

const tokenizer = builder.build();

Tokenizer

Tokenizer はテキストに対して形態素解析を行います。

Tokenizer の作成

new Tokenizer(dictionary, mode?, userDictionary?)

読み込み済みの辞書から直接トークナイザーを作成します。

const { Tokenizer, loadDictionary } = require("lindera");

const dictionary = loadDictionary("embedded://ipadic");
const tokenizer = new Tokenizer(dictionary, "normal");

Tokenizer メソッド

tokenize(text)

入力テキストをトークナイズし、プレーンなトークンオブジェクトの配列を返します。

const tokens = tokenizer.tokenize("形態素解析");

パラメータ:

戻り値: Token[]

トークンはクラスのインスタンスではなくプレーンな JavaScript オブジェクトです。そのため通常の GC で回収され、JSON.stringify、structuredClone、worker への転送を変換なしで通過します。詳細は Token を参照してください。

tokenizeSurfaces(text)

入力テキストをトークナイズし、トークンの surface のみを文字列の配列として返します。分かち書き用途の高速パスです。トークンオブジェクトを構築せず、形態素の詳細情報もロードしないため、surface 文字列だけが必要な場合は tokenize より大幅に高速です。結果は tokenizer.tokenize(text).map((t) => t.surface) と一致します。

const surfaces = tokenizer.tokenizeSurfaces("形態素解析");
// ["形態素", "解析"]

パラメータ:

戻り値: string[]

tokenizeNbest(text, n, unique?, costThreshold?)

N-best トークナイズ結果を返します。各結果はトークン配列とトータルパスコストを含みます。

const results = tokenizer.tokenizeNbest("すもももももももものうち", 3);
for (const { tokens, cost } of results) {
  console.log(cost, tokens.map((t) => t.surface));
}

パラメータ:

戻り値: NbestResult[]。各 NbestResult は { tokens: Token[], cost: number } です。

Token

Token は単一の形態素トークンを表すプレーンオブジェクトです。クラスではなく TypeScript の interface であり、メソッドもプロトタイプも持ちません。 各フィールドは直接読み出します。

プロパティ

詳細情報の読み出し

details を直接インデックスします。範囲外のインデックスは undefined になります。

const token = tokenizer.tokenize("東京")[0];
const pos = token.details[0];      // 例: "名詞"
const subpos = token.details[1];   // 例: "固有名詞"
const reading = token.details[7];  // 例: "トウキョウ"

details の構造は辞書によって異なります：

• IPADIC: [品詞, 品詞細分類1, 品詞細分類2, 品詞細分類3, 活用型, 活用形, 原形, 読み, 発音]
• UniDic: UniDic 仕様に準拠した詳細な形態素情報
• ko-dic / CC-CEDICT / Jieba: 各辞書固有の詳細フォーマット

Mode と Penalty

Mode と Penalty は npm パッケージ lindera からエクスポートされていますが、現状どの公開 API にも接続されていません： TokenizerBuilder.setMode() / Tokenizer のコンストラクタは 単純なモード文字列（"normal" または "decompose"）のみを受け取り、decompose モードは 内部的に常にデフォルトのペナルティ設定を使用します。これらの型は完全性のためにここで 説明していますが、JavaScript からペナルティの挙動をカスタマイズする用途にはまだ使用できません。

Mode

2つの値を持つ文字列列挙型です：

• Mode.Normal -- 辞書コストに基づく標準的なトークナイズ
• Mode.Decompose -- ペナルティベースの複合語分解

Penalty

decompose モードで使用されるペナルティパラメータを表すオブジェクトです：

辞書管理

Lindera Node.js は、形態素解析で使用する辞書の読み込み、ビルド、管理のための関数を提供します。

辞書の読み込み

システム辞書

loadDictionary(uri) を使用してシステム辞書を読み込みます。GitHub Releases からビルド済み辞書をダウンロードし、展開したディレクトリのパスを指定してください：

const { loadDictionary } = require("lindera");

const dictionary = loadDictionary("/path/to/ipadic");

埋め込み辞書（上級者向け） -- embed-* feature フラグ付きでビルドした場合、埋め込み辞書を使用できます：

const dictionary = loadDictionary("embedded://ipadic");

Dictionary には、読み込んだ辞書のメタデータを参照するための読み取り専用アクセサがいくつか用意されています：

console.log(dictionary.metadataName());     // 例: "ipadic"
console.log(dictionary.metadataEncoding()); // 例: "UTF-8"

const metadata = dictionary.metadata(); // Metadata オブジェクト全体
console.log(metadata.defaultWordCost);

ユーザー辞書

ユーザー辞書はシステム辞書にカスタム語彙を追加します。

const { loadUserDictionary, Metadata } = require("lindera");

const metadata = new Metadata();
const userDict = loadUserDictionary("/path/to/user_dictionary", metadata);

トークナイザーのビルド時にユーザー辞書を渡します：

const { Tokenizer, loadDictionary, loadUserDictionary, Metadata } = require("lindera");

const dictionary = loadDictionary("/path/to/ipadic");
const metadata = new Metadata();
const userDict = loadUserDictionary("/path/to/user_dictionary", metadata);

const tokenizer = new Tokenizer(dictionary, "normal", userDict);

または、ビルダー経由で設定します：

const { TokenizerBuilder } = require("lindera");

const builder = new TokenizerBuilder();
builder.setDictionary("/path/to/ipadic");
builder.setUserDictionary("/path/to/user_dictionary");
const tokenizer = builder.build();

辞書のビルド

システム辞書のビルド

ソースファイルからシステム辞書をビルドします：

const { buildDictionary, Metadata } = require("lindera");

const metadata = new Metadata({ name: "custom", encoding: "UTF-8" });
buildDictionary("/path/to/input_dir", "/path/to/output_dir", metadata);

入力ディレクトリには辞書のソースファイル（CSV レキシコン、matrix.def など）が含まれている必要があります。

ユーザー辞書のビルド

CSV ファイルからユーザー辞書をビルドします：

const { buildUserDictionary, Metadata } = require("lindera");

const metadata = new Metadata();
buildUserDictionary("ipadic", "user_words.csv", "/path/to/output_dir", metadata);

metadata パラメータは省略可能です。省略した場合はデフォルトのメタデータ値が使用されます：

buildUserDictionary("ipadic", "user_words.csv", "/path/to/output_dir");

[!NOTE] 第一引数（kind）は現状未使用です -- 将来の拡張のために予約されており、ビルド結果には 影響しません。現時点では任意の文字列を渡しても問題ありません。

Metadata

Metadata クラスは辞書のパラメータを設定します。

Metadata の作成

const { Metadata } = require("lindera");

// デフォルトのメタデータ
const metadata = new Metadata();

// カスタムメタデータ
const metadata = new Metadata({
  name: "my_dictionary",
  encoding: "UTF-8",
  defaultWordCost: -10000,
});

JSON からの読み込み

const metadata = Metadata.fromJsonFile("metadata.json");

プロパティ

[!NOTE] このバインディングの Metadata オブジェクトには、スキーマ情報（辞書/ユーザー辞書の フィールド構成）は公開されていません -- dictionarySchema / userDictionarySchema プロパティは存在しません。代わりに独立した Schema クラスを使用してください。

すべてのプロパティは取得と設定の両方をサポートしています：

const metadata = new Metadata();
metadata.name = "custom_dict";
metadata.encoding = "EUC-JP";
console.log(metadata.name); // "custom_dict"

toObject()

メタデータのオブジェクト表現を返します：

const metadata = new Metadata({ name: "test" });
console.log(metadata.toObject());

Schema

Schema クラスは辞書エントリーのフィールド構造を定義します。

Schema の作成

const { Schema } = require("lindera");

// デフォルトの IPADIC 互換スキーマ
const schema = Schema.createDefault();

// カスタムスキーマ
const custom = new Schema(["surface", "left_id", "right_id", "cost", "pos", "reading"]);

Schema メソッド

const schema = Schema.createDefault();

console.log(schema.fieldCount());           // 13（IPADIC フォーマット）
console.log(schema.getFieldIndex("pos1"));  // 例: 4
console.log(schema.getAllFields());          // ["surface", "left_id", ...]
console.log(schema.getCustomFields());      // インデックス 4 以降のフィールド

FieldDefinition

FieldType

テキスト処理パイプライン

Lindera Node.js は、トークナイズ前に文字フィルタを適用し、トークナイズ後にトークンフィルタを適用する、組み合わせ可能なテキスト処理パイプラインをサポートしています。フィルタは TokenizerBuilder に追加され、追加された順序で実行されます。

Input Text
  --> Character Filters (preprocessing)
  --> Tokenization
  --> Token Filters (postprocessing)
  --> Output Tokens

[!NOTE] このページではよく使われる一部のフィルタのみを例として紹介しています。これが全リストではありません。 lindera-analysis は合計4種類の文字フィルタと18種類のトークンフィルタを提供しています。全フィルタ（パラメータ・使用例を含む）の 正式なカタログについてはフィルタを参照してください。

文字フィルタ

文字フィルタはトークナイズ前に入力テキストを変換します。

unicode_normalize

入力テキストに Unicode 正規化を適用します。

const { TokenizerBuilder } = require("lindera");

const builder = new TokenizerBuilder();
builder.setDictionary("embedded://ipadic");
builder.appendCharacterFilter("unicode_normalize", { kind: "nfkc" });
const tokenizer = builder.build();

サポートされる正規化形式: "nfc"、"nfkc"、"nfd"、"nfkd"。

mapping

マッピングテーブルに従って文字や文字列を置換します。

const builder = new TokenizerBuilder();
builder.setDictionary("embedded://ipadic");
builder.appendCharacterFilter("mapping", {
  mapping: {
    "\u30fc": "-",
    "\uff5e": "~",
  },
});
const tokenizer = builder.build();

japanese_iteration_mark

日本語の踊り字（繰り返し記号）を完全な形に展開します。

const builder = new TokenizerBuilder();
builder.setDictionary("embedded://ipadic");
builder.appendCharacterFilter("japanese_iteration_mark", {
  normalize_kanji: true,
  normalize_kana: true,
});
const tokenizer = builder.build();

トークンフィルタ

トークンフィルタはトークナイズ後にトークンを変換または除去します。

lowercase

トークンの表層形を小文字に変換します。

const builder = new TokenizerBuilder();
builder.setDictionary("embedded://ipadic");
builder.appendTokenFilter("lowercase", {});
const tokenizer = builder.build();

japanese_base_form

辞書の形態素情報を使用して、活用形を基本形（辞書形）に置換します。

const builder = new TokenizerBuilder();
builder.setDictionary("embedded://ipadic");
builder.appendTokenFilter("japanese_base_form", {});
const tokenizer = builder.build();

japanese_stop_tags

指定されたタグに一致する品詞のトークンを除去します。

const builder = new TokenizerBuilder();
builder.setDictionary("embedded://ipadic");
builder.appendTokenFilter("japanese_stop_tags", {
  tags: ["助詞,格助詞,一般", "助詞,係助詞", "助詞,連体化", "助動詞"],
});
const tokenizer = builder.build();

[!NOTE] タグは 4 階層のカンマ区切りに正規化され（不足分は * で補完）、各トークンの先頭 4 つの品詞詳細と完全一致で比較されます。 IPADIC の助詞トークンは必ず 助詞,係助詞 のようにサブカテゴリを持つため、助詞 単独では一致しません。 一方、助動詞はサブカテゴリを持たないため（助動詞,*,*,*）、助動詞 単独で一致します。

japanese_keep_tags

指定されたタグに一致する品詞のトークンのみを保持します。その他のトークンはすべて除去されます。

const builder = new TokenizerBuilder();
builder.setDictionary("embedded://ipadic");
builder.appendTokenFilter("japanese_keep_tags", {
  tags: ["名詞,一般"],
});
const tokenizer = builder.build();

パイプラインの完全な例

以下の例では、複数の文字フィルタとトークンフィルタを1つのパイプラインに組み合わせています：

const { TokenizerBuilder } = require("lindera");

const builder = new TokenizerBuilder();
builder.setMode("normal");
builder.setDictionary("embedded://ipadic");
// Preprocessing
builder.appendCharacterFilter("unicode_normalize", { kind: "nfkc" });
builder.appendCharacterFilter("japanese_iteration_mark", {
  normalize_kanji: true,
  normalize_kana: true,
});
// Postprocessing
builder.appendTokenFilter("japanese_base_form", {});
builder.appendTokenFilter("japanese_stop_tags", {
  tags: ["助詞,格助詞,一般", "助詞,係助詞", "助詞,連体化", "助動詞", "記号,句点", "記号,読点"],
});
builder.appendTokenFilter("lowercase", {});
const tokenizer = builder.build();

const tokens = tokenizer.tokenize("Ｌｉｎｄｅｒａは形態素解析を行うライブラリです。");
for (const token of tokens) {
  console.log(`${token.surface}\t${token.details.join(",")}`);
}

このパイプラインでは：

1. unicode_normalize が全角文字を半角に変換（NFKC 正規化）
2. japanese_iteration_mark が踊り字を展開
3. japanese_base_form が活用形のトークンを基本形に変換
4. japanese_stop_tags が助詞（格助詞・係助詞・連体化）・助動詞・句読点を除去
5. lowercase がアルファベットを小文字に正規化

学習

Lindera Node.js は、アノテーション付きコーパスからカスタム CRF ベースの形態素解析モデルを学習する機能をサポートしています。この機能には train feature が必要です。

前提条件

train feature を有効にして lindera-nodejs をビルドします（デフォルトで有効）：

npm run build -- --features train

モデルの学習

[!NOTE] 以下で示すファイルパス（resources/training/*.csv、*.def）はあくまで例示用のプレースホルダーであり、 このリポジトリにこれらのファイルが実際に同梱されているわけではありません。種辞書・コーパス・各種定義ファイルを その場で生成し、実際に学習・エクスポート・辞書ビルドまで一気通貫で行う完全な実行可能サンプルは lindera-nodejs/examples/train_and_export.js を参照してください。

train() を使用して、種辞書とアノテーション付きコーパスから CRF モデルを学習します：

const { train } = require("lindera");

train({
  seed: "resources/training/seed.csv",
  corpus: "resources/training/corpus.txt",
  charDef: "resources/training/char.def",
  unkDef: "resources/training/unk.def",
  featureDef: "resources/training/feature.def",
  rewriteDef: "resources/training/rewrite.def",
  output: "/tmp/model.dat",
  lambda: 0.01,
  maxIter: 100,
  maxThreads: 4,
});

学習パラメータ

学習済みモデルのエクスポート

学習後、exportModel() を使用してモデルを辞書ソースファイルにエクスポートします：

const { exportModel } = require("lindera");

exportModel({
  model: "/tmp/model.dat",
  output: "/tmp/dictionary_source",
  metadata: "resources/training/metadata.json",
});

エクスポートパラメータ

エクスポートにより、出力ディレクトリに以下のファイルが作成されます：

• lex.csv -- 学習済みコスト付きのレキシコンエントリー
• matrix.def -- 連接コスト行列
• unk.def -- 未知語定義
• char.def -- 文字カテゴリ定義
• metadata.json -- 更新されたメタデータ（metadata パラメータ指定時）

完全なワークフロー

カスタム辞書の学習と使用の完全なワークフロー：

const {
  train,
  exportModel,
  buildDictionary,
  Metadata,
  TokenizerBuilder,
} = require("lindera");

// Step 1: Train the CRF model
train({
  seed: "resources/training/seed.csv",
  corpus: "resources/training/corpus.txt",
  charDef: "resources/training/char.def",
  unkDef: "resources/training/unk.def",
  featureDef: "resources/training/feature.def",
  rewriteDef: "resources/training/rewrite.def",
  output: "/tmp/model.dat",
  lambda: 0.01,
  maxIter: 100,
});

// Step 2: Export to dictionary source files
exportModel({
  model: "/tmp/model.dat",
  output: "/tmp/dictionary_source",
  metadata: "resources/training/metadata.json",
});

// Step 3: Build the dictionary from exported source files
const metadata = Metadata.fromJsonFile("/tmp/dictionary_source/metadata.json");
buildDictionary("/tmp/dictionary_source", "/tmp/dictionary", metadata);

// Step 4: Use the trained dictionary
const builder = new TokenizerBuilder();
builder.setDictionary("/tmp/dictionary");
builder.setMode("normal");
const tokenizer = builder.build();

const tokens = tokenizer.tokenize("形態素解析のテスト");
for (const token of tokens) {
  console.log(`${token.surface}\t${token.details.join(",")}`);
}

Lindera Ruby

Lindera Ruby は、Magnus と rb-sys を使用して構築された Lindera 形態素解析エンジンの Ruby バインディングです。Ruby 3.1 以降をサポートし、Lindera の高性能なトークナイズ機能を Ruby エコシステムに提供します。

特徴

• 多言語対応: 日本語（IPADIC、IPADIC NEologd、UniDic）、韓国語（ko-dic）、中国語（CC-CEDICT、Jieba）のテキストをトークナイズ
• テキスト処理パイプライン: 文字フィルタとトークンフィルタを組み合わせて、柔軟な前処理・後処理が可能
• CRF ベースの辞書学習: アノテーション付きコーパスからカスタム形態素解析モデルを学習（train feature が必要）
• 複数のトークナイズモード: 解析粒度に応じた Normal モードと Decompose モード
• N-best トークナイズ: コスト順にランク付けされた複数のトークナイズ候補を取得
• ユーザー辞書: システム辞書をカスタム語彙で拡張

ドキュメント

• インストール -- 前提条件、ビルド手順、feature フラグ
• クイックスタート -- 最小限の使用例
• Tokenizer API -- TokenizerBuilder、Tokenizer、Token クラスリファレンス
• 辞書管理 -- 辞書の読み込み、ビルド、管理
• テキスト処理パイプライン -- 文字フィルタとトークンフィルタ
• 学習 -- カスタム CRF モデルの学習と辞書のエクスポート

インストール

[!NOTE] lindera-ruby はまだ RubyGems に公開されていません。ソースからビルドする必要があります。

前提条件

• Ruby 3.1 以降
• Rust ツールチェーン -- rustup 経由でインストール
• Bundler -- Ruby の依存関係管理ツール（gem install bundler）

辞書の入手

Lindera はパッケージに辞書を同梱していません。ビルド済み辞書を別途入手する必要があります。

GitHub Releases からのダウンロード

ビルド済み辞書は GitHub Releases ページから入手できます。辞書アーカイブをダウンロードしてローカルディレクトリに展開してください：

# 例: IPADIC 辞書のダウンロードと展開
curl -LO https://github.com/lindera/lindera/releases/download/<version>/lindera-ipadic-<version>.zip
unzip lindera-ipadic-<version>.zip -d /path/to/ipadic

開発ビルド

lindera-ruby を開発モードでビルドしてインストールします：

cd lindera-ruby
bundle install
bundle exec rake compile

または、プロジェクトの Makefile を使用します：

make build-lindera-ruby

make test-lindera-ruby を実行すると、Rust のユニットテストと Ruby の minitest スイートの両方が実行されます。

学習機能付きビルド

train feature は、CRF ベースの辞書学習機能を有効にします。デフォルトで有効です：

LINDERA_FEATURES="train" bundle exec rake compile

Feature フラグ

Feature は環境変数 LINDERA_FEATURES にカンマ区切りリストで指定します。

複数の feature を組み合わせることができます：

LINDERA_FEATURES="train,embed-ipadic,embed-ko-dic" bundle exec rake compile

[!TIP] 辞書をバイナリに直接埋め込みたい場合（上級者向け）は、対応する embed-* feature フラグを有効にしてビルドし、embedded:// スキームでロードしてください：

dictionary = Lindera.load_dictionary("embedded://ipadic")

詳細は Feature フラグ を参照してください。

インストールの確認

インストール後、Ruby で lindera が利用可能であることを確認します：

require 'lindera'

puts Lindera.version

クイックスタート

このガイドでは、lindera-ruby を使用してテキストをトークナイズする方法を紹介します。

基本的なトークナイズ

トークナイザーの作成には Lindera::TokenizerBuilder の使用を推奨します：

require 'lindera'

builder = Lindera::TokenizerBuilder.new
builder.set_mode('normal')
builder.set_dictionary('/path/to/ipadic')
tokenizer = builder.build

tokens = tokenizer.tokenize('関西国際空港限定トートバッグ')
tokens.each do |token|
  puts "#{token.surface}\t#{token.details.join(',')}"
end

注意: ビルド済み辞書を GitHub Releases からダウンロードし、展開したディレクトリのパスを指定してください。

期待される出力：

関西国際空港    名詞,固有名詞,組織,*,*,*,関西国際空港,カンサイコクサイクウコウ,カンサイコクサイクーコー
限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
トートバッグ    名詞,一般,*,*,*,*,*,*,*

逐次的な設定

TokenizerBuilder は逐次的なメソッド呼び出しで設定します：

require 'lindera'

builder = Lindera::TokenizerBuilder.new
builder.set_mode('normal')
builder.set_dictionary('/path/to/ipadic')
tokenizer = builder.build

tokens = tokenizer.tokenize('すもももももももものうち')
tokens.each do |token|
  puts "#{token.surface}\t#{token.get_detail(0)}"
end

トークンプロパティへのアクセス

各トークンは以下のプロパティを公開しています：

require 'lindera'

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('/path/to/ipadic')
tokenizer = builder.build

tokens = tokenizer.tokenize('東京タワー')

tokens.each do |token|
  puts "Surface: #{token.surface}"
  puts "Byte range: #{token.byte_start}..#{token.byte_end}"
  puts "Position: #{token.position}"
  puts "Word ID: #{token.word_id}"
  puts "Unknown: #{token.unknown?}"
  puts "Details: #{token.details}"
  puts
end

N-best トークナイズ

コスト順にランク付けされた複数のトークナイズ候補を取得します：

require 'lindera'

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('/path/to/ipadic')
tokenizer = builder.build

results = tokenizer.tokenize_nbest('すもももももももものうち', 3, false, nil)

results.each do |tokens, cost|
  surfaces = tokens.map(&:surface)
  puts "Cost #{cost}: #{surfaces.join(' / ')}"
end

Tokenizer API

TokenizerBuilder

Lindera::TokenizerBuilder はビルダーパターンを使用して Tokenizer インスタンスを設定・構築します。

コンストラクタ

Lindera::TokenizerBuilder.new

デフォルト設定で新しいビルダーを作成します。

require 'lindera'

builder = Lindera::TokenizerBuilder.new

Lindera::TokenizerBuilder.from_file(file_path)

JSON ファイルから設定を読み込み、新しいビルダーを返します。これはクラスメソッドであり、既存のインスタンスに対してチェーンするものではありません。

builder = Lindera::TokenizerBuilder.from_file('config.json')

設定メソッド

set_mode(mode)

トークナイズモードを設定します。

• "normal" -- 標準的なトークナイズ（デフォルト）
• "decompose" -- 複合語をより小さな単位に分解

builder.set_mode('normal')

set_dictionary(path)

システム辞書のパスまたは URI を設定します。

# 埋め込み辞書を使用
builder.set_dictionary('embedded://ipadic')

# 外部辞書を使用
builder.set_dictionary('/path/to/dictionary')

set_user_dictionary(uri)

ユーザー辞書の URI を設定します。

builder.set_user_dictionary('/path/to/user_dictionary')

set_keep_whitespace(keep)

出力に空白トークンを含めるかどうかを制御します。

builder.set_keep_whitespace(true)

append_character_filter(kind, args)

前処理パイプラインに文字フィルタを追加します。

builder.append_character_filter('unicode_normalize', { 'kind' => 'nfkc' })

append_token_filter(kind, args)

後処理パイプラインにトークンフィルタを追加します。args が不要な場合は nil を渡します。

builder.append_token_filter('lowercase', nil)

ビルド

build

設定された内容で Tokenizer をビルドして返します。

tokenizer = builder.build

Tokenizer

Lindera::Tokenizer はテキストに対して形態素解析を行います。

Tokenizer の作成

Lindera::Tokenizer.new(dictionary, mode, user_dictionary)

読み込み済みの辞書から直接トークナイザーを作成します。user_dictionary が不要な場合は nil を渡します。

require 'lindera'

dictionary = Lindera.load_dictionary('embedded://ipadic')
tokenizer = Lindera::Tokenizer.new(dictionary, 'normal', nil)

ユーザー辞書を使用する場合：

dictionary = Lindera.load_dictionary('embedded://ipadic')
metadata = dictionary.metadata
user_dict = Lindera.load_user_dictionary('/path/to/user_dictionary', metadata)
tokenizer = Lindera::Tokenizer.new(dictionary, 'normal', user_dict)

Tokenizer メソッド

tokenize(text)

入力テキストをトークナイズし、Token オブジェクトの配列を返します。

tokens = tokenizer.tokenize('形態素解析')

パラメータ:

戻り値: Array<Token>

tokenize_surfaces(text)

入力テキストをトークナイズし、トークンの surface のみを文字列の配列として返します。分かち書き用途の高速パスです。Token オブジェクトを生成せず、形態素の詳細情報もロードしないため、surface 文字列だけが必要な場合は tokenize より大幅に高速です。結果は tokenizer.tokenize(text).map(&:surface) と一致します。

surfaces = tokenizer.tokenize_surfaces('形態素解析')
# ["形態素", "解析"]

パラメータ:

戻り値: Array<String>

tokenize_nbest(text, n, unique, cost_threshold)

N-best トークナイズ結果を返します。各結果はトータルパスコストとペアになっています。

results = tokenizer.tokenize_nbest('すもももももももものうち', 3, false, nil)
results.each do |tokens, cost|
  puts "#{cost}: #{tokens.map(&:surface).join(' / ')}"
end

パラメータ:

戻り値: Array<[Array<Token>, Integer]>

Mode

Lindera::Mode はトークナイズモードを表します。モードの確認・比較のためのスタンドアロンヘルパーとして提供されています。TokenizerBuilder#set_mode と Tokenizer.new は現在、Mode インスタンスではなく単純なモード文字列（"normal" または "decompose"）のみを受け付けます（下記の Penalty の制限事項も参照してください）。

Mode の作成

Lindera::Mode.new(mode_str)

Mode を作成します。引数は必須ですが nil を渡すこともできます。"normal" / "Normal"（mode_str が nil の場合に使用）または "decompose" / "Decompose" を受け付けます。それ以外の値を渡すと ArgumentError が発生します。

require 'lindera'

mode = Lindera::Mode.new('normal')
mode = Lindera::Mode.new('decompose')
mode = Lindera::Mode.new(nil)  # デフォルトの "normal" になる

Mode メソッド

mode = Lindera::Mode.new('decompose')
mode.to_s        # "decompose"
mode.normal?      # false
mode.decompose?   # true

Penalty

Lindera::Penalty は "decompose" モードのセグメンテーションで使用される、長さに基づくペナルティのしきい値を設定します。

Penalty の作成

Lindera::Penalty.new(kanji_penalty_length_threshold, kanji_penalty_length_penalty, other_penalty_length_threshold, other_penalty_length_penalty)

4つの位置引数はすべて必須ですが、それぞれ nil を渡すとデフォルト値（下記参照）にフォールバックします。

require 'lindera'

penalty = Lindera::Penalty.new(2, 3000, 7, 1700)
penalty = Lindera::Penalty.new(nil, nil, nil, nil)  # すべてデフォルト値を使用

Penalty プロパティ

すべてのプロパティは読み取り専用です（setter メソッドはありません）：

penalty = Lindera::Penalty.new(nil, nil, nil, nil)
penalty.kanji_penalty_length_threshold  # 2

現在の制限: 現時点では Penalty を Tokenizer や TokenizerBuilder に渡す方法はありません。set_mode と Tokenizer.new は単純なモード文字列のみを受け付け、内部的に "decompose" モードは常に Penalty のデフォルト値を使用します -- カスタムの Penalty インスタンスを作成しても、現時点ではトークナイズには反映されません。

Token

Token は単一の形態素トークンを表します。

プロパティ

さらに、述語メソッド unknown? は辞書に登録されていない単語の場合 true を返します：

token.unknown?  # => false

Token メソッド

get_detail(index)

指定されたインデックスの詳細文字列を返します。インデックスが範囲外の場合は nil を返します。

token = tokenizer.tokenize('東京')[0]
pos = token.get_detail(0)        # 例: "名詞"
subpos = token.get_detail(1)     # 例: "固有名詞"
reading = token.get_detail(7)    # 例: "トウキョウ"

パラメータ:

戻り値: String または nil

to_h / to_hash

トークンを Symbol をキーとするプレーンな Hash として返します。各フィールドは Ruby の自然な型を保つため、独自のエンコーダなしでシリアライズできます。 to_h と to_hash は同一のメソッドです。

require 'json'

data = tokenizer.tokenize('東京')[0].to_h
# {surface: "東京", byte_start: 0, byte_end: 6, position: 0,
#  word_id: 12345, is_unknown: false, details: [...]}

JSON.generate(tokens.map(&:to_h))

戻り値: :surface、:byte_start、:byte_end、:position、:word_id、 :is_unknown、:details をキーに持つ Hash。

details の構造は辞書によって異なります：

• IPADIC: [品詞, 品詞細分類1, 品詞細分類2, 品詞細分類3, 活用型, 活用形, 原形, 読み, 発音]
• UniDic: UniDic 仕様に準拠した詳細な形態素情報
• ko-dic / CC-CEDICT / Jieba: 各辞書固有の詳細フォーマット

Schema

Lindera::Schema はフィールド名の順序付きリストを保持し、フィールド名とインデックスの間の相互変換を提供します。Metadata#dictionary_schema と Metadata#user_dictionary_schema で使用されます（辞書管理 を参照）。

Schema の作成

Lindera::Schema.new(fields)

フィールド名の配列からスキーマを作成します。

require 'lindera'

schema = Lindera::Schema.new(%w[
  surface
  left_context_id
  right_context_id
  cost
  major_pos
  reading
])

Lindera::Schema.create_default

組み込みのデフォルトスキーマを返します。IPADIC 形式に対応する13フィールド（surface、left_context_id、right_context_id、cost、major_pos、pos_detail_1、pos_detail_2、pos_detail_3、conjugation_type、conjugation_form、base_form、reading、pronunciation）です。

schema = Lindera::Schema.create_default

Schema メソッド

schema = Lindera::Schema.create_default

schema.field_count                  # 13
schema.get_field_index('cost')      # 3
schema.get_field_name(0)            # "surface"
schema.get_custom_fields            # ["major_pos", "pos_detail_1", ..., "pronunciation"]

field = schema.get_field_by_name('surface')
puts "#{field.index} #{field.name} #{field.field_type}"  # 0 surface surface

schema.validate_record([
  '東京', '1288', '1288', '100',
  '名詞', '固有名詞', '地域', '一般', '*', '*',
  '東京', 'トウキョウ', 'トーキョー'
])

FieldDefinition

Lindera::FieldDefinition は Schema 内の単一フィールドを表します。インスタンスは Schema#get_field_by_name からのみ取得でき、公開コンストラクタはありません（Lindera::FieldDefinition.new は TypeError を発生させます）。

FieldDefinition プロパティ

schema = Lindera::Schema.create_default
field = schema.get_field_by_name('surface')

field.index         # 0
field.name          # "surface"
field.field_type    # #<Lindera::FieldType: surface>
field.description    # nil（デフォルトスキーマでは説明は設定されていない）

FieldType

Lindera::FieldType はフィールドの種別を列挙します。FieldDefinition と同様、インスタンスは Schema（FieldDefinition#field_type 経由）からのみ取得でき、公開コンストラクタはありません。

to_s（および inspect）は次のいずれかを返します：

• "surface" -- 表層形（単語のテキスト）
• "left_context_id" -- 左文脈 ID
• "right_context_id" -- 右文脈 ID
• "cost" -- 単語コスト
• "custom" -- その他の辞書固有フィールド

field = Lindera::Schema.create_default.get_field_by_name('surface')
field.field_type.to_s  # "surface"

辞書管理

Lindera Ruby は、形態素解析で使用する辞書の読み込み、ビルド、管理のためのメソッドを提供します。

辞書の読み込み

システム辞書

Lindera.load_dictionary(uri) を使用してシステム辞書を読み込みます。GitHub Releases からビルド済み辞書をダウンロードし、展開したディレクトリのパスを指定してください：

require 'lindera'

dictionary = Lindera.load_dictionary('/path/to/ipadic')

埋め込み辞書（上級者向け） -- embed-* feature フラグ付きでビルドした場合、埋め込み辞書を使用できます：

dictionary = Lindera.load_dictionary('embedded://ipadic')

ユーザー辞書

ユーザー辞書はシステム辞書にカスタム語彙を追加します。

require 'lindera'

dictionary = Lindera.load_dictionary('/path/to/ipadic')
metadata = dictionary.metadata
user_dict = Lindera.load_user_dictionary('/path/to/user_dictionary', metadata)

トークナイザーの作成時にユーザー辞書を渡します：

require 'lindera'

dictionary = Lindera.load_dictionary('/path/to/ipadic')
metadata = dictionary.metadata
user_dict = Lindera.load_user_dictionary('/path/to/user_dictionary', metadata)

tokenizer = Lindera::Tokenizer.new(dictionary, 'normal', user_dict)

または、ビルダー経由で設定します：

require 'lindera'

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('/path/to/ipadic')
builder.set_user_dictionary('/path/to/user_dictionary')
tokenizer = builder.build

辞書のビルド

システム辞書のビルド

ソースファイルからシステム辞書をビルドします：

require 'lindera'

metadata = Lindera::Metadata.from_json_file('metadata.json')
Lindera.build_dictionary('/path/to/input_dir', '/path/to/output_dir', metadata)

入力ディレクトリには辞書のソースファイル（CSV レキシコン、matrix.def など）が含まれている必要があります。

ユーザー辞書のビルド

CSV ファイルからユーザー辞書をビルドします：

require 'lindera'

metadata = Lindera::Metadata.from_json_file('metadata.json')
Lindera.build_user_dictionary('ipadic', 'user_words.csv', '/path/to/output_dir', metadata)

metadata パラメータは省略可能です。省略した場合はデフォルトのメタデータ値が使用されます：

Lindera.build_user_dictionary('ipadic', 'user_words.csv', '/path/to/output_dir', nil)

[!NOTE] 第一引数（kind、上の例では 'ipadic'）は現時点では未使用です -- 将来の利用のために予約 されているだけで、ビルドには影響しません。現時点では任意の文字列を渡すことができます。

Metadata

Lindera::Metadata クラスは辞書のパラメータを設定します。

Metadata の作成

require 'lindera'

# 標準設定でデフォルトのメタデータを作成
metadata = Lindera::Metadata.create_default

Lindera::Metadata.new は9つのプロパティすべてを必須の位置引数として受け取ります （それぞれ nil を渡すとデフォルト値にフォールバックします）。特定の値を上書きしたい 場合にのみ使用してください：

metadata = Lindera::Metadata.new(
  'my_dict', # name
  'UTF-8',   # encoding
  -10_000,   # default_word_cost
  1288,      # default_left_context_id
  1288,      # default_right_context_id
  '*',       # default_field_value
  false,     # flexible_csv
  false,     # skip_invalid_cost_or_id
  false      # normalize_details
)

JSON ファイルからの読み込み

metadata = Lindera::Metadata.from_json_file('metadata.json')

辞書からのメタデータ取得

読み込み済みの辞書からメタデータを取得できます：

dictionary = Lindera.load_dictionary('/path/to/ipadic')
metadata = dictionary.metadata

プロパティ

テキスト処理パイプライン

Lindera Ruby は、トークナイズ前に文字フィルタを適用し、トークナイズ後にトークンフィルタを適用する、組み合わせ可能なテキスト処理パイプラインをサポートしています。フィルタは Lindera::TokenizerBuilder に追加され、追加された順序で実行されます。

Input Text
  --> Character Filters (preprocessing)
  --> Tokenization
  --> Token Filters (postprocessing)
  --> Output Tokens

[!NOTE] このページではよく使われる一部のフィルタのみを例として紹介しています。これが全リストではありません。 lindera-analysis は合計4種類の文字フィルタと18種類のトークンフィルタを提供しています。全フィルタ（パラメータ・使用例を含む）の 正式なカタログについてはフィルタを参照してください。

文字フィルタ

文字フィルタはトークナイズ前に入力テキストを変換します。

unicode_normalize

入力テキストに Unicode 正規化を適用します。

require 'lindera'

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_character_filter('unicode_normalize', { 'kind' => 'nfkc' })
tokenizer = builder.build

サポートされる正規化形式: "nfc"、"nfkc"、"nfd"、"nfkd"。

mapping

マッピングテーブルに従って文字や文字列を置換します。

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_character_filter('mapping', {
  'mapping' => {
    "\u30fc" => '-',
    "\uff5e" => '~'
  }
})
tokenizer = builder.build

japanese_iteration_mark

日本語の踊り字（繰り返し記号）を完全な形に展開します。

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_character_filter('japanese_iteration_mark', {
  'normalize_kanji' => true,
  'normalize_kana' => true
})
tokenizer = builder.build

トークンフィルタ

トークンフィルタはトークナイズ後にトークンを変換または除去します。

lowercase

トークンの表層形を小文字に変換します。

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_token_filter('lowercase', nil)
tokenizer = builder.build

japanese_base_form

辞書の形態素情報を使用して、活用形を基本形（辞書形）に置換します。

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_token_filter('japanese_base_form', nil)
tokenizer = builder.build

japanese_stop_tags

指定されたタグに一致する品詞のトークンを除去します。

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_token_filter('japanese_stop_tags', {
  'tags' => ['助詞,格助詞,一般', '助詞,係助詞', '助詞,連体化', '助動詞']
})
tokenizer = builder.build

[!NOTE] タグは 4 階層のカンマ区切りに正規化され（不足分は * で補完）、各トークンの先頭 4 つの品詞詳細と完全一致で比較されます。 IPADIC の助詞トークンは必ず 助詞,係助詞 のようにサブカテゴリを持つため、助詞 単独では一致しません。 一方、助動詞はサブカテゴリを持たないため（助動詞,*,*,*）、助動詞 単独で一致します。

japanese_keep_tags

指定されたタグに一致する品詞のトークンのみを保持します。その他のトークンはすべて除去されます。

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_token_filter('japanese_keep_tags', {
  'tags' => ['名詞,一般']
})
tokenizer = builder.build

japanese_katakana_stem

カタカナ語の末尾にある長音記号を除去します。最小文字数を指定できます。

builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('embedded://ipadic')
builder.append_token_filter('japanese_katakana_stem', { 'min' => 3 })
tokenizer = builder.build

パイプラインの完全な例

以下の例では、複数の文字フィルタとトークンフィルタを1つのパイプラインに組み合わせています：

require 'lindera'

builder = Lindera::TokenizerBuilder.new
builder.set_mode('normal')
builder.set_dictionary('embedded://ipadic')

# Preprocessing
builder.append_character_filter('unicode_normalize', { 'kind' => 'nfkc' })
builder.append_character_filter('japanese_iteration_mark', {
  'normalize_kanji' => true,
  'normalize_kana' => true
})

# Postprocessing
builder.append_token_filter('japanese_base_form', nil)
builder.append_token_filter('japanese_stop_tags', {
  'tags' => ['助詞,格助詞,一般', '助詞,係助詞', '助詞,連体化', '助動詞', '記号,句点', '記号,読点']
})
builder.append_token_filter('lowercase', nil)

tokenizer = builder.build

tokens = tokenizer.tokenize('Ｌｉｎｄｅｒａは形態素解析を行うライブラリです。')
tokens.each do |token|
  puts "#{token.surface}\t#{token.details.join(',')}"
end

このパイプラインでは：

1. unicode_normalize が全角文字を半角に変換（NFKC 正規化）
2. japanese_iteration_mark が踊り字を展開
3. japanese_base_form が活用形のトークンを基本形に変換
4. japanese_stop_tags が助詞（格助詞・係助詞・連体化）・助動詞・句読点を除去
5. lowercase がアルファベットを小文字に正規化

学習

Lindera Ruby は、アノテーション付きコーパスからカスタム CRF ベースの形態素解析モデルを学習する機能をサポートしています。この機能には train feature が必要です。

前提条件

train feature を有効にして lindera-ruby をビルドします：

LINDERA_FEATURES="embed-ipadic,train" bundle exec rake compile

モデルの学習

Lindera.train を使用して、種辞書とアノテーション付きコーパスから CRF モデルを学習します：

require 'lindera'

Lindera.train(
  'resources/training/seed.csv',
  'resources/training/corpus.txt',
  'resources/training/char.def',
  'resources/training/unk.def',
  'resources/training/feature.def',
  'resources/training/rewrite.def',
  '/tmp/model.dat',
  0.01,   # lambda (L1 regularization)
  100,    # max_iter
  nil     # max_threads (nil = auto-detect)
)

学習パラメータ

Lindera.train の引数は位置引数として順番に渡します：

学習済みモデルのエクスポート

学習後、Lindera.export を使用してモデルを辞書ソースファイルにエクスポートします：

require 'lindera'

Lindera.export('/tmp/model.dat', '/tmp/dictionary_source', 'resources/training/metadata.json')

エクスポートパラメータ

エクスポートにより、出力ディレクトリに以下のファイルが作成されます：

• lex.csv -- 学習済みコスト付きのレキシコンエントリー
• matrix.def -- 連接コスト行列
• unk.def -- 未知語定義
• char.def -- 文字カテゴリ定義
• metadata.json -- 更新されたメタデータ（metadata パラメータ指定時）

完全なワークフロー

カスタム辞書の学習と使用の完全なワークフロー：

require 'lindera'

# Step 1: Train the CRF model
Lindera.train(
  'resources/training/seed.csv',
  'resources/training/corpus.txt',
  'resources/training/char.def',
  'resources/training/unk.def',
  'resources/training/feature.def',
  'resources/training/rewrite.def',
  '/tmp/model.dat',
  0.01,  # lambda
  100,   # max_iter
  nil    # max_threads
)

# Step 2: Export to dictionary source files
Lindera.export('/tmp/model.dat', '/tmp/dictionary_source', 'resources/training/metadata.json')

# Step 3: Build the dictionary from exported source files
metadata = Lindera::Metadata.from_json_file('/tmp/dictionary_source/metadata.json')
Lindera.build_dictionary('/tmp/dictionary_source', '/tmp/dictionary', metadata)

# Step 4: Use the trained dictionary
builder = Lindera::TokenizerBuilder.new
builder.set_dictionary('/tmp/dictionary')
builder.set_mode('normal')
tokenizer = builder.build

tokens = tokenizer.tokenize('形態素解析のテスト')
tokens.each do |token|
  puts "#{token.surface}\t#{token.details.join(',')}"
end

Lindera PHP

Lindera PHP は、ext-php-rs を使用して構築された Lindera 形態素解析エンジンの PHP バインディングです。PHP 8.1 以降をサポートし、Lindera の高性能なトークナイズ機能を PHP エコシステムに提供します。

特徴

• 多言語対応: 日本語（IPADIC、IPADIC NEologd、UniDic）、韓国語（ko-dic）、中国語（CC-CEDICT、Jieba）のテキストをトークナイズ
• テキスト処理パイプライン: 文字フィルタとトークンフィルタを組み合わせて、柔軟な前処理・後処理が可能
• CRF ベースの辞書学習: アノテーション付きコーパスからカスタム形態素解析モデルを学習（train feature が必要）
• 複数のトークナイズモード: 解析粒度に応じた Normal モードと Decompose モード
• N-best トークナイズ: コスト順にランク付けされた複数のトークナイズ候補を取得
• ユーザー辞書: システム辞書をカスタム語彙で拡張

ドキュメント

• インストール -- 前提条件、ビルド手順、feature フラグ
• クイックスタート -- 最小限の使用例
• トークナイザー API -- TokenizerBuilder、Tokenizer、Token クラスリファレンス
• 辞書管理 -- 辞書の読み込み、ビルド、管理
• テキスト処理パイプライン -- 文字フィルタとトークンフィルタ
• 学習 -- カスタム CRF モデルの学習と辞書のエクスポート

インストール

[!NOTE] lindera-php はまだ Packagist に公開されていません。ソースからビルドする必要があります。

前提条件

• PHP 8.1 以降
• Rust ツールチェーン -- rustup 経由でインストール
• Composer -- PHP の依存関係管理（テスト実行時に必要）

辞書の入手

Lindera はパッケージに辞書を同梱していません。ビルド済み辞書を別途入手する必要があります。

GitHub Releases からのダウンロード

ビルド済み辞書は GitHub Releases ページから入手できます。辞書アーカイブをダウンロードしてローカルディレクトリに展開してください：

# 例: IPADIC 辞書のダウンロードと展開
curl -LO https://github.com/lindera/lindera/releases/download/<version>/lindera-ipadic-<version>.zip
unzip lindera-ipadic-<version>.zip -d /path/to/ipadic

ビルド

lindera-php をビルドします：

cargo build -p lindera-php

または、プロジェクトの Makefile を使用します：

make build-lindera-php

学習機能付きビルド

train feature を有効にすると、CRF ベースの辞書学習機能が利用可能になります。デフォルトで有効になっています：

cargo build -p lindera-php --features train

PHP 拡張の読み込み

ビルド後、-d extension= オプションでビルドされた共有ライブラリを指定して PHP を実行します：

php -d extension=target/debug/liblindera_php.so script.php

リリースビルドの場合：

cargo build -p lindera-php --release
php -d extension=target/release/liblindera_php.so script.php

Feature フラグ

複数の feature を組み合わせることができます：

cargo build -p lindera-php --features "train,embed-ipadic,embed-ko-dic"

[!TIP] 辞書をバイナリに直接埋め込みたい場合（上級者向け）は、対応する embed-* feature フラグを有効にしてビルドし、embedded:// スキームでロードしてください：

$dictionary = Lindera\Dictionary::load('embedded://ipadic');

詳細は Feature フラグ を参照してください。

インストールの確認

インストール後、PHP で lindera が利用可能であることを確認します：

<?php

$version = Lindera\Dictionary::version();
echo "Lindera version: {$version}\n";

実行方法：

php -d extension=target/debug/liblindera_php.so script.php

クイックスタート

このガイドでは、lindera-php を使用してテキストをトークナイズする方法を紹介します。

基本的なトークナイズ

辞書を読み込み、トークナイザーを作成してテキストをトークナイズします：

<?php

// Load the dictionary
$dictionary = Lindera\Dictionary::load('/path/to/ipadic');

// Create a tokenizer
$tokenizer = new Lindera\Tokenizer($dictionary, 'normal');

// Tokenize the text
$tokens = $tokenizer->tokenize('関西国際空港限定トートバッグ');
foreach ($tokens as $token) {
    echo $token->surface . "\t" . implode(',', $token->details) . "\n";
}

注意: ビルド済み辞書を GitHub Releases からダウンロードし、展開したディレクトリのパスを指定してください。

期待される出力：

関西国際空港    名詞,固有名詞,組織,*,*,*,関西国際空港,カンサイコクサイクウコウ,カンサイコクサイクーコー
限定    名詞,サ変接続,*,*,*,*,限定,ゲンテイ,ゲンテイ
トートバッグ    名詞,一般,*,*,*,*,*,*,*

TokenizerBuilder の使用

TokenizerBuilder を使用すると、より柔軟にトークナイザーを設定できます：

<?php

$builder = new Lindera\TokenizerBuilder();
$builder->setMode('normal');
$builder->setDictionary('/path/to/ipadic');
$tokenizer = $builder->build();

$tokens = $tokenizer->tokenize('すもももももももものうち');
foreach ($tokens as $token) {
    echo $token->surface . "\t" . $token->getDetail(0) . "\n";
}

トークンプロパティへのアクセス

各トークンは以下のプロパティを公開しています：

<?php

$dictionary = Lindera\Dictionary::load('/path/to/ipadic');
$tokenizer = new Lindera\Tokenizer($dictionary, 'normal');
$tokens = $tokenizer->tokenize('東京タワー');

foreach ($tokens as $token) {
    echo "Surface: {$token->surface}\n";
    echo "Byte range: {$token->byte_start}..{$token->byte_end}\n";
    echo "Position: {$token->position}\n";
    echo "Word ID: {$token->word_id}\n";
    echo "Unknown: " . ($token->is_unknown ? 'true' : 'false') . "\n";
    echo "Details: " . implode(',', $token->details) . "\n";
    echo "\n";
}

N-best トークナイズ

コスト順にランク付けされた複数のトークナイズ候補を取得します：

<?php

$builder = new Lindera\TokenizerBuilder();
$builder->setDictionary('/path/to/ipadic');
$tokenizer = $builder->build();

$results = $tokenizer->tokenizeNbest('東京都', 3);
foreach ($results as $result) {
    $surfaces = array_map(fn($t) => $t->surface, $result->tokens);
    echo "Cost {$result->cost}: " . implode(' / ', $surfaces) . "\n";
}

Decompose モード

Decompose モードでは、複合語をより小さな単位に分解します：

<?php

$dictionary = Lindera\Dictionary::load('/path/to/ipadic');
$tokenizer = new Lindera\Tokenizer($dictionary, 'decompose');

$tokens = $tokenizer->tokenize('関西国際空港限定トートバッグ');
foreach ($tokens as $token) {
    echo $token->surface . "\n";
}

トークナイザー API

TokenizerBuilder

TokenizerBuilder はビルダーパターンを使用して Tokenizer インスタンスを設定・構築します。

コンストラクタ

new Lindera\TokenizerBuilder()

デフォルト設定で新しいビルダーを作成します。

<?php

$builder = new Lindera\TokenizerBuilder();

設定メソッド

setMode($mode)

トークナイズモードを設定します。

• "normal" -- 標準的なトークナイズ（デフォルト）
• "decompose" -- 複合語をより小さな単位に分解

$builder->setMode('normal');

setDictionary($uri)

システム辞書のパスまたは URI を設定します。

// 埋め込み辞書を使用
$builder->setDictionary('embedded://ipadic');

// 外部辞書を使用
$builder->setDictionary('/path/to/dictionary');

setUserDictionary($uri)

ユーザー辞書の URI を設定します。

$builder->setUserDictionary('/path/to/user_dictionary.csv');

setKeepWhitespace($keep)

出力に空白トークンを含めるかどうかを制御します。

$builder->setKeepWhitespace(true);

appendCharacterFilter($kind, $args)

前処理パイプラインに文字フィルタを追加します。

$builder->appendCharacterFilter('unicode_normalize', ['kind' => 'nfkc']);

appendTokenFilter($kind, $args)

後処理パイプラインにトークンフィルタを追加します。

$builder->appendTokenFilter('lowercase');
$builder->appendTokenFilter('japanese_stop_tags', [
    'tags' => ['助詞,格助詞,一般', '助詞,係助詞', '助詞,連体化', '助動詞'],
]);

ビルド

build()

設定された内容で Tokenizer をビルドして返します。

$tokenizer = $builder->build();

Tokenizer

Tokenizer はテキストに対して形態素解析を行います。

Tokenizer の作成

new Lindera\Tokenizer($dictionary, $mode, $userDictionary)

読み込み済みの辞書から直接トークナイザーを作成します。

<?php

$dictionary = Lindera\Dictionary::load('embedded://ipadic');
$tokenizer = new Lindera\Tokenizer($dictionary, 'normal');

ユーザー辞書を指定する場合：

<?php

$dictionary = Lindera\Dictionary::load('embedded://ipadic');
$metadata = $dictionary->metadata();
$userDictionary = Lindera\Dictionary::loadUser('/path/to/user_dictionary.csv', $metadata);

$tokenizer = new Lindera\Tokenizer($dictionary, 'normal', $userDictionary);

Tokenizer メソッド

tokenize($text)

入力テキストをトークナイズし、Token オブジェクトの配列を返します。

$tokens = $tokenizer->tokenize('形態素解析');

パラメータ:

戻り値: array<Token>

tokenizeSurfaces($text)

入力テキストをトークナイズし、トークンの surface のみを文字列の配列として返します。分かち書き用途の高速パスです。Token オブジェクトを生成せず、形態素の詳細情報もロードしないため、surface 文字列だけが必要な場合は tokenize より大幅に高速です。結果は array_map(fn ($t) => $t->surface, $tokenizer->tokenize($text)) と一致します。

<?php

$surfaces = $tokenizer->tokenizeSurfaces('形態素解析');
// ["形態素", "解析"]

パラメータ:

戻り値: array<string>

tokenizeNbest($text, $n)

N-best トークナイズ結果を返します。各結果は NbestResult オブジェクトで、トークン配列とトータルパスコストを含みます。

$results = $tokenizer->tokenizeNbest('すもももももももものうち', 3);
foreach ($results as $result) {
    echo "Cost: {$result->cost}\n";
    foreach ($result->tokens as $token) {
        echo "  {$token->surface}\n";
    }
}

パラメータ:

戻り値: array<NbestResult>

NbestResult

NbestResult は N-best トークナイズの個別の結果を表します。

NbestResult プロパティ

Token

Token は単一の形態素トークンを表します。

Token プロパティ

Token メソッド

getDetail($index)

指定されたインデックスの詳細文字列を返します。インデックスが範囲外の場合は null を返します。

$token = $tokenizer->tokenize('東京')[0];
$pos = $token->getDetail(0);        // 例: "名詞"
$subpos = $token->getDetail(1);     // 例: "固有名詞"
$reading = $token->getDetail(7);    // 例: "トウキョウ"

パラメータ:

戻り値: string または null

toArray()

トークンを連想配列として返します。各フィールドは PHP の自然な型を保つため、 独自のエンコーダなしでシリアライズできます。

$data = $tokenizer->tokenize('東京')[0]->toArray();
// ['surface' => '東京', 'byte_start' => 0, 'byte_end' => 6, 'position' => 0,
//  'word_id' => 12345, 'is_unknown' => false, 'details' => [...]]

echo json_encode(array_map(fn($t) => $t->toArray(), $tokens));

戻り値: surface、byte_start、byte_end、position、word_id、 is_unknown、details をキーに持つ array。

[!NOTE] Lindera\Token は JsonSerializable を実装していないため、トークンオブジェクトを そのまま json_encode に渡してもこれらのフィールドは出力されません。先に toArray() を呼んでください。この拡張は ext-php-rs でビルドされており、その #[php_class] はまだ実装インターフェースを宣言できません（上流の ext-php-rs#326）。

details の構造は辞書によって異なります：

• IPADIC: [品詞, 品詞細分類1, 品詞細分類2, 品詞細分類3, 活用型, 活用形, 原形, 読み, 発音]
• UniDic: UniDic 仕様に準拠した詳細な形態素情報
• ko-dic / CC-CEDICT / Jieba: 各辞書固有の詳細フォーマット

Mode

Mode はトークナイズの動作モードを表します。

Mode の作成

new Lindera\Mode($name)

$mode = new Lindera\Mode('normal');
$mode = new Lindera\Mode('decompose');
$mode = new Lindera\Mode();  // デフォルト: 'normal'

Mode プロパティ

Mode メソッド

Penalty

Penalty は、文字種と長さのしきい値に基づいて、decompose モードが複合語をどの程度積極的に分割するかを設定します。

注意: Penalty は現時点で TokenizerBuilder や Tokenizer のコンストラクタには接続されていません。これを受け取るセッターは存在しないため、インスタンスを作成してもトークナイズには影響しません。decompose モードは常に以下のデフォルト値を使用します。

<?php

// すべてのパラメータは省略可能で、decompose モードが使用するデフォルト値になります
$penalty = new Lindera\Penalty(
    kanji_penalty_length_threshold: 2,
    kanji_penalty_length_penalty: 3000,
    other_penalty_length_threshold: 7,
    other_penalty_length_penalty: 1700,
);

Penalty プロパティ

辞書管理

Lindera PHP は、形態素解析で使用する辞書の読み込み、ビルド、管理のためのクラスを提供します。

辞書の読み込み

システム辞書

Lindera\Dictionary::load($uri) を使用してシステム辞書を読み込みます。GitHub Releases からビルド済み辞書をダウンロードし、展開したディレクトリのパスを指定してください：

<?php

$dictionary = Lindera\Dictionary::load('/path/to/ipadic');

埋め込み辞書（上級者向け） -- embed-* feature フラグ付きでビルドした場合、埋め込み辞書を使用できます：

<?php

$dictionary = Lindera\Dictionary::load('embedded://ipadic');

ユーザー辞書

ユーザー辞書はシステム辞書にカスタム語彙を追加します。Lindera\Dictionary::loadUser() を使用して読み込みます。

<?php

$dictionary = Lindera\Dictionary::load('/path/to/ipadic');
$metadata = $dictionary->metadata();
$userDictionary = Lindera\Dictionary::loadUser('/path/to/user_dictionary.csv', $metadata);

トークナイザーの作成時にユーザー辞書を渡します：

<?php

$dictionary = Lindera\Dictionary::load('/path/to/ipadic');
$metadata = $dictionary->metadata();
$userDictionary = Lindera\Dictionary::loadUser('/path/to/user_dictionary.csv', $metadata);

$tokenizer = new Lindera\Tokenizer($dictionary, 'normal', $userDictionary);

または、ビルダー経由で設定します：

<?php

$builder = new Lindera\TokenizerBuilder();
$builder->setDictionary('/path/to/ipadic');
$builder->setUserDictionary('/path/to/user_dictionary.csv');
$tokenizer = $builder->build();

Dictionary メソッド

辞書のビルド

システム辞書のビルド

ソースファイルからシステム辞書をビルドします：

<?php

$metadata = Lindera\Metadata::fromJsonFile('/path/to/metadata.json');
Lindera\Dictionary::build('/path/to/input_dir', '/path/to/output_dir', $metadata);

入力ディレクトリには辞書のソースファイル（CSV レキシコン、matrix.def など）が含まれている必要があります。

以下は IPADIC 辞書をダウンロードしてビルドする例です：

<?php

$url = 'https://lindera.dev/mecab-ipadic-2.7.0-20070801.tar.gz';
$filename = '/tmp/mecab-ipadic-2.7.0-20070801.tar.gz';

// Download and extract dictionary source
file_put_contents($filename, file_get_contents($url));
$phar = new PharData($filename);
$phar->extractTo('/tmp/', null, true);

// Load metadata and build
$metadata = Lindera\Metadata::fromJsonFile('resources/ipadic_metadata.json');
Lindera\Dictionary::build(
    '/tmp/mecab-ipadic-2.7.0-20070801',
    '/tmp/lindera-ipadic',
    $metadata
);

Metadata

Metadata クラスは辞書のパラメータを設定します。

Metadata の作成

<?php

// デフォルトのメタデータ
$metadata = Lindera\Metadata::createDefault();

// カスタムメタデータ
$metadata = new Lindera\Metadata('my_dictionary', 'UTF-8', -10000);

JSON からの読み込み

$metadata = Lindera\Metadata::fromJsonFile('metadata.json');

プロパティ

Schema

Schema クラスは辞書のフィールド構造を定義します。

Schema の作成

<?php

// デフォルトスキーマ（IPADIC 互換）
$schema = Lindera\Schema::createDefault();

// カスタムスキーマ
$schema = new Lindera\Schema(['surface', 'pos']);

メソッド