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"]
    SEGMENTER["lindera-segmenter\n(Segmenter)"]
    ANALYSIS["lindera-analysis\n(Analysis Chain)"]
    LIB["lindera\n(Facade)"]
    CLI["lindera-cli\n(CLI)"]
    BINDING["lindera-binding"]
    PY["lindera-python"]
    NODEJS["lindera-nodejs"]
    RUBY["lindera-ruby"]
    PHP["lindera-php"]
    WASM["lindera-wasm"]

    CRF --> TRAINER
    DICT --> TRAINER
    TRAINER -.->|"train feature"| SEGMENTER
    DICT --> IPADIC
    DICT --> UNIDIC
    DICT --> SUDACHIDICT
    DICT --> KODIC
    DICT --> CCCEDICT
    DICT --> JIEBA
    DICT --> NEOLOGD
    DICT --> SEGMENTER
    IPADIC --> SEGMENTER
    UNIDIC --> SEGMENTER
    SUDACHIDICT --> SEGMENTER
    KODIC --> SEGMENTER
    CCCEDICT --> SEGMENTER
    JIEBA --> SEGMENTER
    NEOLOGD --> SEGMENTER
    SEGMENTER --> ANALYSIS
    SEGMENTER --> LIB
    ANALYSIS -.->|"analysis feature"| LIB
    LIB --> CLI
    LIB --> BINDING
    BINDING --> PY
    BINDING --> NODEJS
    BINDING --> RUBY
    BINDING --> PHP
    BINDING --> 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ライブラリ -- linderaファサードとセグメンターAPI
• Lindera Analysis -- 文字フィルタ、トークンフィルタ、Tokenizer
• Lindera Dictionary -- 辞書の読み込みとビルド
• Lindera Trainer -- CRFベースの辞書学習
• Lindera CRF -- CRFエンジン
• Lindera CLI -- コマンドラインインターフェース
• 開発ガイド -- ビルド、テスト、コントリビュート

はじめに

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

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

インストール

動作要件

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

依存関係の追加

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

[dependencies]
lindera = "7"

[!NOTE] この 1 つの依存だけで、分析チェーン（character filter・token filter・Tokenizer）も lindera::analysis として利用できます。セグメンターだけが必要な場合は default-features = false を指定してください。 v6 からアップグレードする場合はv6 から v7 への移行を参照してください。

辞書のセットアップ

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 = "7", 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 で検証。無効なファイルは自動的に再ダウンロード）
• クレートに埋め込まれるビルド済みバイナリ辞書と、その辞書を何から作ったかを記録する build_inputs.json

フォーマットバージョンをパスに含めているのは、オンディスクレイアウトが異なるビルドが書いたキャッシュを「古いまま再利用」ではなく「キャッシュミス」にするためです。キャッシュした辞書は、次のすべてが今回のビルドと一致するときだけ再利用し、そうでなければ作り直します。

• 辞書フォーマットバージョンと、クレートの metadata.json の内容
• 辞書を作る lindera-dictionary クレートのバージョンとソースのダイジェスト。辞書ビルダーを変更すると、コミット前の変更でも辞書を作り直します
• ソースアーカイブ（ファイル名と MD5）と、ビルドがその中で読むディレクトリ
• connection_id_mapping が有効なとき、ビルドが読む文脈 ID の頻度表（context_id_freq.txt、または LINDERA_CTX_FREQ_FILE が指すファイル）

中断されたビルドが残した辞書や、build_inputs.json より前のリリースがキャッシュした辞書は作り直します。ビルダーが依存するクレートのバージョンは比較しません。フォーマットバージョンを変えずに lindera-dictionary の依存クレートを更新したときは、ビルドした辞書が変わりうるならキャッシュを削除してください。古いフォーマットバージョンのディレクトリは自動削除されないため、キャッシュが肥大化する場合は手動で削除してください。

cargo build -vv を実行すると、辞書クレートごとに、キャッシュした辞書を使ったかどうかとその理由が lindera dictionary cache: で始まる行に表示されます。

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

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

使用方法：

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

注意点：

• このディレクトリは自動管理されており、削除しても安全です（必要に応じて再ダウンロード・再ビルドされます）
• バージョンごとのサブディレクトリはアップグレードのたびに蓄積され、自動削除されません。古いものは自由に削除できます
• この変数を設定すると、embed-* feature が無効でも辞書クレートはダウンロードとビルドを実行します（キャッシュの事前準備に便利です）。このビルドは辞書を埋め込まないので、キャッシュにすでにある辞書は確かめずにそのまま残します。embed-* feature を有効にしたビルドが確かめ、必要なら作り直します
• キャッシュディレクトリは checkout ごとに 1 つ使ってください。辞書ビルダーのコードが異なる 2 つの checkout が同じディレクトリを共有すると、互いの辞書を作り直し合います。さらに、build script が再実行されなかったクレートは、もう一方の checkout が作った辞書を埋め込むことがあります。このリポジトリでは相対パスがワークスペースのルートを基準に解決されるので、checkout ごとに別のキャッシュになります
• このディレクトリを共有するビルド（たとえば cargo build と、別のターゲットディレクトリを使う rust-analyzer）は、辞書を 1 つずつ書き込みます。同じ辞書を別のビルドが書き込んでいれば、それが終わるのを待ち、そのビルドが残した辞書を使います（cargo build -vv に lindera dictionary cache: waiting for another build と表示されます）。ロックは辞書の隣にある空の <辞書>.lock ファイルで、ビルドが辞書を書き込む間だけ保持します。ロックが効くのは 1 台のマシンの中のビルド同士で、ネットワークファイルシステムでは、そのファイルシステムがファイルロックに対応する範囲に限られます。ファイルをロックできないときは、ビルドは警告を出し、7.0.0 より前と同じくロックなしで続けるので、そうしたビルド同士は互いのファイルを消すことがあります
• DOCS_RS を設定したビルドは、この変数を無視します（後述の DOCS_RS を参照）

LINDERA_CONFIG_PATH

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

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

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

DOCS_RS

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

このビルドは LINDERA_BUILD_DICTIONARY_CACHE_DIR を無視します。ダミーの辞書は build script の出力ディレクトリに作られ、キャッシュには入らないので、後で DOCS_RS なしにビルドしても埋め込まれません。

これは主に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 （デフォルトで有効な analysis feature）として利用できるため、 lindera = "7" だけで分析チェーン全体を利用できます。追加の依存は不要です。 default-features = false にするとセグメンターのみになります。詳細は Lindera Analysis を、v6 からアップグレードする場合は v6 から v7 への移行 を参照してください。

サンプル

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

tokenize* のサンプルは lindera::analysis の Tokenizer とフィルタ API を使います。ソースは lindera-analysis クレートにあるため、以下では -p lindera-analysis を指定します。

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

利用可能なサンプル

segment

Segmenter API による基本的な形態素分割です。セグメンターだけで足りるため、default-features = false でも動作します。

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 コストを制限するためです。次の \n や \t までは、各文が前の文の最後の語から続くため、わずかな例外を除いて、そのテキスト全体を 1 つのラティスで解いた場合と同じ結果になります（文分割を参照）。区切り文字を含まない病的な入力（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*探索を使用して総コストの昇順にパスを列挙します。

1-best のトークナイズと同じく、入力はまず文に分けられ、\n や \t までの文の並びが 1 つの区間になります（文分割を参照）。区間ごとに探索され、区間の中では 、・。 をまたいで文脈を引き継ぐため、区間のパスは、区間全体を 1 つのラティスで解いたときのコストの小さい N 本のパスです。どの候補も入力全体の分割で、区間ごとに 1 つのパスを選び、そのコストは選んだパスのコストの合計です。候補は、これらの組み合わせのうちコストの小さい N 件です。

unique を指定すると、後ろ向きの探索はパスではなく単語境界を単位に進みます。1 つの区切りには各単語の辞書エントリの選び方の数だけパスがあり、短い行でも数百万本になることがありますが、探索は各区切りを最もコストの低いパスで 1 回だけ取り出し、他のパスはたどりません。

パラメータ

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::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内容の例

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

表層形（1 列目）は書いたとおりに使われます。先頭や末尾の空白も語の一部になり、空白だけの表層形も登録できます（IPADIC は U+3000 をこの形で登録しています）。読み飛ばされるのは空の表層形だけです。lindera build でビルドするシステム辞書の見出し語の CSV も同じです。

末尾が空白の語は、空白をラティス上で読み飛ばすとき（SudachiDict を除く同梱辞書のデフォルト。空白文字の扱い を参照）も、MeCab と同じくその空白をトークンに含みます。ただし読み飛ばすときは、辞書の SPACE カテゴリの空白で始まる語や、その空白だけの語は一致しません。読み飛ばした空白から始まる語はないためです。U+3000 は SPACE カテゴリではないため、IPADIC の U+3000 の語は引き続き一致します。

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

同点の見出し語

表層形・左右の文脈 ID・コストがすべて同じ 2 つの見出し語は同点です。どちらを使っても経路のコストは同じになります。ユーザー辞書の見出し語は、同点のシステム辞書の見出し語より優先して選ばれます。そのため、システム辞書の見出し語の表層形・文脈 ID・コストをそのまま使った詳細形式の見出し語（たとえば語に別の読みを与えるもの）は、システム辞書の見出し語の代わりに出力されます。MeCab はシステム辞書の見出し語を選びます。同点のユーザー辞書の見出し語どうしでは、MeCab と同じく先の行が選ばれます（v7 より前は後の行でした。v6 から v7 への移行を参照）。簡易形式の見出し語には、辞書の metadata.json のコストと文脈 ID（default_word_cost・default_left_context_id・default_right_context_id。IPADIC では -10000・0・0）が使われるため、システム辞書の見出し語と同点になることはまずありません。

文脈 ID

詳細形式の見出し語の左右の文脈 ID は、組み合わせるシステム辞書の接続コスト行列のセルを指していなければなりません。左文脈 ID はそのシステム辞書の matrix.def のヘッダの 2 つ目の値より小さく、右文脈 ID は 1 つ目の値より小さくなければなりません。lindera build がシステム辞書自体に課すのと同じ範囲です。たとえば IPADIC の行列は 1316 x 1316 です。

CSV のユーザー辞書をシステム辞書と一緒にビルドするときは、ビルドしながら各行を確認し、行列の範囲外にある最初の行で、その CSV の行番号と表層形を示すエラーを出して失敗します。

• --system-dict でシステム辞書を指定した lindera build --user（Rust API では DictionaryBuilder::with_system_matrix。文脈 ID の確認 を参照）
• 設定（Segmenter::from_config、TokenizerBuilder）や lindera tokenize --user-dict で指定した .csv のユーザー辞書と、Python・Node.js・Ruby・PHP のバインディングの TokenizerBuilder にパスで渡した .csv のユーザー辞書
• 読み込み済みのシステム辞書に合わせてユーザー辞書を読み込む関数（Rust API・Python・Ruby の load_user_dictionary_for、Node.js の loadUserDictionaryFor、PHP の Lindera\Dictionary::loadUserFor、WebAssembly の loadUserDictionaryFromBytesFor）
• 読み込み済みのシステム辞書に合わせてユーザー辞書をビルドする関数（Python・Ruby の build_user_dictionary_for、Node.js の buildUserDictionaryFor、PHP の Lindera\Dictionary::buildUserFor）

たとえば、1 行目が IPADIC の行列の範囲内にあり、2 行目の左文脈 ID が 60000 の userdic.csv では次のようになります。

