Pagefindのステミング警告は見当違いだった — 日本語検索を壊していたのは分かち書きの不一致
Pagefindはビルドのたびに日本語と中国語のステミング未対応を警告していました。本当の不具合は別にあり、検索語と索引のトークナイザーの不一致が誤ったページを返していました。

目次
はじめに
このサイトはビルドのたびに同じ 2 つの注意書きを出していて、私は何週間もそれを読み飛ばしていました。
Note: Pagefind doesn't support stemming for the language ja-jp.Search will still work, but will not match across root words.ja-jp に 1 つ、zh-tw に 1 つ、そして en-us には何も出ません。あるとき、この注意書きを見れば誰でも抱く疑問を確かめることにしました。これは Pagefind の日本語と中国語における本当の制限なのか、直せるのか。安心させるだけの答えではなく正直な答えが欲しかったのは、このサイトで古い記事にたどり着く手段が検索しかないからです。
正直な答えは 2 つに分かれました。この警告は恒久的で、無害で、そもそも壊れていない部分についてのものです。
その下には、何ひとつログを出さない本物の不具合が潜んでいました。Pagefind 1.5 では、日本語の複合語で検索すると誤った記事が、しかも自信たっぷりに返ってきます。私はこれを、Pagefind のビルド済みバンドルへの 1 行のパッチで直しました。その後 Pagefind 1.6.0 が上流で検索結果の取りこぼしを直したので、いまのパッチが変えるのは結果の並び順だけです。
ステミングは英語のもの、分かち書きは日本語のもの
この 2 つの語は同じもののように聞こえますが、正反対の問題を指しています。
ステミングは接尾辞を削り、活用した形を 1 つの語根にまとめます。repository で検索して repositories にも当たるのはこれのおかげで、英語が語の末尾に文字を足して文法を表す言語だから成立します。Pagefind はステミングライブラリの Snowball でステミングを実装していて、ステミングに対応する言語として 33 言語を挙げています。
分かち書きは逆の問題です。そもそも語の切れ目がどこなのかを見つけます。日本語と中国語はスペースを使わずに書くので、索引に入れる前に「画像変換」が 1 語ではなく 2 語だと判断する処理が要ります。英語にこの工程は要りません。スペースがすでにその仕事を終えているからです。
Snowball に中国語・日本語・韓国語のアルゴリズムはなく、今後も追加されません。接尾辞で活用しない言語にとって、接尾辞を削る操作は意味を持たないからです。つまりこの注意書きは正確で恒久的です。同時に無関係でもあります。日本語の検索は、注意書きが指す工程に一切依存していません。
分かち書きのほうは対応済みです。pagefind の npm パッケージは、CJK の分かち書き器を同梱した extended バイナリを入れます。extended バイナリが入っていることは、ビルド出力の 1 行目で確認できます。
Running Pagefind v1.5.2 (Extended)1.5.2 の extended バイナリが 55 MB あるのは辞書を抱えているからです。中の文字列を取り出すと、何が入っているかが分かります。
charabia-0.9.9/src/segmenter/chinese.rs -> jieba-rs 0.8.1charabia-0.9.9/src/segmenter/japanese.rs -> lindera 0.43.3 + lindera-unidic中国語は Jieba、日本語は UniDic 辞書を伴う Lindera。警告が触れていない能力のほうは、最初から備わっていました。
警告を読んでいるだけでは思いつかなかった計測
注意書きを読んでも先に進まないので、私は検索そのものを計測することにしました。サイトをビルドし、各ロケールの索引を Pagefind の JavaScript API から直接引きます。そして語ごとの件数を、その語を含む日本語記事の数と突き合わせました。ある語が 8 ページに出現して検索が 8 件返すなら、その言語の検索は正しく動いています。
1.5.2 では、日本語もほとんどは動いていました。
| 検索語 | 含むページ数 | 件数 | 正しいか |
|---|---|---|---|
ドキュメント | 47 | 47 | はい |
ブラウザ | 38 | 38 | はい |
画像 | 21 | 21 | はい |
コンポーネント | 19 | 19 | はい |
リポジトリ | 49 | 1 | いいえ |
リポジトリ は珍しい語ではありません。このサイトの 49 記事に出てきます。それなのに返ってきた 1 件は、その語をどこにも含まない、言語モデルの歴史についての記事でした。
0 件を返す検索なら、失敗したことが分かります。この検索は、もっともらしい誤答を返してきました。
語は索引にあったのに、検索語の側が問い合わせていなかった
リポジトリ に対して Pagefind が返した抜粋が、そのまま答えになっていました。ハイライトされていたのは リレー、字面が少し似ているだけの無関係な語です。エンジンは何にも一致できず、曖昧一致に落ちていました。
次の試験で、原因が索引側と検索語側のどちらにあるかを切り分けられました。複合語 ガベージコレクション の前方一致である ガベージ で検索すると、その複合語を含む 2 記事がどちらも返ります。完全な語で検索すると、どちらも返りません。
短い検索語が見つけたものを、長くより正確な検索語は見つけられませんでした。ふつうは長く正確な検索語ほどよく当たるので、関係が逆転しています。ガベージ で 2 記事が返ったことから索引が複合語をまるごと保持していると分かるので、原因は検索語側にあります。
その検索語をブラウザがどう扱うかを尋ねると、仕組みが 1 行で出てきました。
[...new Intl.Segmenter('ja-JP', { granularity: 'word' }).segment('ガベージコレクション')] .filter((s) => s.isWordLike) .map((s) => s.segment);// ['ガ', 'ベ', 'ージ', 'コレクション']
// リポジトリ -> ['リ', 'ポジ', 'トリ']// ドキュメント -> ['ドキュメント']// 画像 -> ['画像']Pagefind 1.5.0 は、ブラウザ組み込みの単語分割 API である Intl.Segmenter を使って、ブラウザ側で検索語を切りはじめました。1.5.0 のリリースノートによれば、検索語も本文と同じ切り方をすべきだ、というのがその理由です。しかし 1.5 では、索引側と検索語側が同じ辞書を使っていません。
索引を切るのは Rust バイナリ内の Lindera と UniDic です。検索語を切るのは、利用者のブラウザが積んでいる ICU の辞書です。Lindera と ICU の切り方が食い違えば、負けるのは検索語のほうです。
ガベージコレクション を 1 語として格納し、ICU は 4 つの断片に切りました。索引にある語は最後の コレクション だけです。全ての語が一致する必要があるため、複合語を持つページが候補から外れ、索引に実在する コレクション が別のページを引き寄せます。これが不具合の中身です。断片 ガ、ベ、ージ は索引上の語ではなく、Pagefind は全ての検索語の一致を要求するので、複合語を含む記事が除外されます。残るのは曖昧一致が見つけたもので、何も見つからないこともあります。
この対応関係は試したすべての語で成り立ちました。Intl.Segmenter が語を保ったときは検索が正確で、語を刻んだときは検索が誤っていました。
語を最後まで打つと不具合が起きる
前方一致は効いて完全な語は効かないので、この不具合はとりわけ意地の悪い現れ方をします。ガベージコレクション の各前方一致を順に検索し、その語を含む 2 記事が結果に入っているかを確かめました。
利用者は、語を正確に打とうとしたことで罰を受けます。この不具合が長く気づかれなかった理由もここにあります。検索語を途中まで打った人には検索が機能して見え、どのログもそれについて何も言わなかったからです。
中国語も壊れていましたが、最初は気づきませんでした。ICU は 儲存庫 を 儲存 と 庫 に切り、Jieba も繁体字中国語を独自の短い単位に切ります。コーパスが小さいうちは、ICU と Jieba の切り方はおおむね一致していました。いまのコーパスでは、搜尋 は 35 件の zh-TW 記事に出てくるのに 1.5.2 は 1 件しか返さず、環境變數 は 10 件に出てくるのに 1 件も返しませんでした。
1.4 への差し戻しは検索を直し、検索窓を壊した
検索語の分かち書きを導入したのが 1.5.0 である以上、1.4.0 にこの不具合はないはずです。同じビルドを pnpm dlx pagefind@1.4.0 で再インデックスし、同じ検索語を流すと、そのとおりでした。
| 検索語 | 1.4.0 | 1.5.2 |
|---|---|---|
リポジトリ | 49 件、すべて正しい | 1 件、誤ったページ |
ガベージコレクション | 2 件、どちらも正しい | 0 件 |
ドキュメント | 47 | 47 |
つまり退行は本物で、1.4.0 に固定したくなりました。しかし 1.4.0 は、このサイトでは使い物になりませんでした。このサイトの検索 UI は pagefind-searchbox という Web コンポーネントですが、1.4.0 が同梱するその版は、自身の pagefind.js が定義していない関数を呼びます。
TypeError: s.createInstance is not a function古いバンドルが配信されていたわけではありません。全ファイルを cache: 'reload' で取り直しても同じエラーでした。
うまくいった方法の前に、2 つの方法が失敗しています。検索語を "リポジトリ" と引用符で囲んでも分かち書きは回避できず、0 件が返りました。引用された語句も、同じように刻まれた断片から組み立てられるからです。
pagefind.js の中の言語リストにパッチを当てても、出力は素の状態と 1 バイトも変わらず、パッチが黙って失敗したように見えました。失敗してはいませんでした。1.5.0 以降、検索は Web Worker で走り、pagefind-worker.js が同じ言語リストを自前で持っています。片方だけにパッチを当てても、利用者から見える変化は何も起きません。
1 つのリストから 1 つの言語を外す
判定そのものは、最小化された 3 行の JavaScript です。
needsWordSegmentation = (lang) => { if (!lang) return false; const primaryLang = lang.split('-')[0].toLowerCase(); return ['zh', 'ja', 'th'].includes(primaryLang);};これを切り替える設定項目はありません。--force-language も代わりにはなりません。サイト全体を 1 つの言語として索引にするので、/ja/search が英語記事を返さないようにしている <html lang> ごとの索引分割が潰れてしまうからです。
そこで、ビルド後のバンドル内のそのリストを、両方のファイルで、日本語についてだけ書き換えることにしました。上流の修正を待つのではなくこれを入れると私が決め、scripts/patch-pagefind-ja.ts が pnpm build の一部として pagefind の実行後に毎回走るようになっています。
ビルド出力を書き換えるのはワークアラウンドで、ワークアラウンドは気づかないうちに腐ります。そこで scripts/patch-pagefind-ja.ts は、黙って腐る代わりにはっきり失敗するように書いてあります。
- リストが見つからなければ、原因を明示してビルドを失敗させます。パッチの当たっていないバンドルを黙って出荷すれば、このスクリプトが存在する理由そのものの不具合が戻ってきます。
- Pagefind が計測時のバージョンでなければ、警告を出します。
- 未検証のバージョンでリストがすでに
['zh', 'th']になっていた場合は致命的エラーにします。そのリストはこのスクリプトの以前の実行結果ではなく上流自身のものかもしれず、その場合この工程は何もしないまま正常終了してしまうからです。
あわせて、pagefind を厳密なバージョンに固定しました。それまではキャレット範囲で指定されていて、このリポジトリでは Dependabot が自動マージし、必須のステータスチェックもありません。最小化された出力の形を変える Pagefind のリリースが出れば、そのリリースは Dependabot によって自動でマージされ、その後は検索と無関係な記事公開まで含めてすべての本番デプロイを止めていたはずです。
同じ理由で、バージョン不一致は致命的エラーにしていません。致命的にすれば、その障害を防ぐどころか自分で起こしてしまいます。
1.5.2 でパッチが変えたもの
| 検索語 | パッチなしの 1.5.2 | パッチありの 1.5.2 |
|---|---|---|
リポジトリ | 1 件、誤ったページ | 49 件、すべて正しい |
ガベージコレクション | 0 件 | 2 件、どちらも正しい |
ドキュメント / アーキテクチャ / コンポーネント | 47 / 9 / 19 | 変化なし |
ワークツリー | 3 記事中 3 記事 | 3 記事中 1 記事 |
搜尋 / 環境變數(zh-TW) | 1 / 0 | 1 / 0 |
repository / repositories | 38 / 38 | 38 / 38 |
中国語には手を触れていないので失敗はそのまま残り、英語は今もステミングしています。代償は ワークツリー の行です。Lindera はこの複合語を分割して索引に入れていたので、検索語をまるごと渡すと 3 記事のうち 2 記事を取りこぼしました。
Pagefind 1.6.0 は ICU4X で索引を作り、パッチは並び順を変えるだけになった
Pagefind 1.6.0 は Lindera と Jieba を ICU4X に置き換えました。ICU4X は、Chromium の Intl.Segmenter が土台にしている ICU ライブラリを Rust で書き直したものです。extended バイナリは 55 MB から 12 MB に縮み、中の文字列には icu_segmenter-2.3.0 が現れます。
Pagefind 1.6.0 のリリースノートには、索引側の分かち書きが「ブラウザで使われる Intl.Segmenter にかなり近づいた」(拙訳)とあり、メンテナーはこの食い違いを追っていた上流の issue (Pagefind/pagefind#1237) を閉じました。
このコーパスでは、1.6.0 はパッチの有無にかかわらず、どちらの言語でも該当ページをすべて見つけます。中国語もこれで回復しました。
| zh-TW の検索語 | 含むページ数 | 1.5.2 | 1.6.0 |
|---|---|---|---|
搜尋 | 35 | 1 | 35 |
環境變數 | 10 | 0 | 16 件中に 10 件すべて |
快取 | 24 | 31 件中に 24 件すべて | 24 件、過不足なし |
日本語では、パッチが変えるのは順位だけになりました。次の表の「上位」は、その語を含むページ数を N としたとき、最初の N 件に正しいページがいくつ入ったかを数えたものです。
| 検索語 | 含むページ数 | パッチなしの 1.6.0(上位) | パッチありの 1.6.0(上位) |
|---|---|---|---|
ガベージコレクション | 2 | 0 | 2 |
ワークツリー | 3 | 1 | 3 |
型チェック | 9 | 4 | 8 |
環境変数 | 10 | 8 | 3 |
依存関係 | 12 | 8 | 6 |
ブランチ保護 | 2 | 2 | 1 |
ブラウザは今もカタカナの複合語を刻み、パッチなしの 1.6.0 は、断片に一致したページを語をまるごと含むページより上に並べます。漢字の複合語は逆です。ICU4X が索引側でもブラウザと同じように語を切るようになったので、検索語をまるごと渡すと順位が下がります。
技術ブログではカタカナの外来語のほうがよく検索されるので、私はパッチを残しました。また 1.6.0 からは、ステミングの注意書きも --verbose を付けて実行したときにしか出ません。
まとめ
- 毎回のビルドで出ている警告は、いま追っている不具合の証拠ではありません。ステミングの警告は正確で、恒久的で、無関係でした。警告の隣にあった不具合のほうは、何もログを出しませんでした。
- ステミングと分かち書きは正反対の問題を解きます。英語は最初から区切られていて語尾を削る必要があり、日本語は切れ目なく届いて切る必要があります。ステミングを持たず分かち書きを完璧にこなすツールはありえます。
- 一方の辞書で索引を作り、もう一方の辞書で検索するエンジンは、その 2 つの辞書が食い違う語でちょうど失敗します。しかもその失敗は、空の結果ではなくもっともらしい誤答として現れます。
- 前方一致ではなく、完全な語で試してください。前方一致の検索はこの不具合を完全に隠していましたし、検索窓を軽く確認する人が実際に打つのは前方一致です。
- 読めない言語は数えて検証してください。ページ数と検索の件数を突き合わせる作業に読解力は要らず、小さなコーパスが隠していた中国語の失敗もこれで見つかりました。
- Pagefind 1.6.0 は ICU4X で索引を作ることで取りこぼしを直しました。分かち書きのリストから
jaを外すと、いまはカタカナの順位がよくなる代わりに漢字の順位が下がります。私は Pagefind を上げるたびに、この損得を計り直しています。
参考リンク
- Pagefind: Multilingual search(ステミング対応・非対応の言語一覧を含む)
- Pagefind 1.5.0 リリースノート(検索語側の
Intl.Segmenterによる分かち書きが入った版) - Pagefind 1.6.0 リリースノート(索引側の分かち書きが ICU4X に移った版)
- Pagefind issue: 索引側の Lindera と検索側の Intl.Segmenter が日本語の複合語で食い違う (Pagefind/pagefind#1237)
- MDN: Intl.Segmenter(Pagefind が検索語を切るのに使うブラウザ API)
- Snowball(Pagefind の対応言語を支えるステミングライブラリ)


