litsea-binding-core

litsea-binding-core は、各言語バインディングが共有する FFI 非依存のロジックをまとめたクレートです。依存先は litsea（およびネイティブターゲットではブロッキング用の Tokio）のみで、PyO3・napi・ext-php-rs・magnus・wasm-bindgen には一切依存しません。そのため、ホスト言語のツールチェーンなしでユニットテストできます。

インストール

[dependencies]
litsea-binding-core = "0.13.0"

モジュール構成

graph LR
    A["litsea_binding_core::segmenter"] --- B["CoreSegmenter"]
    C["litsea_binding_core::model"] --- D["build_segmenter, read_model_file, read_model_uri"]
    E["litsea_binding_core::token"] --- F["TokenView"]
    G["litsea_binding_core::language"] --- H["parse_language, SUPPORTED_LANGUAGES"]
    I["litsea_binding_core::trainer"] --- J["CoreExtractor, CoreTrainer, CorePerceptronTrainer, CoreTwoStageTrainer"]
    K["litsea_binding_core::cancel"] --- L["CancelToken"]
    M["litsea_binding_core::error"] --- N["CoreError, ErrorKind, CoreResult"]
    O["litsea_binding_core::runtime"] --- P["block_on"]

分割

#![allow(unused)]
fn main() {
use litsea::Language;
use litsea_binding_core::CoreSegmenter;

let segmenter = CoreSegmenter::from_path(Language::Japanese, "models/japanese.model".as_ref())?;

assert_eq!(
    segmenter.segment("これはテストです。"),
    vec!["これ", "は", "テスト", "です", "。"]
);
}

空白区切りの言語では空白自体が 1 トークンとして返るため、トークンを連結すると入力が正確に復元されます。例えば korean.model は "안녕하세요 반갑습니다" を ["안녕하세요", " ", "반갑습니다"] に分割します。

CoreSegmenter は Arc<Segmenter> と Mutex<SegmentBuffer> を保持します。Segmenter は Send + Sync であり、モデル読み込み済みのインスタンスは packed テーブルが構築済みのため、並行した segment 呼び出しは内部の read ロックしか取りません。ミューテックスが保護するのはスクラッチバッファだけです。したがって 1 つのインスタンスをスレッド間で共有し、継続的に再利用できます（各バインディングはそのように使います）。

バイトオフセットは厳密です。トークンは入力を隙間も重複もなく覆うため、すべてのトークンについて &text[token.byte_start..token.byte_end] == token.surface が成り立ちます。空白を保持する韓国語・英語でも同様です。

なお segment_with_pos_batch は segment_batch のようにアロケーションを償却できません。litsea に segment_with_pos のバッファ再利用版が存在しないためです。

モデルの読み込み

いずれも build_segmenter を経由し、モデルファイル自身から何を構築するかを決定します。

バイト列を 1 度読んでから分岐するため、リモートモデルのダウンロードは 1 回で済みます。

エラー

CoreError は ErrorKind とメッセージを持ちます。種別は安定した文字列で、ホスト言語へそのまま公開することを想定しています。

この一覧は remote_model feature の有無で変化しないため、バインディング側の例外階層は固定できます。

学習

ネイティブターゲットのみで利用できます。特徴量抽出と学習はファイル入出力を前提としているためです。

#![allow(unused)]
fn main() {
use litsea::Language;
use litsea_binding_core::{CancelToken, CoreExtractor, CoreTrainer, CorpusFormat};

CoreExtractor::new(Language::Japanese).extract(
    "corpus.txt".as_ref(),
    "features.txt".as_ref(),
    CorpusFormat::PlainText,
    false, // tag_free
)?;

let metrics = CoreTrainer::new(0.01, 10_000, "features.txt".as_ref())?
    .train(&CancelToken::new(), "japanese.model".as_ref())?;
println!("accuracy: {:.2}%", metrics.accuracy);
}

CoreTwoStageTrainer は CLI の train --pos に対応します。litsea の TwoStageTrainer::train がトレーナを消費する（stage 1 は AdaBoost モデルへ collapse されるため、その場での再学習ができない）ため、このトレーナは 1 度しか使えません。2 回目の呼び出しは InvalidArgument エラーを返し、is_available() で状態を確認できます。

キャンセルの挙動

キャンセルは協調的であり、エラーではありません。

• トレーナは次のチェックポイントで停止し、
• 部分的に学習されたモデルは指定パスへ保存され、
• メトリクスが通常どおり返されます。

チェックは AdaBoost 学習ではブースティング反復ごと、パーセプトロン学習ではエポックごと・インスタンスごとに行われるため、パーセプトロン学習の方が反応がはるかに速くなります。CancelToken のクローンは同じフラグを共有するので、バックグラウンドスレッドに渡したトークンから、別スレッドが実行中の学習を停止できます。

プラットフォームサポート

wasm32-unknown-unknown では trainer・runtime・read_model_file・CoreSegmenter::from_path はコンパイル対象から外れます。wasm32 にはファイルシステムもブロッキングランタイムも存在しないためです。WASM から使う場合は、JavaScript 側でモデルのバイト列を取得し CoreSegmenter::from_bytes に渡してください。

Feature