$ echo 東京スカイツリーへ行く | lindera tokenize -d embedded://ipadic -u userdic.csv
Error: LinderaError { kind: Args, source: LinderaError(kind=Parse, source=failed to build tokenizer: LinderaError(kind=Content, source=user dictionary line 2 (surface: '東京スカイツリー'): left context id 60000 is out of range for the connection matrix (matrix.def size 1316 1316; left context ids must be below 1316)))

それ以外のユーザー辞書は、システム辞書なしでビルドされます。--system-dict を指定せずに lindera build --user で書き出した .bin、バインディングのビルド関数でメタデータだけを使って書き出した .bin（Python・Ruby の build_user_dictionary、Node.js の buildUserDictionary、PHP の Lindera\Dictionary::buildUser）、メタデータだけで読み込んだユーザー辞書（Rust API・Python・Ruby の load_user_dictionary、Node.js の loadUserDictionary、PHP の Lindera\Dictionary::loadUser、WebAssembly の loadUserDictionaryFromBytes）です。この場合、文脈 ID は 2 つの辞書を組み合わせるときに確認します。Segmenter::try_new、設定からの構築、lindera tokenize --user-dict、各言語バインディングの Tokenizer のコンストラクタとビルダーは、行列の範囲外にある最初の見出し語についてエラーを返します。エラーは、見出し語をその単語 ID（表層形の順に並べた行を 0 から数えた番号）と詳細フィールドで示します。上の userdic.csv からビルドした .bin では次のようになります。

$ echo 東京スカイツリーへ行く | lindera tokenize -d embedded://ipadic -u user_dict/userdic.bin
Error: LinderaError { kind: Args, source: LinderaError(kind=Parse, source=failed to build tokenizer: LinderaError(kind=Content, source=user dictionary entry 1 (名詞,固有名詞,一般,*,*,*,東京スカイツリー,トウキョウスカイツリー,トウキョウスカイツリー): left context id 60000 is out of range for the connection matrix (matrix.def size 1316 1316; left context ids must be below 1316)))

Segmenter::new はこの ID を確認しません。範囲外の見出し語があると、その見出し語が入力に一致したときに解析中にパニックします。v7.0.0 より前は、どの経路もこの動作でした。簡易形式の見出し語も確認します。簡易形式の見出し語には、ビルドに使う metadata.json の文脈 ID（default_left_context_id と default_right_context_id。同梱のどの辞書でも 0）が使われます。

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)?;
    // `try_new` checks the user dictionary's context IDs against the
    // dictionary's connection matrix (see "Context IDs" above).
    let segmenter = Segmenter::try_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 <user_dictionary.csv> --dest <dest_dir> --metadata <metadata.json> --user [--system-dict <system_dictionary>]

--system-dict を指定すると、組み合わせるシステム辞書と照らし合わせて文脈 ID を確認します（文脈 ID を参照）。

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

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

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

フィルタ

Linderaの解析パイプライン（lindera-analysisクレートが提供し、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種類の文字フィルタと21種類のトークンフィルタを提供しており、日本語・韓国語・汎用的なテキスト正規化をカバーしています。

各フィルタの説明・パラメータ・実行可能な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はラベル付きラティスの例を受け取り、前向き・後向きアルゴリズムで勾配を計算し、反復的にモデルの重みを更新します。Trainer::trainは学習したRawModelを返します。Trainer::train_with_statsは、実際に回ったイテレーション数を持つTrainingStatsも返します。この数は、Trainer::max_iterで設定した最大値で学習が止まったときはその値で、収束などでそれより前に最適化が止まったときはそれより少なくなります。

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を保持します。

RawModel::unigram_weightは、ユニグラム素性IDの並びについてこの和を計算し、mergeはラベルごとにこれを呼びます。重みのない素性は何も足さないため、学習でラベルでなかったエントリの素性の重みも計算できます。lindera-trainerはユーザー辞書のエントリのコストにこれを使います。

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

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

Feature フラグ

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

APIリファレンス

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

• lindera-crf

Lindera Dictionary

Lindera Dictionaryは、形態素解析辞書のベースライブラリです。辞書の読み込み、ビルド、Viterbiベースのセグメンテーションを提供します。CRFベースの辞書学習機能は、別クレートのlindera-trainerが提供します。lindera ファサードからは lindera::dictionary 配下（辞書データ構造の lindera::dictionary::core、lindera::dictionary::builder、lindera::dictionary::viterbi など）で参照できるため、lindera-dictionary への直接依存はほとんど不要です。

主な特徴

• ファイルシステムまたは埋め込みデータからの辞書読み込み
• 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, UniqueNBestGenerator (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セグメンテーションパスを生成します。これにより、アプリケーションは単一の最適パスを超えた代替セグメンテーションを検討できます。

UniqueNBestGenerator

区切り（単語境界の並び）の異なる N-best を生成します。区切りごとに最もコストの低いパスを、コストの昇順に返します。unique な N-best（unique、--nbest-unique）はこれを使います。1 つの区切りには、各単語の辞書エントリの選び方の数だけパスがあり、短い行でも数百万本になることがあります。そのため、パスではなく単語境界の並びの末尾部分を単位に、後ろ向きに探索します。1 つの探索ノードが 1 つの範囲の候補をすべてまとめて持ち、そのコストは正確なので、各区切りはちょうど 1 回現れ、処理量はパスの数ではなく、結果の数と行の長さに比例します。1 件目は 1-best のパスで、同じ表層・同じ文脈 ID・同じコストのエントリは、1-best と同じく、どの結果でも CSV の先の行になります。

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 行も変わらないため見落としやすい箇所です。ビルドキャッシュがフォーマットバージョンをキーに含めているのは、まさにこのためです。

現在のフォーマットバージョンは 3 です。バージョン 2（v6.0.0）では、システム前方一致辞書のバイト単位 daachorse Aho-Corasick オートマトン（dict.da）が、文字単位のダブル配列トライ（dict.trie）と u32 の累積和インデックス（dict.valsidx）に置き換えられました。バージョン 3（v7.0.0）では、char_def.bin の各行に、コードポイントの既定カテゴリを先頭に、残りのカテゴリをカテゴリ ID 順に並べます。MeCab と同じく未知語は既定カテゴリだけから作るためで、バージョン 2 の行を読むと既定カテゴリを黙って取り違えます。バージョン 3 には、それより前の 7.0.0 でのビルダーの出力の変更も含まれます（v6 から v7 への移行 を参照）。バージョン 2 以前の辞書はロード時に対処方法を含むエラーで拒否されます。ユーザー辞書の .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など）を扱える
• MeCabの学習器と同じ学習用ラティス: 各位置から始まる種辞書の語と、ランタイムがchar.defとunk.defから作る未知語を候補にし、unk.defのエントリごとに1つのCRFラベルを割り当てる
• 学習された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・unk.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を構築し、さらに種辞書・文字定義・未知語定義をもとにインメモリのlindera_dictionary::dictionary::Dictionaryを組み立てます。char.defは辞書ビルダー（CharacterDefinitionBuilder::build_from_str）でパースするため、学習時の文字カテゴリはビルドされる辞書と同じになります。%t素性に使う各文字の既定カテゴリは、ビルダーのbuild_default_category_tableから得ます。このDictionary（dict()）は学習用ラティスの材料を持ちます。prefix_dictionary（system_lexicon()）は種辞書で、種辞書の表層形を収めたprefix dictionaryの単語IDは行番号です。unknown_dictionary（unk_handler()）は、辞書ビルダーのparse_unkで読んだunk.defのエントリを、ファイル順に1行1エントリで持ちます。これらのコストと文脈IDは学習では使わず、Dictionaryの連接行列はプレースホルダーです。TrainerConfigは、種辞書の素性文字列と、unk.defのエントリを(カテゴリ, 素性文字列)の組としてファイル順にも保持し、ラベルとエクスポートするunk.defはこれらから作ります。unk.defでは、#で始まる行と空行を読み飛ばし、フィールドが5つ未満の行と、文脈IDやコストが数値でない行は、その行を示すエラーになります。from_readersは、mecab-dict-indexやlindera buildと同じく、それより前の行で定義していないカテゴリを指すchar.defの範囲行、2回定義したカテゴリ、char.defにないカテゴリを指すunk.defの行、unk.defの行がないchar.defのカテゴリも拒否します（lindera_dictionary::dictionary::unknown_dictionary::check_unknown_word_categories）。そのため、こうした入力は、エクスポートしたファイルのビルドではなく、学習の前に失敗します。また、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]です。%F[n]・%L[n]・%R[n]が最後の列より後ろを読むテンプレートは、?の有無にかかわらず、MeCabの学習器と同じく素性を作りません。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)を返します。マッチするルールがないセクションは入力をそのまま通過させます。MeCabと同じく、素性と各ルールのパターン・置換はMeCabのtokenizeCSVの規則（クレート内部のfeature_csv::split_feature）で列に分けるので、,を含む引用付きの列は1つの列です。rewrite()は書き換えた列を,でつなぎ、,か"を含む列は引用符で囲みます。学習器は、素性テンプレートのために3つの結果を同じく列に分けます。（かつてのrewrite_cached()は素性文字列全体をキーにメモ化していましたが、実辞書の素性は行ごとにほぼ一意でキャッシュが一度もヒットしないため削除されました — #975。）

Trainer

Trainer::newはCRFのラベルを作ります。まず種辞書の行ごとに行順で1つ（ラベル行番号 + 1。単語IDが行番号である学習用辞書での一致を、そのままラベルに対応付けるため）、続いてunk.defのエントリごとにファイル順で1つ作り、その%tはエントリのカテゴリのIDです。Trainer::trainは、MeCabの学習器と同じく、例文ごとにlindera_crf::Latticeを1つ作ります。

• 各位置の候補は、その位置から始まる種辞書の語と、ランタイムがその位置に作る未知語です。未知語はlindera_dictionary::viterbi::Lattice::unknown_word_candidatesが列挙します。文字の既定カテゴリの未知語を、そのINVOKE・GROUP・LENGTHの設定で、カテゴリのunk.defのエントリそれぞれについて作ります。
• 正解の各トークンには、範囲と素性文字列全体が同じ最初の種辞書の行のラベルを付けます。なければ、範囲が同じ未知語候補のunk.defエントリのうち、*以外の素性の列がすべて正解トークンの列と一致するファイル順で最初のエントリのラベルを付けます（どちらの列もrewrite()と同じく分けます）。それもなければ、MeCabの学習器が仮想ノードを追加するのと同じく、正解の素性文字列から作る仮想ラベル（%tは0、%wなし、素性文字列ごとに1つ）を付けます。仮想ラベルはほかのラベルの後に並び、学習されますが、エクスポートされることはありません。
• それ以外の候補はすべて負例の辺になります。

ラティスを作り終えると、Lattice statistics:の行を出力します。各方法でラベルを付けた正解トークンの数（gold_lexicon・gold_unknown・gold_virtual）、仮想ラベルの数（virtual_labels）、種辞書と未知語候補それぞれから作った負例の辺の数（negative_lexicon・negative_unknown）です。Trainer::max_grouping_lenは、ランタイムと同じ意味（先頭の1文字を除いた文字数。デフォルトのNoneは無制限）で未知語のグルーピングの長さに上限を設けます。ほかのビルダーメソッドは、正則化・イテレーション数の上限・スレッド数を設定します。

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と同じ学習結果の情報――素性の重み、ラベル、品詞情報、連接コスト行列、unk.defのエントリ（unk_entries。ファイル順の(カテゴリ, 素性文字列)の組）、保存されているchar.def / feature.def / rewrite.defの内容、コストファクター、左右文脈IDマッピング――をTrainerConfigを持たない所有データとして保持し、辞書エクスポートファイルを生成するための独自のライターメソッド群を提供します。

Modelのパブリックメソッド

SerializableModelのパブリックメソッド

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

ModelMetadataとFeatureSetInfo

ModelMetadataは学習実行に関する要約情報を保持します: version（モデルの形式バージョンMODEL_FORMAT_VERSION）、regularization（使用した正則化コスト係数）、iterations（実際に回ったL-BFGSのイテレーション数。Trainer::max_iterで設定した最大値以下。model_info.training_iterationsとしてエクスポートされます）、feature_count、label_countです。SerializableModel::metadataに格納されます。

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

APIリファレンス

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

• lindera-trainer

Lindera ライブラリ

lindera クレートは Rust API のファサードです。lindera-segmenter の形態素セグメンター（lindera::segmenter・lindera::dictionary・lindera::mode など）を再エクスポートし、デフォルトで有効な analysis feature により lindera-analysis の分析チェーンを lindera::analysis として提供します。必要な依存は lindera = "7" の 1 行だけで、default-features = false にするとセグメンターのみになります。このセクションでは、セグメンテーション、エラーハンドリング、APIリファレンスについて説明します。

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

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

Segmenter

Segmenter は形態素解析を実行するコアコンポーネントです。辞書とコストモデルに基づいて、入力テキストの最適な分割を Viterbi アルゴリズムで探索します。表層形・文脈 ID・コストがすべて同じ見出し語（同点の見出し語）からは、MeCab と同じく CSV で先の行を選び、ユーザー辞書の見出し語とシステム辞書の見出し語が同点ならユーザー辞書の見出し語を選びます（同点の見出し語を参照）。同じ位置で終わる 2 つの分割のコストが同じなら、MeCab と同じく最後の語が後から始まる方を選びます。

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);
}

Segmenter::new はユーザー辞書をシステム辞書と照らし合わせて確認しません。Segmenter::try_new は同じ引数を取り、見出し語の文脈 ID がシステム辞書の接続コスト行列の範囲外にあるとエラーを返します。Segmenter::new はそうした見出し語を受け付け、その見出し語が入力に一致したときに解析中にパニックします（文脈 ID を参照）。設定からの構築も確認します。load_user_dictionary_for は、読み込み済みのシステム辞書に合わせてユーザー辞書を読み込み、.csv はビルドする時点で確認するため、エラーはその行の CSV の行番号と表層形を示します。.bin や、load_user_dictionary でメタデータだけを使って読み込んだユーザー辞書では、try_new が見出し語を単語 ID で示します。

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

let dictionary = load_dictionary("embedded://ipadic")?;
let user_dictionary = load_user_dictionary_for("userdic.csv", &dictionary)?;
let segmenter = Segmenter::try_new(Mode::Normal, dictionary, Some(user_dictionary))?;
}

トークナイズモード

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）と同じ挙動になります。

Segmenter::from_config_with_dictionaries は、バイト列から読み込んだ辞書など、読み込み済みの辞書に設定を適用します。Some で渡した辞書は dictionary キーが指す辞書の代わりに使われ、このときキーは省略できます（use_mmap は関係しません）。Some で渡したユーザー辞書は、user_dictionary キーが指すユーザー辞書の代わりに使われます。None の場合、辞書は from_config と同じく設定から読み込まれ、設定にあるユーザー辞書は、load_user_dictionary_for で使う辞書に合わせて読み込まれます（.csv はその辞書のメタデータでビルドし、接続コスト行列と照らし合わせて確認します）。それ以外のキーは from_config と同じように適用されます：

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

let dictionary = load_dictionary("embedded://ipadic")?;
let config: SegmenterConfig = json!({
    "mode": "normal",
    "keep_whitespace": true
});
let segmenter = Segmenter::from_config_with_dictionaries(&config, Some(dictionary), None)?;
}

Tokenizer::from_config_with_dictionaries と TokenizerBuilder::build_with_dictionaries は、フィルタを含むトークナイザーの設定に対して同じことを行います（アーキテクチャを参照）。

メモリマップド読み込み

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

空白文字の扱い

デフォルトでは、MeCab と同様に空白をラティス上で読み飛ばします。空白文字から始まる語はなく、空白の後ろの語は空白の前の語に直接接続し、辞書が学習した連接コストが使われます。読み飛ばした空白は出力に現れず、トークンの表層形とオフセットにも含まれません。ただし、見出し語の一部である空白は、語の途中（IPADIC-NEologd の GeForce GTX、ユーザー辞書の 해운대 해수욕장）でも末尾（ko-dic の、半角スペースの付いた 에듀）でも、MeCab と同じくその語のトークンに残ります。「空白」とは辞書の SPACE 文字カテゴリ（char.def）のことで、ko-dic では U+0020、U+0009、U+000A、U+000B、U+000D、IPADIC・IPADIC-NEologd・UniDic・SudachiDict・CC-CEDICT・Jieba では U+0020、U+0009、U+000A、U+000B です。これらの char.def は U+00D0（Ð）も SPACE に割り当てています（U+000D のタイポ）が、後続の 0x00C0..0x00FF ALPHA 行が優先されるため、MeCab と同じく Ð は英字として扱われます。

デフォルトは辞書の metadata.json（skip_whitespace）で決まります。SudachiDict はこれを false にしています。Sudachi は空白をラティスに残して 空白 トークンとして出力し、SudachiDict のコストもそれに合わせて調整されているため、読み飛ばすと、たとえば caramel man という項目が 2 つの普通名詞に分割されてしまいます。そのため SudachiDict では、デフォルトで空白が独立したノード（U+0020 の項目のような 空白 の見出し語か、SPACE の未知語）としてラティスに残ります（出力からは除外されます）。他の同梱辞書はこの設定を持たず、その場合は読み飛ばします。設定が導入される前にビルドされた辞書（再ビルドするまでの Lindera 6.x 製の SudachiDict を含む）も同様です。

Segmenter に対して keep_whitespace(true) を呼び出すと、空白のトークンを出力します。このとき空白はラティスにも独立したノード（IPADIC や UniDic の U+3000 の項目のような空白の見出し語か、SPACE の未知語）として残るため、他のトークンも、空白を読み飛ばすデフォルトの出力と変わることがあります：

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

v7 より前の Lindera は、空白を出力から除外する場合でもラティスにはノードとして残していました。そのため空白の前後の語は、互いにではなく空白のノードに接続していました。その影響の大きさは、辞書の SPACE の未知語の連接コストによります。ko-dic では連接表のその行と列がすべて 0 なので、空白のたびに文脈が途切れ、空白に挟まれた語は単語コストだけで選ばれていました。ko-dic は 2년 전 대회 の 전 を名詞 NNG ではなく 저/NP + ㄴ/JX と解析していました。IPADIC と UniDic ではこの連接コストは 0 ではなく（IPADIC の SPACE の未知語は全角空白の項目 記号,空白 と文脈 ID を共有します）、IPADIC は Google が 新しい の が を接続詞と解析していました。CC-CEDICT と Jieba には連接コスト自体がないため、分割はこの違いに左右されませんが、N-best が返す経路のコストは変わります。skip_whitespace は辞書のデフォルトを上書きします。skip_whitespace(false) は従来どおり空白ノードをラティスに残し（出力からは除外）、skip_whitespace(true) は SudachiDict でも読み飛ばしを有効にします。SegmenterConfig の skip_whitespace キーには true または false を指定し、省略するか null にすると辞書のデフォルトのままになります。CLI では --disable-skip-whitespace で読み飛ばしを無効にします：

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

\n と \t は引き続き区間の終わりになるため（文分割 を参照）、改行やタブをまたいで文脈は引き継がれません。mecab-ko は 1 行ずつ解析し、行内のタブは他の空白と同様に読み飛ばします。

未知語のグルーピング

辞書にない語は「未知語」として扱われます。未知語は、辞書の char.def が文字に割り当てる文字種（カタカナ・英字・数字・記号など）をもとに作られます。漢数字（IPADIC では KANJINUMERIC KANJI）のように、1 つの文字が複数の文字種を持つこともあります。その文字の文字種を決める char.def の行の先頭の文字種を、その文字の「既定の文字種」と呼びます。Lindera は、ラティス上の経路が到達するすべての位置で、その位置の文字の既定の文字種から未知語候補を作ります。作るのは、その文字種が常に未知語を作る設定（char.def の INVOKE）の場合か、その位置から始まる辞書語がない場合で、MeCab と同じ条件です。グルーピングする設定（GROUP）の文字種では、カタカナの連続のように、その位置から「どの文字も直前の文字と文字種を 1 つ以上共有する」間続くランを 1 つの候補にします。これを「グルーピングした未知語」と呼びます。

ko-dic では、数字の 三 は HANJANUMERIC HANJA（既定の文字種はグルーピングする HANJANUMERIC）、ほかの漢字は HANJA です。そのため 三 から始まるグルーピングした未知語は後ろの漢字まで続き、三國史記 は MeCab と同じく 1 つの未知語（SH）になります。v7 より前の Lindera は、文字の文字種ごとに候補を作り、次の文字が文字種の並びの同じ位置に同じ文字種を持つ間だけランを続けていたため、三 / 國史 / 記 を返していました。

未知語は、前の位置からグルーピングした未知語が覆うランの内側も含め、こうしたどの位置からも始まります。IPADIC の char.def は ・ をカタカナの範囲に含めるため、ジョン・レノンが歌う の先頭の位置では ジョン・レノン がグルーピングした未知語になります。一方、辞書語の ジョン と ・ をたどる経路が レ の位置に届き、そこから未知語 レノン が始まるので、結果は MeCab と同じく ジョン / ・ / レノン / が / 歌う になります。v7 より前の通常モードは、Kuromoji から引き継いだ近道として、直前にグルーピングした未知語の内側の位置では未知語を作らなかったため、ジョン・レノン を 1 つの未知語として返していました。Decompose モードにはこの近道はありませんでした。

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

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

上限はラン全体ではなく、ラティスの各位置で判定されます。ある位置から始まるランが上限を超える場合、その位置ではグルーピング候補を出さず、1 文字候補（および後述の候補ラダーと辞書語）が残ります。残りの末尾は上限に収まった時点で再びグルーピングされます。そのため未知語トークンは最長で n + 1 文字になりますが、上限を超えるランが全体として 1 文字ずつになるわけではありません。IPADIC で辞書外のカタカナ列 ヷヸヹヺヷ を max_grouping_len(Some(2)) で分割すると、候補ラダーを無効にした場合は ヷ / ヸ / ヹヺヷ になります。先頭 2 つの位置ではランの長さが 5 文字・4 文字で上限を超えるため 1 文字候補だけが残り、末尾 3 文字は上限に収まるのでグルーピングされます。候補ラダーが有効（デフォルト）の場合は先頭位置で 2 文字のラダー候補が選ばれ、ヷヸ / ヹヺヷ になります。

Some(0) は 2 文字以上のランを一切グルーピングしません。設定キー max_grouping_len と CLI の --max-grouping-len では 0 は無制限を意味します。

グルーピングとは独立に、Lindera はデフォルトで MeCab/Vibrato 由来の 「候補ラダー（length ladder）」も生成します。1 文字から、既定の文字種の char.def の LENGTH フィールドまでの短い未知語候補を段階的に生成し、 Viterbi 探索が最もコストの低い長さを選べるようにします。候補が伸びるのは、 先頭の文字と文字種を共有する文字が続く間です。MeCab と同じく、各文字は 直前の文字ではなく先頭の文字と比べます。unknown_word_ladder(false) で 無効にすると、各位置で作る候補は、v6 より前と同じくグルーピング候補か 1 文字候補だけになります。ただし、ランの内側から始まる未知語など、その後の変更に よる出力の違いは残るため、v6 より前の出力とは一致しません（v6 から v7 への移行を参照）:

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

左側空白ペナルティ（韓国語）

MeCab ベースの韓国語解析器（mecab-ko + mecab-ko-dic、Lucene の nori）は、直前に空白がある候補の品詞が、本来は前の語に空白なしで付く品詞（助詞 J*、語尾 E*、指定詞 VCP、派生接尾辞 XS*）である場合にコストを加算します。これがないと 검색 이 잘 된다 の 이 は感動詞 IC ではなく主格助詞 JKS と解析されます。Lindera は、ルールを metadata.json に同梱する辞書（ko-dic）ではこのペナルティをデフォルトで適用します。他の辞書には影響しません。Segmenter::space_penalty(None)、設定の "space_penalty": false、CLI の --disable-space-penalty でオフにできます。skip_whitespace(false) と併用すると、空白まわりの韓国語の解析について v6.0 以降に入った 2 つの変更（このペナルティと空白の読み飛ばし）がどちらもオフになります。ただし、." のような記号の連続が分かれるなど、それ以外の出力の変化は残ります（v6 から v7 への移行を参照）。

SpacePenaltyConfig は「先頭品詞タグの一覧とコスト」の組（ルール）のリストです。候補は品詞タグの最初の + より前の部分（ko-dic の Inflect 行では first_part_of_speech 列）で照合され、最初に一致したルールが適用されます。一覧にないタグのコストは 0 です。mecab-ko-dic の dicrc のルールは次のように書けます:

#![allow(unused)]
fn main() {
use lindera::space_penalty::{SpacePenaltyConfig, SpacePenaltyRule};

let rules = SpacePenaltyConfig::new(vec![
    SpacePenaltyRule::new(["EC", "EF", "EP", "ETM", "ETN", "VCP", "XSA", "XSN", "XSV"], 3000),
    SpacePenaltyRule::new(["JC", "JKB", "JKC", "JKG", "JKO", "JKQ", "JKS", "JKV", "JX"], 6000),
]);
let segmenter = Segmenter::new(Mode::Normal, dictionary, None).space_penalty(Some(rules))?;
}

「空白」とは辞書の SPACE カテゴリ（char.def）に属する文字のことで、ラティス上で読み飛ばす文字集合、keep_whitespace が除外する文字集合と同じです。SPACE カテゴリを持たない辞書では Unicode の White_Space にフォールバックします。ペナルティは両モードと N-best 探索で適用され、システム辞書・ユーザー辞書・未知語のいずれのエントリにも効きます。space_penalty は単語 ID ごとの参照表を一度だけ構築し（ko-dic で数十ミリ秒）、辞書スキーマに part_of_speech_tag も part_of_speech もない場合はエラーを返します。

辞書は metadata.json の space_penalty にデフォルトのルールを同梱できます。ko-dic は上記とまったく同じルールを同梱しており、Segmenter::new がそれを自動的に適用します。space_penalty_from_dictionary() はオフにした後に再び有効化するためのもので、ルールを同梱しない辞書ではエラーを返します。同梱ルールを適用できない辞書（スキーマに品詞列が無い辞書）では、Segmenter::new は警告を出してオフのままにします:

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

このルールを同梱しているのは、Lindera 6.1.0 以降でビルドした ko-dic だけです。v6.0.0 リリースからダウンロードした ko-dic にはルールがないため、その辞書ではペナルティは黙ってオフのままになり、space_penalty_from_dictionary()（および "space_penalty": true）は辞書を再ビルドするまでエラーを返します。明示的なルール（space_penalty、--space-penalty-rules）はどの ko-dic でも使えます。

SegmenterConfig の space_penalty キーには、明示的なルールのオブジェクト、オフにする false、辞書のルールを要求する true（同梱しない辞書ではエラー）を指定できます。キーを省略するか null にするとデフォルト、つまり辞書がルールを同梱していればそのルールが使われます:

{
  "dictionary": "embedded://ko-dic",
  "space_penalty": {
    "rules": [
      { "pos": ["EC", "EF", "EP", "ETM", "ETN", "VCP", "XSA", "XSN", "XSV"], "cost": 3000 },
      { "pos": ["JC", "JKB", "JKC", "JKG", "JKO", "JKQ", "JKS", "JKV", "JX"], "cost": 6000 }
    ]
  }
}

候補は、前の語との間にその語に含まれない空白があるときにペナルティを受けます。これは mecab-ko の判定（空白を読み飛ばしたノード、つまり rlength > length のノードに加算する）と同じです。そのため、文頭の空白の後の語はペナルティを受け、表層が空白で終わる見出し語の直後の語は受けません。ko-dic にはこのような見出し語が 4 件あり（내셔날、에듀、캘리、콜라비 のそれぞれに空白が続くもの）、에듀 이 は mecab-ko と同じくこの見出し語と 이/VCP になります。見出し語が含まない 2 つ目の空白がある 에듀 이 では 이/NR になります。判定は、空白をラティス上で読み飛ばす場合（デフォルト。空白文字の扱い を参照）でもノードとして残す場合でも同じで、残す場合は空白のノードの後の語がペナルティを受けます。空白を読み飛ばすと、ペナルティの対象となる読みの一部は連接コストだけで排除されます（서울 시 에서 の 시 はペナルティなしでも NNG）が、すべてではありません（검색 이 잘 된다 の 이）。

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());
    }
}
}

どの結果も入力全体の分割です。入力は文分割のとおりに区間に分けられ、区間ごとに探索されます。区間の中では 、・。・強制的な区切りをまたいで文脈を引き継ぐため、区間のパスは、区間全体を 1 つのラティスで解いたときのコストの小さい n 本のパスです（例外は文分割を参照）。unique は区間全体の単語境界で比較します。各結果は区間ごとに 1 つのパスを選んだ組み合わせで、そのコストは選んだパスのコストの合計です。結果は、これらの組み合わせのうちコストの小さい n 件です。そのため、1 つの区間だけが最良の結果と異なる結果もあります。best_cost は 1 件目の結果のコストなので、cost_threshold は入力全体に対して適用されます。1 件目の結果は常に segment の出力と同じです。語のない入力は、MeCab と同じく、BOS から EOS への連接コストを持つトークンのない結果を 1 件返します。読み飛ばす空白だけの入力と、v7 からは空の入力（以前は結果なし）がこれにあたります。

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

文分割

ラティスを構築する前に、Linderaは入力テキストを区切り文字（\n、\t、。、、）で文単位に分割し、文ごとに Viterbi ラティスを構築します。文の先頭からおよそ 32 KiB 以内に区切り文字が見つからない場合、Linderaはその位置で強制的に文の境界を区切り、警告をログに出力します。こうして区切ることで、各ラティスのサイズ（ひいてはメモリ・CPU コスト）を制限しています。

\n・\t・入力の終わりは、区間（segment）の終わりになります。区間とは、そこまでの文の並びのことで、区間どうしは互いに独立しています。区間の中では、、・。 と強制的な区切りをまたいで文脈を引き継ぎます。次の文は文頭（BOS）からではなく前の文の最後の語から始まり（その右文脈 ID ごとに、そこまでの最良のパスのコストを引き継ぎます）、文末（EOS）への連接コストは区間の終わりでだけ払います。そのため、区間の最良のパスとそのコストは、区間全体を 1 つのラティスで解いた場合と同じになり、行の中で区切らない MeCab の結果と一致します。v7 より前は、どの文も BOS から始まり EOS で終わっていたため、、 の直後の語は文脈を失っていました。たとえば IPADIC では、彼は、ああ言った の ああ が感動詞になっていましたが、現在は MeCab と同じく副詞になります。

次の場合は、区間全体を 1 つのラティスで解いた結果と異なることがあります。

• 区切りをまたぐ語はできません。UniDic の 一、二塁 のように 、 や 。 を含む見出し語はマッチせず、未知語も区切りをまたいでまとめられず、強制的な区切りをまたぐはずの語はそこで分かれます。
• 強制的な区切りの位置から始まる語には、区切りの直前が空白でも左側空白ペナルティ（左側空白ペナルティ（韓国語）を参照）がかかりません。
• 経路のない文（未知語の候補を作らない文字がある辞書でだけ起きます）があると、その前で区間を終えます。区切りまでの最良の経路を、そこで終わる経路として（文末の連接コストを含めて）確定し、その文は単独で解析します。N-best の 1 件目も同じ経路になります。

通常のテキストが強制的な区切りに達することはありませんが、区切り文字を含まない病的な入力（例えば minify されたテキストや base64 エンコードされたデータなど）に対しては、この人為的な分割位置でトークナイズ結果に影響が出ることがあります。

N-best の探索も同じ区間を使います。N-Best セグメンテーションを参照してください。

再利用可能な 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・set_skip_whitespace・set_max_grouping_len・set_unknown_word_ladder・set_space_penalty・set_space_penalty_from_dictionary で呼び出しごとに設定を切り替えられます。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-segmenter
• lindera-analysis

Lindera Analysis

Lindera Analysisは、lindera-segmenterクレートが提供する形態素セグメンター（Segmenter）の上に、Lucene流のテキスト解析チェーンを重ねるクレートです。通常はlinderaファサード経由でlindera::analysisとして使います（デフォルトで有効なanalysis feature）。文字フィルタ、Segmenter、トークンフィルタを1つのTokenizerパイプラインとして組み合わせ、Rustコードから組み立てることも、YAML設定ファイルだけで組み立てることもできます。

主な特徴

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

依存関係

ファサード経由（推奨）:

[dependencies]
lindera = "7"

#![allow(unused)]
fn main() {
use lindera::analysis::tokenizer::Tokenizer;
}

直接依存にする場合。同じクレートなので、どちらのパスも同じ型を指します。linderaとlindera-analysisのメジャーバージョンは揃えてください（v6 から v7 への移行を参照）:

[dependencies]
lindera = "7"
lindera-analysis = "7"

#![allow(unused)]
fn main() {
use lindera_analysis::tokenizer::Tokenizer;
}

目次

• 設定 -- 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
  # skip_whitespace: false # MeCab と同様に空白をラティス上で読み飛ばす。SudachiDict 以外はデフォルトでオン。false で空白ノードを残す（v7 より前の動作）
  # use_mmap: false # ファイルシステム辞書（embedded:// ではない辞書）にのみ意味がある
  # max_grouping_len: 24 # 未知語のグルーピング長の上限。省略または 0 で無制限
  # unknown_word_ladder: true # 短い未知語候補も生成する（デフォルト: true）
  # space_penalty: false # 左側空白ペナルティ（韓国語）。ルールを同梱する辞書（ko-dic）ではデフォルトでオン。false でオフ、オブジェクトで明示的なルールを指定

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:
      # Merge the numeral tokens only. A counter merged into the number token keeps japanese_number from converting it.
      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つの複合語トークンに結合します。

結合後のトークンの詳細には、辞書スキーマから解決した品詞の位置に new_tag が入ります。それより前の品詞以外のフィールド（SudachiDict の display_surface）と残りのフィールドはすべて * になります。

パラメータ:

例:

{
  "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 つ（辞書スキーマで part_of_speech という名前のフィールドから始まる 4 つ。スキーマにそのフィールドが無い場合は先頭の詳細から）と完全一致で比較されます。IPADIC の助詞トークンは必ず 助詞,係助詞 のようにサブカテゴリを持つため、助詞 単独では一致しません。一方、助動詞はサブカテゴリを持たないため（助動詞,*,*,*）、助動詞 単独で一致します。この動作は japanese_stop_tags、japanese_compound_word、および japanese_number の tags も同様です。位置はスキーマ経由で解決されるため、SudachiDict の display_surface のように品詞の前に列があるスキーマでも同じ規則で一致します。

パラメータ:

例:

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

japanese_number

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

トークンは、その全ての文字が数詞である場合にのみ変換されます（Lucene の JapaneseNumberFilter と同じ規則）。そのため、数詞で始まるだけの通常の語は変換されません。一部は1部にならず一部のままです。

japanese_compound_wordの後段で使う場合は、名詞,数のトークンだけを結合してください。助数詞（名詞,接尾,助数詞）を数値トークンに結合すると、そのトークンは数詞ではなくなるため、一万円は変換されずそのまま残ります。

パラメータ:

例:

{
  "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_compound_word

最初の品詞タグがtagsのいずれかに一致する連続した韓国語トークンを、1つの複合語トークンに結合します。結合後のトークンは先頭トークンのbyte_startとposition、末尾トークンのbyte_endを持ち、position_lengthは結合したトークン数になります。隣接トークンが一致しない単独のトークンはそのままです。

ko-dicは漢数詞を形態素単位に分割するため、이/NR 천/NR 이/NR 십/NR 육/NRをkorean_numberで変換する前に1トークンへ戻すのがこのフィルタの役割です。

パラメータ:

例:

{
  "kind": "korean_compound_word",
  "args": {
    "tags": [
      "SN",
      "NR"
    ],
    "new_tag": "NR"
  }
}

既定の設定では、ko-dicは만 원や십만 원の만を数詞NRと判定するため、십만 원は십만/NR 원/NNBCになります。空白の読み飛ばしを無効にする（skip_whitespace: false）と、만の後ろの語は空白のノードに接続するため、ko-dicはそこでの만を助詞JXと判定し（만/JX 원/NNG）、["SN", "NR"]では結合されません。

korean_decompound

ko-dicの複合語・活用形・事前解析済み（Preanalysis）トークンを、expressionフィールドが示す形態素に分割します。Lucene noriのDecompoundModeと同じ動作で、隣接トークンを結合するkorean_compound_wordの逆操作にあたります。LinderaのMode::Decomposeは日本語の漢字向けに調整された長さペナルティであり、これらのフィールドを読まないため、このフィルタなしでは무궁화はどのモードでも分割されません。

断片のオフセットはnoriに合わせています。自身のバイト範囲を持つのはCompoundの断片だけで、各断片は自身が表すテキストの範囲を持ちます。InflectとPreanalysisの断片はトークン全体の範囲を共有します。活用形の断片は元の表層形の部分文字列とは限らないためです（갔は가 + 았に分解されます）。

Compoundトークンを分割するのは、断片をつなげると表層形とちょうど一致する場合だけで、それ以外は範囲を共有します。これには、断片が表層形そのものの文字列ではない同梱ko-dicの12項目（안지랑역 = 안지 + 역、고춧값 = 고추 + 값）が含まれます。これらではnoriのオフセットが一部の断片を別の文字列に向けてしまいます。프린터3D = 프린터 + 쓰리디のようなユーザー辞書の項目や、先行フィルタが表層形を書き換えた場合も同様です。同梱辞書のそれ以外の項目ではオフセットはnoriと一致し、どのオフセットでテキストを切り出しても安全です。

discardでは断片が複合語自身の位置から連番で並び、mixedでは複合語がその位置にposition_lengthを断片数として残り、断片が同じ位置から続きます。展開後のトークンは増えた位置の分だけ後ろにずれ、それ以外はずれないため、korean_stop_tagsなど先行フィルタが残した位置の隙間は保たれます。

展開するのは位置を1つだけ占めるトークンに限るため、mixedが残した複合語が再び分割されることはありません。それでもフィルタはチェーンに一度だけ入れてください。mixedが残した断片1つの項目は位置を1つしか占めないためです。korean_compound_wordと組み合わせる場合は結合を先に置いてください。結合はバイト範囲の重なるトークンを繋がないため逆順でも壊れませんが、結合を先にするとセグメンターが出したトークンそのものを対象にできます。

断片は自身の品詞タグと意味分類を持ち、複合語自体を説明するフィールド（type、expression、first_part_of_speech、last_part_of_speech、reading、presence_absence）は空になります。読みを空にするのはnoriと同じ挙動で、noriのDecompoundToken.getReading()はnullを返します。korean_reading_formは*をスキップするため、断片は自身の表層形を保ちます。

スキーマにtype/expressionフィールドがない辞書に適用した場合、フィルタは設定されたフィルタごとに一度だけ警告を出し、すべてのトークンをそのまま通過させます。

パラメータ:

例:

{
  "kind": "korean_decompound",
  "args": {
    "mode": "discard",
    "types": [
      "Compound",
      "Inflect",
      "Preanalysis"
    ]
  }
}

korean_keep_tags

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

パラメータ:

例:

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

korean_number

トークンの表層テキストに含まれる漢数詞由来の韓国語の数値表現（ハングル数字、漢数字、全角数字）をアラビア数字に変換します。固有語数詞（하나、둘、열、스물など）は位取りの構造を持たないため変換しません。

変換はトークンごとに独立して行われます。ko-dicは漢数詞を形態素単位に分割するため、1つの数を構成するトークン群が1つのアラビア数字にまとまるわけではありません。

IPADICに対するjapanese_compound_wordのように、変換前にトークンを結合するにはkorean_compound_wordをこのフィルタの前に置きます。結合後のトークンを変換対象にするため、new_tagにはこのフィルタのtagsに含まれるタグを指定します。

[
  {"kind": "korean_compound_word", "args": {"tags": ["SN", "NR"], "new_tag": "NR"}},
  {"kind": "korean_number", "args": {"tags": ["SN", "NR"]}}
]

このチェーンで이천이십육년は2026 년、10만は100000、2천26は2026になります。漢字表記の二千二十六/SHのように数値全体が1トークンの場合は、このフィルタ単体でそのまま変換されます。

パラメータ:

トークンは、その全ての文字が数詞である場合にのみ変換されます（Lucene の KoreanNumberFilter と同じ規則）。これにより固有語数詞が保護されます。일곱（7）は漢数詞の일で始まるため、1文字ずつ変換すると1곱になってしまいます。

ハングルの数詞は他の形態素とも同形で（이は主格助詞、만は補助詞）、これらは1文字なので全文字一致の規則では区別できません。そのため既定では数詞の品詞タグに限定しています。

漢数字も変換する場合はSHを追加してください。対応は2つの意味で部分的です。ko-dicは漢字語全体をNNGと判定するため參加や萬歲は変換されず、一方で単語に結び付かない単独の漢字はSHとなるため、十字架は10 字 架、百貨店は100 貨 店になります。

例:

{
  "kind": "korean_number",
  "args": {
    "tags": [
      "SN",
      "NR"
    ]
  }
}

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/
│   ├── compound.rs                  # 複合語フィルタが共有する結合ヘルパー（非公開）
│   ├── 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_compound_word.rs
│   ├── korean_decompound.rs
│   ├── korean_keep_tags.rs
│   ├── korean_number.rs
│   ├── korean_reading_form.rs
│   ├── korean_stop_tags.rs
│   ├── length.rs
│   ├── lowercase.rs
│   ├── mapping.rs
│   ├── numeral.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ファイルの形式は設定を、フィルタの完全なリファレンスはフィルタを参照してください。

TokenizerBuilder::buildは、設定が指す辞書を読み込みます。TokenizerBuilder::build_with_dictionaries（とTokenizer::from_config_with_dictionaries）は、代わりにバイト列から読み込んだ辞書などの読み込み済みの辞書を受け取り、フィルタを含む設定のほかの項目をすべてその辞書に適用します。渡した辞書が設定の辞書をどう置き換えるかはConfig からの構築を参照してください。WASMバインディングのTokenizerBuilderは、setDictionaryInstance()とsetUserDictionaryInstance()で設定した辞書を渡して、この方法でトークナイザーをビルドします。

AnalysisWorker

AnalysisWorker（Tokenizer::new_workerまたはTokenizer::into_workerで作成）は、解析チェーン全体に対する再利用可能なセッションです。呼び出しごとのバッファ — Viterbiラティスとバックトレース用スクラッチ（SegmentWorker経由）、文字フィルタが操作する正規化テキストバッファ、オフセットマッピング用スクラッチ — をすべて所有するため、tokenizeを繰り返し呼び出してもTokenizer::tokenizeが支払う呼び出しごとのアロケーションを回避できます。文字フィルタが設定されている場合、トークンのsurfaceはトークンごとのStringにコピーされる代わりにワーカーのバッファを借用します。返されるトークンはワーカーを借用するため、次の呼び出しの前に消費する必要があります。マルチスレッドで使う場合はスレッドごとにワーカーを作成してください（あるいはlindera-bindingのように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) — 以降の呼び出しで空白トークンを出力に残すかどうかを設定します。残した空白はラティスにも残るため、他のトークンも変わることがあります。
• set_skip_whitespace(&mut self, skip: bool) — 空白トークンを残さないとき、以降の呼び出しで空白をラティス上で読み飛ばすかどうかを設定します（デフォルトは辞書の設定）。
• set_max_grouping_len(&mut self, max_grouping_len: Option<usize>)・set_unknown_word_ladder(&mut self, unknown_word_ladder: bool) — 以降の呼び出しで使う未知語グルーピングの上限と候補ラダーを設定します。
• set_space_penalty(&mut self, space_penalty: Option<SpacePenaltyConfig>)・set_space_penalty_from_dictionary(&mut self) — 以降の呼び出しで使う左側空白ペナルティのルールを設定するか、辞書のルールに戻します。
• 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 - 学習済みモデルを辞書フォーマットにエクスポート

警告とログメッセージ

どのコマンドも、結果を標準出力に、Lindera のライブラリが出す警告を標準エラー出力に書きます。たとえば tokenize は、文の区切り文字のないテキストが 32 KiB を超えると、そこで文を区切り（文分割を参照）、警告を出します：

% head -c 40000 /dev/zero | tr '\0' a | lindera tokenize --dict embedded://ipadic -o wakati > /dev/null
[WARN  lindera_segmenter::segmenter] no sentence delimiter (\n, \t, 。, 、) found within 32768 bytes from offset 0; forcing a sentence boundary to bound lattice size (see https://github.com/lindera/lindera/issues/871)

環境変数 RUST_LOG で、出すメッセージを選べます。書式は env_logger のものです：

• 指定なし: 警告とエラー
• RUST_LOG=error: エラーだけ。警告は出しません。RUST_LOG=off はログメッセージを一切出しません
• RUST_LOG=debug: デバッグ用のメッセージも出します。たとえば lindera build が読み書きするファイル

この設定で標準出力は変わりません。また、失敗したコマンドのエラーは設定にかかわらず出します。標準エラー出力が端末のときはメッセージに色を付けます。RUST_LOG_STYLE=never で色を消せます。

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: スペース区切りのトークンのみ。入力 1 行につき 1 行（トークンのない行は空行）
  • json: すべてのトークン情報を含む詳細なJSON形式
• --user-dict / -u: ユーザー辞書のパス（オプション）。文脈 ID がシステム辞書の接続コスト行列の範囲外にある見出し語はエラーになります（文脈 ID を参照）。
• --mode / -m: トークナイズモード (デフォルト: normal)
  • normal: 標準的なトークナイズ
  • decompose: 複合語を分解する
• --char-filter / -c: 文字フィルタ設定 (JSON)
• --token-filter / -t: トークンフィルタ設定 (JSON)
• --keep-whitespace: 空白文字のトークンを出力に含める。このとき空白はラティスにも残るため、他のトークンもデフォルトの出力と変わることがある（デフォルトでは空白は出力から除去され、辞書の metadata.json で無効にしていない限り（SudachiDict は無効）、MeCab と同様にラティス上で読み飛ばされる）
• --disable-skip-whitespace: 空白を読み飛ばさず、独立したノード（空白の見出し語か SPACE の未知語）としてラティスに残す（出力からは引き続き除去する。v7 より前の動作）。そのノードの連接コストがすべて 0 の ko-dic では、空白のたびに連接の文脈が途切れる。読み飛ばしは、metadata.json で無効にしていない辞書（SudachiDict は無効）ではデフォルトで有効。--keep-whitespace と併用した場合は効果がない。Segmenter のドキュメントを参照
• --max-grouping-len: 未知語グルーピングの上限（先頭を除いた文字数。MeCab の max-grouping-size に相当し、MeCab のデフォルトは 24）。上限は各位置で判定され、ラン（MeCab と同じく、どの文字も直前の文字と char.def の文字種を共有する連続）が上限を超える位置ではグルーピング候補を出さず、1 文字候補（および候補ラダーと辞書語）が残ります。残りの末尾は上限に収まった時点で再びグルーピングされるため、未知語トークンは最長で上限 + 1 文字になります。0 または省略: 無制限。例は Segmenter のドキュメントを参照
• --disable-unknown-word-ladder: MeCab/Vibrato 由来の未知語候補ラダー（char.def の LENGTH フィールド）を無効化する。デフォルトで有効。無効にすると、v6 より前と同じくこれらの候補を作らない。ただし、グルーピングした未知語の内側から始まる未知語など、その後の変更による出力の違いは残る。Segmenter のドキュメントを参照
• --disable-space-penalty: 辞書の metadata.json に同梱されたルールでデフォルト有効になる左側空白ペナルティ（mecab-ko の left-space-penalty-factor。ko-dic は mecab-ko-dic のルールを同梱）を無効にする。直前に空白があり、先頭品詞タグが一覧にある候補にコストを加算する機能で、--disable-skip-whitespace と併せて無効にすると、空白まわりの韓国語の解析について v6.0 以降に入った 2 つの変更（このペナルティと空白の読み飛ばし）がどちらもオフになる。ただし、." のような記号の連続が分かれるなど、それ以外の出力の変化は残る。Segmenter のドキュメントを参照
• --space-penalty-rules: 辞書のルールの代わりに、明示的な左側空白ペナルティのルールを JSON で指定する。例: '{"rules":[{"pos":["JKS","JX"],"cost":6000}]}'。--disable-space-penalty とは同時に指定できない
• --mmap: 辞書ディレクトリの単語リストにメモリマップドファイル読み込みを使用する。embedded:// 辞書、および mmap feature が無効な場合は無視される。プロセスがマップを保持している間に辞書ディレクトリを再ビルド・切り詰めると、次回のルックアップで SIGBUS を引き起こす可能性がある。
• --nbest / -N: 返す N-best 結果の数（デフォルト: 1）。2以上に設定すると N-best 出力が有効になります。
• --nbest-unique: 同じ分割を生成するパスの重複を排除します。各結果は、その単語境界のパスのうち最もコストの低いものです。
• --nbest-cost-threshold: 最良の結果からの最大コスト差。best_cost + threshold 以内のコストを持つ結果のみが返されます。どちらのコストも入力行全体の合計です。
• 入力ファイル: オプションのファイルパス (デフォルト: 標準入力)。入力は 1 行ずつ読み込まれ、行ごとに解析されます。取り除くのは行末の改行コード（\n または \r\n）だけで、行頭・行末の空白も行の途中と同じに扱います（SPACE の文字である半角空白とタブは読み飛ばして出力から除き、U+3000 は IPADIC・IPADIC-NEologd・UniDic ではトークンになります）。JSON 出力のバイトオフセットは入力行の中の位置を指します。MeCab は CRLF の行の \r も未知語として出力しますが、Lindera は取り除きます

基本的な使用方法

# 辞書ディレクトリを指定してトークナイズ
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 形式

トークンテキストのみをスペース区切りで、入力 1 行につき 1 行（-N では結果 1 件につき 1 行）出力します。空行や空白だけの行のようにトークンのない行は、MeCab と同じく空行になります：

% 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* アルゴリズムに基づいています。

行は \t・。・、 で文に区切られますが、、 と 。 をまたいで文脈を引き継ぐため、タブを含まない行の候補は、行全体の分割のうちコストの小さい N 件です（わずかな例外は文分割を参照）。タブは区間の終わりになります。タブを含む行は区間ごとに探索され、候補は区間ごとに 1 つのパスを選んだ組み合わせのうちコストの小さい N 件です。どの候補も行全体の分割です。

基本的な N-Best の例

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

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

2 位と 3 位は、分割は異なりますがコストは同じ（24541）です。

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

同じ分割が複数のパスに現れる場合（各単語の品詞など、辞書エントリだけが異なる場合）、--nbest-unique を使用して重複を排除します。各結果は、その単語境界のパスのうち最もコストの低いものになります。探索は他のパスをたどりません（短い行でも数百万本になることがあります）:

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

NBEST 1 (cost=15760)
営業 部長 谷川 です
NBEST 2 (cost=17747)
営業 部 長谷川 です
NBEST 3 (cost=18365)
営業 部 長谷 川 です
NBEST 4 (cost=21125)
営業 部 長 谷川 です
NBEST 5 (cost=22259)
営業 部長 谷 川 です

コスト閾値を使用した 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=17747)
営業 部 長谷川 です
NBEST 3 (cost=18365)
営業 部 長谷 川 です

上の例の 4 位のコスト 21125 が 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: システム辞書の代わりにユーザー辞書をビルドする（オプションフラグ）
• --system-dict: ユーザー辞書を組み合わせるシステム辞書。ディレクトリのパス、URI、ダウンロード済みの辞書名のいずれかで、tokenize --dict と同じ形で指定する（オプション。--user のときだけ）。指定すると、各行の文脈 ID をそのシステム辞書の接続コスト行列と照らし合わせて確認します（文脈 ID の確認 を参照）
• --context-id-freq / -f: 接続コストIDの並び替えに使用するコンテキストID アクセス頻度ファイル（オプション。辞書の metadata.json で connection_id_mapping: true が設定されている場合にのみ意味を持ちます）

辞書の種類

システム辞書 (System dictionary)

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

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

ユーザー辞書 (User dictionary)

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

文脈 ID の確認

システム辞書をビルドするとき、lindera build は MeCab の mecab-dict-index と同じく、すべての文脈 ID が接続コスト行列の範囲内にあることを確認します。lex.csv の各行と unk.def の各行で、右文脈 ID は matrix.def のヘッダの 1 つ目の値より小さく、左文脈 ID は 2 つ目の値より小さくなければなりません。これに反する辞書はビルドに失敗し、エラーはファイル・行・ID・行列の大きさを示します。たとえば 2 x 2 の matrix.def で、lex.csv の 2 行目の右文脈 ID が 2 の場合は次のとおりです：

Error: LinderaError { kind: Content, source: ./dict-source/lex.csv: line 2: right context id 2 is out of range for the connection matrix (matrix.def size 2 2; right context ids must be below 2) }

• 辞書の metadata.json で skip_invalid_cost_or_id が true の場合は、そうした lex.csv の行を取り除き、標準エラー出力に警告を出します（警告とログメッセージを参照）。unk.def の行は常に確認します。
• ID が軸の範囲外にある matrix.def の行もエラーになり、フィールドが 4 つ未満の unk.def の行もエラーになります。
• ユーザー辞書（--user）を確認するのは、組み合わせるシステム辞書を --system-dict で指定したときだけです（次の段落を参照）。

--system-dict を指定すると、lindera build --user はユーザー辞書の各行を、そのシステム辞書の接続コスト行列と同じ範囲で照らし合わせて確認します。簡易形式の行は、metadata.json の既定の文脈 ID（default_left_context_id と default_right_context_id）で確認します。行列の範囲外にある最初の行でビルドは失敗し、エラーはその行の CSV の行番号と表層形を示します。.bin ファイルは書き出しません。たとえば IPADIC の 1316 x 1316 の行列に対して、userdic.csv の 2 行目の左文脈 ID が 60000 の場合は次のとおりです：

% lindera build --src ./userdic.csv --dest ./user_dict --metadata ./lindera-ipadic/metadata.json --user --system-dict embedded://ipadic
Error: LinderaError { kind: Content, source: user dictionary line 2 (surface: '東京スカイツリー'): left context id 60000 is out of range for the connection matrix (matrix.def size 1316 1316; left context ids must be below 1316) }

--system-dict を指定しないと、ビルドの時点では組み合わせるシステム辞書が分からないため、ユーザー辞書はそのままビルドされます。その後 lindera tokenize --user-dict がシステム辞書と照らし合わせて確認し、行列の範囲外にある最初の見出し語を単語 ID で示すエラーで失敗します（文脈 ID を参照）。lindera tokenize --user-dict に .csv を渡すと、読み込むときに --dict のシステム辞書に合わせてビルドするため、--system-dict と同じく CSV の行番号と表層形を示すエラーになります。

matrix.def にないセル

matrix.def は、すべてのセルを列挙しなくてもかまいません。lindera build は、matrix.def が列挙していないセルのコストを、MeCab の mecab-dict-index と同じく 0 にします。v6.2.0 までは、そうしたセルのコストは 32767（i16::MAX）で、その接続は非常に高いコストになっていました。たとえば次の matrix.def では、右文脈 ID 1 から左文脈 ID 0 と 1 への接続のコストが 10 と 20 になり、残りの 7 つのセルのコストは 0 になります。

3 3
1 0 10
1 1 20

同梱の辞書と、lindera export が書き出す matrix.def は、すべてのセルを列挙しているため、この規則で変わることはありません。

char.def と unk.def の確認

システム辞書をビルドするとき、lindera build は mecab-dict-index と同じく、char.def と unk.def を互いに照らし合わせて確認します：

• char.def の範囲行が指すカテゴリは、それより前の行で定義されていること
• 各カテゴリの定義は 1 回だけであること
• unk.def の各行が、char.def で定義したカテゴリを指すこと
• char.def の各カテゴリに、unk.def の行が 1 行以上あること

どれかに反する辞書はビルドに失敗し、エラーはファイルとカテゴリを示します。unk.def の行がないカテゴリ以外では、行も示します。以前はこうした辞書もビルドでき、その後の lindera tokenize は、未定義のカテゴリの文字で panic したり、一部のカテゴリに別のカテゴリの設定を使ったり、どの単語にも未知語にも覆われない文字の手前で出力を打ち切ったり、unk.def の行を無視したりしていました。たとえば、char.def が SPACE カテゴリを定義し、unk.def に SPACE の行がない場合は、次のようになります：

Error: LinderaError { kind: Content, source: ./dict-source/unk.def: no line for category SPACE, which char.def defines; every char.def category needs at least one unk.def line }

lindera train も、学習の前に --char-def と --unk-def を同じように確認します（学習パイプラインを参照）。

例

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 \
  --context-id-freq ./lindera-unidic/context_id_freq.txt

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 \
  --context-id-freq ./lindera-ko-dic/context_id_freq.txt

ユーザー辞書のビルド

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

--system-dict embedded://ipadic（またはビルド済みの IPADIC のパス）を加えると、各行の文脈 ID を IPADIC の接続コスト行列と照らし合わせて確認します（文脈 ID の確認 を参照）。

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,名詞,接尾,一般,*,*,*,人,ジン,ジン

このファイルは、lindera build が lex.csv を読むのと同じく CSV として読みます。フィールドは引用符で囲め（",",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. 学習結果

lindera train はモデルを --output のファイルに書き出します。学習用のラティスを作り終えると、コーパスの正解トークンのラベルの付き方を出力します（学習のしくみを参照）。./resources/training/ のファイルでは次のとおりです：

Lattice statistics: gold_lexicon=14 gold_unknown=0 gold_virtual=0 virtual_labels=0 negative_lexicon=0 negative_unknown=17

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

• シード辞書の語: シード辞書のすべてのレコード（学習された重みと文脈 ID 付き）
• 未知語: unk.def のすべてのエントリをファイル順に（学習された重みと文脈 ID 付き）

シード辞書にないコーパスの語は、語として追加されません。それらは unk.def のエントリか、学習されるもののエクスポートされない仮想ラベルを通じて学習されます。

export

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

エクスポートパラメータ

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

出力ファイル

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

• lex.csv: 学習された重みを持つ語彙ファイル（MeCab互換の tocost() によるコスト変換）
• matrix.def: モデルの文脈 ID と BOS/EOS 用の 0 の全 (right_id, left_id) ペアを網羅する密な接続コスト行列。学習した重みがないペアのコストは、学習中や MeCab と同じく 0
• unk.def: 未知語定義。学習の入力の unk.def のエントリごとに 1 行を、同じ順序で書き出す
• char.def: 文字種定義
• feature.def: 素性テンプレート定義（学習済みモデルからコピー）
• rewrite.def: 素性リライトルール（学習済みモデルからコピー）
• left-id.def: 左文脈IDから素性文字列へのマッピング
• right-id.def: 右文脈IDから素性文字列へのマッピング
• metadata.json: 更新されたメタデータファイル（--metadata オプションが指定された場合）

モデルの形式バージョン

lindera export が読み込めるのは、現在の形式バージョン（2.0.0）のモデルだけです。それより前のバージョンで書かれた model.dat（7.0.0 より前に書かれたものはすべて該当）は拒否されるため、lindera train で学習し直す必要があります。6.1.0 の CLI で学習したモデルでは次のとおりです：

Error: LinderaError { kind: Deserialize, source: failed to deserialize model: failed without error information; enable debug assertions and the `alloc` feature in rancor for error information. The file is not a legacy JSON model either, so it was most likely written by a different version of lindera-trainer; re-run `lindera train` to regenerate it. }

完全なワークフロー例

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

これ	名詞,代名詞,一般,*,*,*,これ,コレ,コレ
は	助詞,係助詞,*,*,*,*,は,ハ,ワ
外国	名詞,一般,*,*,*,*,外国,ガイコク,ガイコク
人	名詞,接尾,一般,*,*,*,人,ジン,ジン
参政	名詞,サ変接続,*,*,*,*,参政,サンセイ,サンセイ
権	名詞,接尾,一般,*,*,*,権,ケン,ケン
です	助動詞,*,*,*,特殊・デス,基本形,です,デス,デス
。	記号,句点,*,*,*,*,。,。,。
EOS

メタデータ更新機能

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

1. ベースとなる metadata.json ファイルを読み込み、既存の設定を保持します
2. 特定のフィールドを学習済みモデルの値で更新します：
   • default_word_cost: 素性重みの中央値から計算された値
   • model_info: 素性数、ラベル数、行列サイズ（connection_matrix_size。matrix.def の大きさを行数 x 列数で表す）、実際に回った学習の反復回数（training_iterations。--max-iterations 以下）、正則化、モデルの形式バージョンを含む学習統計情報。タイムスタンプは書き込まれないため、同じモデルを 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

ホイールの対象は、CPython 3.10〜3.15 の Linux（x86_64 と aarch64、glibc）、macOS（x86_64 と arm64）、Windows（x64 と arm64）です。それ以外の環境（musl ベースの Linux（Alpine）、ほかの CPU アーキテクチャ、free-threaded 版 CPython など）では、pip install lindera がソース配布物（sdist）からパッケージをビルドします。このビルドには Rust ツールチェーン 1.89 以降（rustup でインストール）と cc などの C リンカが必要で、数分かかります。

[!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.15 まで）
• 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, penalty=None)

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

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

penalty は "decompose" モードが使う Penalty です。None（デフォルト）では既定のペナルティを使います。"normal" とペナルティを一緒に渡すと ValueError が、Penalty でない値を渡すと TypeError が送出されます。

builder.set_mode("normal")
builder.set_mode("decompose", Penalty(kanji_penalty_length_penalty=0))

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.csv")

set_keep_whitespace(keep)

出力に空白トークンを含めるかどうかを制御します。残した空白はラティスにも残るため、他のトークンも、MeCab と同様に空白をラティス上で読み飛ばすデフォルトの出力と変わることがあります。空白を出力せずにラティスにだけ残すには、代わりに set_skip_whitespace(False) を使います。

builder.set_keep_whitespace(True)

set_skip_whitespace(skip)

空白をラティス上で読み飛ばすかどうかを設定します。skip の意味は設定ファイルの segmenter.skip_whitespace と同じです：

• True -- 空白を読み飛ばし、MeCab と同様に空白の前後の語を直接接続します。
• False -- 空白を独立したノード（空白の見出し語か SPACE の未知語）としてラティスに残します（v7 より前の動作）。空白は引き続き出力から除外されます。
• None -- 辞書の metadata.json のデフォルトです。SudachiDict 以外では読み飛ばします。以前の呼び出しを取り消すときに使います。

ここで設定した値は、辞書のデフォルトと、from_file で読み込んだ skip_whitespace より優先されます。空白トークンを残すとき（set_keep_whitespace(True)）は効果がありません。残した空白は常にラティスに残るためです。それ以外の値では TypeError が送出されます。

たとえば IPADIC では、Google が 新しい の が は、デフォルトでは助詞（助詞）、set_skip_whitespace(False) では接続詞（接続詞）と解析されます。詳しくは Segmenter を参照してください。

# v7 より前と同じく、空白をラティスに残す
builder.set_skip_whitespace(False)

set_space_penalty(value)

韓国語向けの左側空白ペナルティ（left-space penalty）を設定します。直前に空白がある候補のうち、本来は前の語に空白なしで付く品詞（助詞、語尾など）の候補にコストを加算します。value の意味は設定ファイルの segmenter.space_penalty と同じです：

• None -- デフォルト。辞書が metadata.json に同梱するルールがあればそれを使います（ko-dic は mecab-ko-dic のルールを同梱し、他の同梱辞書はルールを持ちません）。以前の呼び出しを取り消すときにも使います。
• False -- ペナルティをオフにします。
• True -- 辞書のルールを要求します。ルールを同梱しない辞書では build() が ValueError を送出します。
• {"rules": [{"pos": [...], "cost": n}, ...]} 形式の dict -- 辞書のルールの代わりにこのルールを適用します。先頭品詞タグが pos に含まれる候補に cost を加算し、最初に一致したルールが使われます。

それ以外の値では ValueError が送出されます（任意のオブジェクトなど JSON に対応しない値は、append_token_filter と同様に TypeError になります）。

# ペナルティをオフにする
builder.set_space_penalty(False)

# 明示的なルール
builder.set_space_penalty({
    "rules": [
        {"pos": ["EC", "EF", "EP", "ETM", "ETN", "VCP", "XSA", "XSN", "XSV"], "cost": 3000},
        {"pos": ["JC", "JKB", "JKC", "JKG", "JKO", "JKQ", "JKS", "JKV", "JX"], "cost": 6000},
    ]
})

[!NOTE] v6.1.0 から、ko-dic では mecab-ko と同じく左側空白ペナルティがデフォルトで適用されます。たとえば 검색 이 잘 된다 の 이 は感動詞 IC と解析されます（ペナルティがなければ主格助詞 JKS）。オフにするには builder.set_space_penalty(False) を呼び出してください。ルールを同梱しているのは Lindera 6.1.0 以降でビルドした ko-dic だけです。v6.0.0 リリースの ko-dic ではペナルティはオフのままで、辞書を再ビルドするまで True はエラーになります。詳しくは Segmenter を参照してください。

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", {})

set_space_penalty、append_character_filter、append_token_filter の引数は、list と dict の入れ子が 128 段までです。それより深い値や、自分自身を含む値を渡すと ValueError が送出されます。

ビルド

build()

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

tokenizer = builder.build()

Tokenizer

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

Tokenizer の作成

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

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

space_penalty には TokenizerBuilder.set_space_penalty と同じ値を渡せます。None（デフォルト）では辞書が同梱する左側空白ペナルティのルールを使うため、ko-dic ではペナルティがオンになります。オフにするには False を渡します。不正な設定では、set_space_penalty や build() と同じエラーが送出されます。

penalty には、TokenizerBuilder.set_mode と同じく "decompose" モードの Penalty を渡せます。エラーも set_mode と同じです。

from lindera import Tokenizer, load_dictionary

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

# 左側空白ペナルティなしの ko-dic
ko_tokenizer = Tokenizer(load_dictionary("embedded://ko-dic"), space_penalty=False)

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"）を受け取ります。decompose モードのペナルティは、 それぞれの penalty 引数で渡します（下記 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 の使い方

Penalty は "decompose" と一緒に TokenizerBuilder.set_mode() か Tokenizer のコンストラクタ に渡します。長さのペナルティをなくすと、decompose モードでも長い語が分割されずに残ります。

from lindera import Penalty, Tokenizer, TokenizerBuilder, load_dictionary

text = "関西国際空港限定トートバッグ"
penalty = Penalty(kanji_penalty_length_penalty=0, other_penalty_length_penalty=0)

builder = TokenizerBuilder().set_dictionary("embedded://ipadic")
tokenizer = builder.set_mode("decompose").build()
print([token.surface for token in tokenizer.tokenize(text)])
# ['関西', '国際', '空港', '限定', 'トートバッグ']

tokenizer = builder.set_mode("decompose", penalty).build()
print([token.surface for token in tokenizer.tokenize(text)])
# ['関西国際空港', '限定', 'トートバッグ']

tokenizer = Tokenizer(load_dictionary("embedded://ipadic"), mode="decompose", penalty=penalty)
print([token.surface for token in tokenizer.tokenize(text)])
# ['関西国際空港', '限定', 'トートバッグ']

"normal" モードと一緒に Penalty を渡すと ValueError が送出されます。

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 オブジェクト全体

ユーザー辞書は、組み合わせるシステム辞書と同じメタデータ（スキーマ、 エンコーディングなど）を共有する必要があります。load_user_dictionary_for は システム辞書を受け取り、そのメタデータを使います。 lindera-python/examples/tokenize_with_userdict.py とユーザー辞書を参照してください。

ユーザー辞書

ユーザー辞書はシステム辞書にカスタム語彙を追加します。組み合わせるシステム辞書に 合わせて読み込みます：

from lindera import load_dictionary, load_user_dictionary_for

dictionary = load_dictionary("/path/to/ipadic")
user_dict = load_user_dictionary_for("/path/to/user_dictionary.csv", dictionary)

.csv はシステム辞書のメタデータでビルドし、ビルドしながら接続コスト行列と 照らして確認します。文脈 ID が行列の範囲外にある行は、その CSV の行番号と表層形を 示す ValueError になります（文脈 ID を参照）。.bin はビルドされたとおりに読み込みます。

load_user_dictionary(uri, metadata) は、メタデータだけでユーザー辞書を 読み込みます。この方法で読み込んだ .csv はシステム辞書と組み合わせるときに 確認し、エラーは見出し語をその単語 ID で示します：

from lindera import load_user_dictionary, Metadata

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

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

from lindera import Tokenizer, load_dictionary, load_user_dictionary_for

dictionary = load_dictionary("/path/to/ipadic")
user_dict = load_user_dictionary_for("/path/to/user_dictionary.csv", dictionary)

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.csv")
    .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 など）が含まれている必要があります。

Metadata.from_json_file で読み込んだメタデータは metadata.json の space_penalty ルールを保持し、ビルドした辞書にもそのルールが同梱されます。そのため ko-dic をビルドした場合も、左側空白ペナルティはデフォルトでオンのままです。トークナイザーごとにオフにするには TokenizerBuilder.set_space_penalty(False) を使います（Tokenizer API を参照）。コンストラクタで作成した Metadata はルールを持ちません。

ユーザー辞書のビルド

組み合わせるシステム辞書に合わせて、CSV ファイルからユーザー辞書をビルドします：

from lindera import build_user_dictionary_for, load_dictionary, load_user_dictionary_for

dictionary = load_dictionary("/path/to/ipadic")
build_user_dictionary_for("user_words.csv", "/path/to/user_dictionary.bin", dictionary)
user_dict = load_user_dictionary_for("/path/to/user_dictionary.bin", dictionary)

CSV はシステム辞書のメタデータでビルドし、接続コスト行列と照らして確認します。 文脈 ID が行列の範囲外にある行は、その CSV の行番号と表層形を示す ValueError になり、ファイルは書き出しません（文脈 ID を参照）。2 番目の引数は書き出すファイルのパスです。ローダーは拡張子で ユーザー辞書の読み込み方を決めるので、.bin で終えてください。

build_user_dictionary(kind, input_file, output_dir, metadata) は、メタデータ だけでユーザー辞書をビルドします。output_dir も、名前に反してディレクトリでは なく、書き出すファイルのパスです。各行はシステム辞書と組み合わせるときに確認し、 エラーは見出し語をその単語 ID で示します：

from lindera import build_user_dictionary, Metadata

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

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

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

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

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()

メタデータを文字列の dict として返します。上記のプロパティを含み、2 つのスキーマは dictionary_schema_fields と user_dictionary_schema_fields（カンマ区切りのフィールド名）として格納されます：

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

ko-dic のようにメタデータが左側空白ペナルティのルールを持つ場合、dict にはそのルールを JSON 文字列で保持する space_penalty エントリも含まれます。ルールがない場合、このキーはありません：

metadata = Metadata.from_json_file("/path/to/ko-dic/metadata.json")
metadata.to_dict()["space_penalty"]
# '{"rules":[{"pos":["EC","EF",...],"cost":3000},{"pos":["JC","JKB",...],"cost":6000}]}'

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 つ（辞書スキーマで part_of_speech という名前のフィールドから始まる 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",
)

エクスポートパラメータ

エクスポートにより、出力ディレクトリに以下のファイルが作成されます。lindera export が作成するファイルと同じです：

• lex.csv -- 学習済みコスト付きのレキシコンエントリー
• matrix.def -- 連接コスト行列
• unk.def -- 未知語定義
• char.def -- 文字カテゴリ定義（学習済みモデルからコピー）
• feature.def -- 素性テンプレート定義（学習済みモデルからコピー）
• rewrite.def -- 素性リライトルール（学習済みモデルからコピー）
• left-id.def -- 左文脈IDから素性文字列へのマッピング
• right-id.def -- 右文脈IDから素性文字列へのマッピング
• metadata.json -- 更新されたメタデータ（metadata パラメータ指定時）

モデルファイルは、このバージョンの学習で作ったものである必要があります。それより前のバージョンで書かれたモデルファイル（7.0.0 より前に書かれたものはすべて該当）は拒否され、lindera.export() は学習のやり直しを求めるエラーで失敗します。そうしたモデルは lindera.train() で学習し直してください。

完全なワークフロー

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

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, penalty?)

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

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

penalty は "decompose" モードが使う Penalty オブジェクトです。null または undefined（デフォルト）では既定のペナルティを使います。"normal" とペナルティを一緒に渡すと、不正なモードと同じくエラーを投げます。オブジェクトでない値や、範囲内の整数でないフィールドを渡すと、InvalidArg のエラーを投げます。

builder.setMode("normal");
builder.setMode("decompose", { kanjiPenaltyLengthPenalty: 0 });

setDictionary(path)

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

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

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

setUserDictionary(uri)

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

builder.setUserDictionary("/path/to/user_dictionary.csv");

setKeepWhitespace(keep)

出力に空白トークンを含めるかどうかを制御します。残した空白はラティスにも残るため、他のトークンも、MeCab と同様に空白をラティス上で読み飛ばすデフォルトの出力と変わることがあります。空白を出力せずにラティスにだけ残すには、代わりに setSkipWhitespace(false) を使います。

builder.setKeepWhitespace(true);

setSkipWhitespace(skip)

空白をラティス上で読み飛ばすかどうかを設定します。値の意味は設定ファイルの segmenter.skip_whitespace と同じです。

ここで設定した値は、辞書のデフォルトと、fromFile で読み込んだ skip_whitespace より優先されます。空白トークンを残すとき（setKeepWhitespace(true)）は効果がありません。残した空白は常にラティスに残るためです。引数は省略できず、それ以外の値を渡すと Error を投げます。

たとえば IPADIC では、Google が 新しい の が は、デフォルトでは助詞（助詞）、setSkipWhitespace(false) では接続詞（接続詞）と解析されます。詳しくは Segmenter を参照してください。

// v7 より前と同じく、空白をラティスに残す
builder.setSkipWhitespace(false);

// 辞書のデフォルトに戻す
builder.setSkipWhitespace(null);

setSpacePenalty(value)

韓国語向けの左側空白ペナルティ（mecab-ko の left-space-penalty-factor）を設定します。直前に空白があり、先頭品詞タグがルールの一覧にある候補に、そのルールのコストを加算します。値の意味は設定ファイルの segmenter.space_penalty と同じです。

それ以外の値を渡すと Error を投げます。

// ペナルティをオフにする
builder.setSpacePenalty(false);

// 明示的なルール（ko-dic が同梱するルールと同じ）
builder.setSpacePenalty({
  rules: [
    { pos: ["EC", "EF", "EP", "ETM", "ETN", "VCP", "XSA", "XSN", "XSV"], cost: 3000 },
    { pos: ["JC", "JKB", "JKC", "JKG", "JKO", "JKQ", "JKS", "JKV", "JX"], cost: 6000 },
  ],
});

// 辞書のデフォルトに戻す
builder.setSpacePenalty(null);

[!NOTE] v6.1.0 以降、ko-dic では左側空白ペナルティがデフォルトで適用されます。ko-dic の metadata.json が mecab-ko-dic のルールを同梱しているためです。これにより韓国語の出力が変わります（例: 검색 이 잘 된다 の 이 は、ペナルティがあると感動詞 IC、なければ主格助詞 JKS になる）。オフにするには setSpacePenalty(false) を呼び出してください。直接作成する Tokenizer では、4 番目の引数に false を渡します（new Tokenizer(dictionary, "normal", null, false)）。v6.0.0 リリースからダウンロードした ko-dic はルールを同梱していないため、その辞書ではペナルティはオフのままで、setSpacePenalty(true) を指定すると build() が例外を投げます。詳細は Segmenter を参照してください。

appendCharacterFilter(kind, args?)

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

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

appendTokenFilter(kind, args?)

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

builder.appendTokenFilter("lowercase", {});

setSpacePenalty、appendCharacterFilter、appendTokenFilter の引数は、配列とオブジェクトの入れ子が 128 段までです。それより深い値や、自分自身を含む値を渡すと Error を投げます。

ビルド

build()

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

const tokenizer = builder.build();

Tokenizer

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

Tokenizer の作成

new Tokenizer(dictionary, mode?, userDictionary?, spacePenalty?, penalty?)

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

spacePenalty には setSpacePenalty と同じ値を渡せます。null または undefined（デフォルト）では、辞書が同梱する左側空白ペナルティのルールを使います。不正な設定では、setSpacePenalty や build() と同じくエラーを投げます。

penalty には、setMode と同じく "decompose" モードの Penalty を渡せます。エラーも setMode と同じです。

const { Tokenizer, loadDictionary } = require("lindera");

const dictionary = loadDictionary("embedded://ipadic");
const tokenizer = new Tokenizer(dictionary, "normal");

// 左側空白ペナルティなしの ko-dic
const koTokenizer = new Tokenizer(loadDictionary("embedded://ko-dic"), "normal", null, false);

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

TokenizerBuilder.setMode() と Tokenizer のコンストラクタは、モードを単純な文字列 （"normal" または "decompose"）で、decompose モードのペナルティを Penalty オブジェクトで受け取ります。

Mode

2つの値を持つ文字列列挙型です：

• Mode.Normal -- 辞書コストに基づく標準的なトークナイズ
• Mode.Decompose -- ペナルティベースの複合語分解

Penalty

decompose モードのペナルティパラメータを持つプレーンなオブジェクト（TypeScript の型は Penalty）です。フィールドはすべて省略でき、省略したフィールドはデフォルト値になります：

"decompose" と一緒に setMode() か Tokenizer のコンストラクタ に渡します。長さのペナルティをなくすと、decompose モードでも長い語が分割されずに残ります：

const { Tokenizer, TokenizerBuilder, loadDictionary } = require("lindera");

const text = "関西国際空港限定トートバッグ";
const penalty = { kanjiPenaltyLengthPenalty: 0, otherPenaltyLengthPenalty: 0 };
const surfaces = (tokenizer) => tokenizer.tokenize(text).map((token) => token.surface);

const builder = new TokenizerBuilder().setDictionary("embedded://ipadic");
console.log(surfaces(builder.setMode("decompose").build()));
// [ '関西', '国際', '空港', '限定', 'トートバッグ' ]

console.log(surfaces(builder.setMode("decompose", penalty).build()));
// [ '関西国際空港', '限定', 'トートバッグ' ]

const tokenizer = new Tokenizer(loadDictionary("embedded://ipadic"), "decompose", null, null, penalty);
console.log(surfaces(tokenizer));
// [ '関西国際空港', '限定', 'トートバッグ' ]

"normal" モードと一緒にペナルティを渡すとエラーを投げます。

辞書管理

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 { loadDictionary, loadUserDictionaryFor } = require("lindera");

const dictionary = loadDictionary("/path/to/ipadic");
const userDict = loadUserDictionaryFor("/path/to/user_dictionary.csv", dictionary);

.csv はシステム辞書のメタデータでビルドし、ビルドしながら接続コスト行列と 照らして確認します。文脈 ID が行列の範囲外にある行は、その CSV の行番号と表層形を 示すエラーになります（文脈 ID を参照）。.bin はビルドされたとおりに読み込みます。

loadUserDictionary(uri, metadata) は、メタデータだけでユーザー辞書を 読み込みます。この方法で読み込んだ .csv はシステム辞書と組み合わせるときに 確認し、エラーは見出し語をその単語 ID で示します：

const { loadUserDictionary, Metadata } = require("lindera");

const metadata = new Metadata();
const userDict = loadUserDictionary("/path/to/user_dictionary.csv", metadata);

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

const { Tokenizer, loadDictionary, loadUserDictionaryFor } = require("lindera");

const dictionary = loadDictionary("/path/to/ipadic");
const userDict = loadUserDictionaryFor("/path/to/user_dictionary.csv", dictionary);

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.csv");
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 など）が含まれている必要があります。

辞書の metadata.json に含まれる設定のままビルドするには、Metadata.fromJsonFile() でファイルを読み込み、その結果を渡します。ファイルの space_penalty ルールは保持されるため、この方法でビルドした ko-dic では左側空白ペナルティがデフォルトで適用されます（setSpacePenalty を参照）。new Metadata(...) で作成した Metadata はルールを持ちません。

const metadata = Metadata.fromJsonFile("/path/to/lindera-ko-dic/metadata.json");
buildDictionary("/path/to/mecab-ko-dic", "/path/to/output_dir", metadata);

ユーザー辞書のビルド

組み合わせるシステム辞書に合わせて、CSV ファイルからユーザー辞書をビルドします：

const { buildUserDictionaryFor, loadDictionary, loadUserDictionaryFor } = require("lindera");

const dictionary = loadDictionary("/path/to/ipadic");
buildUserDictionaryFor("user_words.csv", "/path/to/user_dictionary.bin", dictionary);
const userDict = loadUserDictionaryFor("/path/to/user_dictionary.bin", dictionary);

CSV はシステム辞書のメタデータでビルドし、接続コスト行列と照らして確認します。 文脈 ID が行列の範囲外にある行は、その CSV の行番号と表層形を示すエラーを投げ、 ファイルは書き出しません（文脈 ID を参照）。2 番目の引数は書き出すファイルのパスです。ローダーは拡張子で ユーザー辞書の読み込み方を決めるので、.bin で終えてください。

buildUserDictionary(kind, inputFile, outputDir, metadata) は、メタデータだけで ユーザー辞書をビルドします。outputDir も、名前に反してディレクトリではなく、 書き出すファイルのパスです。各行はシステム辞書と組み合わせるときに確認し、 エラーは見出し語をその単語 ID で示します：

const { buildUserDictionary, Metadata } = require("lindera");

const metadata = new Metadata();
buildUserDictionary("ipadic", "user_words.csv", "/path/to/user_dictionary.bin", metadata);

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

buildUserDictionary("ipadic", "user_words.csv", "/path/to/user_dictionary.bin");

[!NOTE] 第一引数（kind）は現状未使用です -- 将来の拡張のために予約されており、ビルド結果には 影響しません。現時点では任意の文字列を渡しても問題ありません。システム辞書に合わせて ビルドするには buildUserDictionaryFor を使います。

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());

メタデータが左側空白ペナルティのルールを持つ場合（ko-dic の metadata.json から読み込んだ場合など）、オブジェクトにはルールを JSON 文字列で保持する spacePenalty エントリーも含まれます。ルールを持たない場合、このキーはありません。

const koDic = Metadata.fromJsonFile("/path/to/lindera-ko-dic/metadata.json");
const { rules } = JSON.parse(koDic.toObject().spacePenalty);
console.log(rules[1].pos); // ["JC", "JKB", "JKC", "JKG", "JKO", "JKQ", "JKS", "JKV", "JX"]

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 が提供する全フィルタ（パラメータ・使用例を含む）の正式なカタログについてはフィルタを参照してください。

文字フィルタ

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

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 つ（辞書スキーマで part_of_speech という名前のフィールドから始まる 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",
});

エクスポートパラメータ

エクスポートにより、出力ディレクトリに以下のファイルが作成されます。lindera export が作成するファイルと同じです：

• lex.csv -- 学習済みコスト付きのレキシコンエントリー
• matrix.def -- 連接コスト行列
• unk.def -- 未知語定義
• char.def -- 文字カテゴリ定義（学習済みモデルからコピー）
• feature.def -- 素性テンプレート定義（学習済みモデルからコピー）
• rewrite.def -- 素性リライトルール（学習済みモデルからコピー）
• left-id.def -- 左文脈IDから素性文字列へのマッピング
• right-id.def -- 右文脈IDから素性文字列へのマッピング
• metadata.json -- 更新されたメタデータ（metadata パラメータ指定時）

モデルファイルは、このバージョンの学習で作ったものである必要があります。それより前のバージョンで書かれたモデルファイル（7.0.0 より前に書かれたものはすべて該当）は拒否され、exportModel() は学習のやり直しを求めるエラーで失敗します。そうしたモデルは train() で学習し直してください。

完全なワークフロー

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

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 モデルの学習と辞書のエクスポート

インストール

v6.1.0 以降の lindera-ruby は、RubyGems から lindera としてインストールできます。ソース gem のため、gem install の実行時に同梱の Rust ソースからネイティブ拡張をコンパイルします（数分かかります）。

前提条件

• Ruby 3.1 以降と、ネイティブ gem のビルドに必要なツール（C コンパイラと make）
• Rust ツールチェーン 1.89 以降 -- rustup 経由でインストール
• libclang -- Debian/Ubuntu は libclang-dev、macOS は Xcode コマンドラインツール
• Bundler -- ソースからビルドする場合のみ（gem install bundler）

RubyGems からのインストール

gem install lindera

または Gemfile に追加します：

gem "lindera"

[!NOTE] lindera v6.1.0 以降を使用してください。v6.1.0 より前に公開された lindera gem は、インストール時のコンパイルに失敗します。それらのバージョンは、以下の手順でソースからビルドしてください。

gem は crates.io 上の同じバージョンの lindera と lindera-binding に対してコンパイルされます（この 2 つはバージョンを完全に固定しています）。gem には Cargo.lock が含まれないため、それ以外の依存（ほかの lindera-* クレートを含む）は、インストール時に互換性のある最新のリリースに解決されます。デフォルトの feature（train）のみを有効にし、辞書は埋め込みません。辞書は辞書の入手を参照してください。その他の Feature フラグを有効にするには、インストール時に LINDERA_FEATURES を指定します：

LINDERA_FEATURES="embed-ipadic" gem install lindera

辞書の入手

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 スイートの両方が実行されます。

gem のビルド

bundle exec rake build（または make package-lindera-ruby）は、ソース gem を lindera-ruby/pkg/ に出力します。cargo package が正規化したクレートを同梱するため、 gem はこのリポジトリの外でも、crates.io 上の同じバージョンの lindera と lindera-binding に対してコンパイルできます。gem build を直接実行しないで ください。クレート自身の Cargo.toml は Cargo ワークスペースの中でしか解決できません。

make test-lindera-ruby-gem（Docker が必要）は、gem をビルドし、クリーンな ruby コンテナで gem install を実行して、テキストをトークナイズします。このテストは lindera クレートをチェックアウトからコンパイルするため、crates.io に未公開の バージョンでも実行できます。

学習機能付きビルド

train feature は、CRF ベースの辞書学習機能を有効にします。デフォルトで有効です：

LINDERA_FEATURES="train" bundle exec rake compile

Feature フラグ

Feature は環境変数 LINDERA_FEATURES にカンマ区切りリストで指定します。bundle exec rake compile と gem install のどちらでも使えます。

複数の 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, penalty: nil)

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

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

キーワード引数 penalty: には、"decompose" モードが使う Lindera::Penalty を渡します。nil（デフォルト）では既定のペナルティを使います。"normal" とペナルティを一緒に渡すと、不正なモードと同じく RuntimeError が、Lindera::Penalty でない値を渡すと TypeError が発生します。

builder.set_mode('normal')
builder.set_mode('decompose', penalty: Lindera::Penalty.new(nil, 0, nil, nil))

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.csv')

set_keep_whitespace(keep)

出力に空白トークンを含めるかどうかを制御します。残した空白はラティスにも残るため、他のトークンも、MeCab と同様に空白をラティス上で読み飛ばすデフォルトの出力と変わることがあります。空白を出力せずにラティスにだけ残すには、代わりに set_skip_whitespace(false) を使います。

builder.set_keep_whitespace(true)

set_skip_whitespace(skip)

空白をラティス上で読み飛ばすかどうかを設定します。skip の意味は設定ファイルの segmenter.skip_whitespace と同じです：

• true -- 空白を読み飛ばし、MeCab と同様に空白の前後の語を直接接続します。
• false -- 空白を独立したノード（空白の見出し語か SPACE の未知語）としてラティスに残します（v7 より前の動作）。空白は引き続き出力から除外されます。
• nil -- 辞書の metadata.json のデフォルトです。SudachiDict 以外では読み飛ばします。以前の呼び出しを取り消すときに使います。

ここで設定した値は、辞書のデフォルトと、TokenizerBuilder.from_file で読み込んだ skip_whitespace より優先されます。空白トークンを残すとき（set_keep_whitespace(true)）は効果がありません。残した空白は常にラティスに残るためです。それ以外の値は、set_keep_whitespace と同じく Ruby の真偽値の規則で扱われ、false と nil 以外は読み飛ばしを有効にします。

たとえば IPADIC では、Google が 新しい の が は、デフォルトでは助詞（助詞）、set_skip_whitespace(false) では接続詞（接続詞）と解析されます。詳しくは Segmenter を参照してください。

# v7 より前と同じく、空白をラティスに残す
builder.set_skip_whitespace(false)

set_space_penalty(value)

韓国語向けの左側空白ペナルティ（left-space penalty）を設定します。直前に空白がある候補のうち、本来は前の語に空白なしで付く品詞（助詞、語尾など）の候補にコストを加算します。value の意味は設定ファイルの segmenter.space_penalty と同じです：

• nil -- デフォルト。辞書が metadata.json に同梱するルールがあればそれを使います（ko-dic は mecab-ko-dic のルールを同梱し、他の同梱辞書はルールを持ちません）。以前の呼び出しを取り消すときにも使います。
• false -- ペナルティをオフにします。
• true -- 辞書のルールを要求します。ルールを同梱しない辞書では build が RuntimeError を発生させます。
• 文字列キーのハッシュ { 'rules' => [{ 'pos' => [...], 'cost' => n }, ...] } -- 辞書のルールの代わりにこのルールを適用します。先頭品詞タグが pos に含まれる候補に cost を加算し、最初に一致したルールが使われます。

これらの形式に当てはまらない値（1、'false'、{ 'rules' => 'JKS' } など）では RuntimeError が発生します。変換できない値では TypeError が発生します。該当するのは Symbol（ハッシュのキーや要素に含まれる場合も含むため、%i[JKS] ではなく %w[JKS] と書きます）、有限でない Float（NaN や Infinity）、64 ビットの範囲を超える Integer、および nil・true・false・Integer・Float・String・Array・Hash 以外のオブジェクトです。

# ペナルティをオフにする
builder.set_space_penalty(false)

# 明示的なルール
builder.set_space_penalty({
  'rules' => [
    { 'pos' => %w[EC EF EP ETM ETN VCP XSA XSN XSV], 'cost' => 3000 },
    { 'pos' => %w[JC JKB JKC JKG JKO JKQ JKS JKV JX], 'cost' => 6000 }
  ]
})

[!NOTE] v6.1.0 から、ko-dic では mecab-ko と同じく左側空白ペナルティがデフォルトで適用されます。たとえば 검색 이 잘 된다 の 이 は感動詞 IC と解析されます（ペナルティがなければ主格助詞 JKS）。オフにするには builder.set_space_penalty(false) を呼び出してください。Lindera::Tokenizer.new(dictionary, ...) で直接作成したトークナイザーは常にデフォルトを使うため、オフにするには TokenizerBuilder を使ってください。ルールを同梱しているのは Lindera 6.1.0 以降でビルドした ko-dic だけです。v6.0.0 リリースの ko-dic ではペナルティはオフのままで、辞書を再ビルドするまで true はエラーになります。詳しくは Segmenter を参照してください。

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)

set_space_penalty、append_character_filter、append_token_filter の引数は、配列と hash の入れ子が 128 段までです。それより深い値や、自分自身を含む値を渡すと ArgumentError が発生します。

ビルド

build

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

tokenizer = builder.build

Tokenizer

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

Tokenizer の作成

Lindera::Tokenizer.new(dictionary, mode = nil, user_dictionary = nil, space_penalty: nil, penalty: nil)

読み込み済みの辞書から直接トークナイザーを作成します。mode のデフォルトは 'normal' で、user_dictionary は省略できます。

キーワード引数 space_penalty: には TokenizerBuilder#set_space_penalty と同じ値を渡せます。nil（デフォルト）では辞書が同梱する左側空白ペナルティのルールを使うため、ko-dic ではペナルティがオンになります。オフにするには false を渡します。不正な設定では、set_space_penalty や build と同じエラーが発生します。

キーワード引数 penalty: には、TokenizerBuilder#set_mode と同じく "decompose" モードの Lindera::Penalty を渡せます。エラーも set_mode と同じです。

require 'lindera'

dictionary = Lindera.load_dictionary('embedded://ipadic')
tokenizer = Lindera::Tokenizer.new(dictionary)

# 左側空白ペナルティなしの ko-dic
ko_tokenizer = Lindera::Tokenizer.new(Lindera.load_dictionary('embedded://ko-dic'), space_penalty: false)

ユーザー辞書を使用する場合：

dictionary = Lindera.load_dictionary('embedded://ipadic')
user_dict = Lindera.load_user_dictionary_for('/path/to/user_dictionary.csv', dictionary)
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"）を受け取ります。decompose モードのペナルティは、それぞれのキーワード引数 penalty: で渡します（下記の Penalty を参照してください）。

Mode の作成

Lindera::Mode.new(mode_str)

Mode を作成します。引数は必須ですが nil を渡すこともできます。"normal" / "Normal"（mode_str が nil の場合に使用）または "decompose" / "Decompose" を受け付けます。それ以外の値を渡すと ArgumentError が発生します。