migrate_user_dictionary.md

ユーザー辞書の移行手順

V0 形式 -> V1 形式

Sudachi v0.8.2 にてバイナリ辞書の形式が V0 から V1 に更新されました。 これらには互換性がないため、V0 形式の Sudachi バイナリ辞書は v0.8.2 以降の Sudachi では利用できません（逆も同様です）。

合わせて辞書ソースファイルについても記述方法が更新されています。 ソースファイルについては v0.8.2 以降でも V0 形式のものを利用可能ですが、記述可能な情報量が制限されます。

ここでは V0 形式の Sudachi 辞書から V1 形式に移行するための手順を記述します。 大まかな手順は以下です。

• （バイナリ辞書しか保持していない場合）v0.8.1 以前の Sudachi を用いて内容をソースファイルにダンプする
• ソースファイルを V0 形式から V1 形式に更新する
• 実行時に使用するものと同じシステム辞書を取得する
• そのシステム辞書を用いてユーザ辞書をビルドする

辞書ソースファイル (lexicon CSV)

辞書ソースである lexicon CSV ファイルは、標準の記述方法が変更されました。 v0.8.2 では V0 形式のものも利用可能ですが、新形式への移行を推奨します。

本文書では移行のための最小限の差分のみを扱います。 V1 形式の詳細については user_dict_v1.md、V0 形式の詳細については user_dict_v0.md を参照してください。

移行のための差分

V0 形式から V1 形式への移行にあたっては、以下の変更が必要となります。

ヘッダー

辞書ソースの 1 行目にはヘッダー行をおき、記述する項目の種類と順序を指定するようになりました。

V0 形式に対応するヘッダー行は以下です。 これをソースファイルの 1 行目に追加してください。

SURFACE,LEFT_ID,RIGHT_ID,COST,WRITING,POS1,POS2,POS3,POS4,POS5,POS6,READING_FORM,NORMALIZED_FORM,DICTIONARY_FORM,MODE,SPLIT_A,SPLIT_B,WORD_STRUCTURE

なお、カラム名の表記における大文字小文字および "_" の有無による差分はパース時に無視されます（"LEFT_ID" を "leftId" などと記述できます）。

空項目

V0 形式では項目の値がない場合 "*" を指定していましたが、V1 形式では空文字列とする必要があります。 辞書形 ID (dictionary_form)、A/B 単位分割情報 (split_a, split_b)、第 17 項目（word_structure）について、"*" を空文字列に置き換えてください。

なお品詞項目の "*" は空値とは異なるためそのままとしてください。

語参照

正規化形や辞書形、分割情報の項目では他の語への参照を記述する場合があります。 V1 形式における語参照は、参照先の語の「見出し表記、品詞、読み」の組でのみ記述が可能です。 V0 形式では行番号による指定が可能でしたが、これは廃止されました。 また V0 形式の正規化形はその語に紐づく情報でしたが、V1 形式では別の語を参照するものに変更されました。正規化形においては見出し表記のみでの語参照の記述が許されるためそのままでも移行が可能ですが、参照にマッチする別語に解決される可能性があることに注意してください。

辞書形 ID (dictionary_form)、A/B 単位分割情報 (split_a, split_b)、第 17 項目（word_structure）について、行番号での記述を参照先の語の「見出し表記、品詞、読み」の組に変更してください。 各項目は , （コンマ） で分割し、その項目全体を " （ダブルクォーテーション）で括ります。

例（split_a）： ...,1/2,... -> ...,"東京,名詞,固有名詞,地名,一般,*,*,トウキョウ/都,名詞,普通名詞,一般,*,*,*,ト",...

「見出し表記、品詞、読み」の組で参照先の語が一意に定まらない場合は、参照 ID を使用することができます。 Reference_Id カラムを追加し、重複する語にそれぞれ固有の文字列を記載します。 その上で語参照の組の第4項目にこの文字列を追加することで参照先を一意に定めることができます。 なおこの記述を行わない場合は、先頭に記載されている語に解決されます。

ソースファイルの記述例：

Surface,LeftId,RightId,Cost,POS1,POS2,POS3,POS4,POS5,POS6,ReadingForm,NormalizedForm,DictionaryForm,Split_A,Split_B,WordStructure,Reference_Id
あわ,5146,5146,8000,名詞,普通名詞,一般,*,*,*,アワ,泡,,,,,bubble
あわ,5146,5146,8000,名詞,普通名詞,一般,*,*,*,アワ,粟,,,,,foxtail-millet

参照ID付き語参照の記述例： "あわ,名詞,普通名詞,一般,*,*,*,アワ,foxtail-millet"

移行用スクリプト

migrate_lexicon_v0_to_v1.py

移行用スクリプト migrate_lexicon_v0_to_v1.py が利用できます。 これはソースファイルの内容を直接 V0 から V1 形式に変換するスクリプトです。 実行には Python 実行環境が必要です。

スクリプトの実行には、参照するシステム辞書のソースファイル（V1 形式）を指定する必要があります。 別途辞書ソース配布ページから取得してください。 辞書のタイプ（small / core / full）に応じて複数のソースファイルを指定する必要があることに注意してください。

V1 形式では加えて品詞リストを指定することができます。 公式配布のシステム辞書バイナリでは pos.csv を使用しています。

V0 形式のソースファイル内でシステム辞書内の語を参照している場合、以前と異なるシステム辞書を用いると、参照先がずれる可能性があります。 このスクリプトの使用においては、対象 lexicon ファイルの作成時に参照したバージョンのシステム辞書を指定するか、変換後に内容を確認してください。 一度 V1 形式へ変換した lexicon CSV ファイルは任意のバージョンのシステム辞書と共にビルド可能になります。

例： dict/system_small.csv および dict/system_core.csv を参照し、old_lexicon.csv を変換したものを new_lexicon.csv に出力する

cd /path/to/sudachi
python3 ./scripts/migrate_lexicon_v0_to_v1.py \
    -o new_lexicon.csv \
    -p ./src/main/resources/pos.csv \
    --drop-leading-zero-synonym-group \
    -s ./dict/system_small.csv -s ./dict/system_core.csv \
    old_lexicon.csv

migrate_user_lexicon_v0_to_v1.sh

移行用スクリプト migrate_user_lexicon_v0_to_v1.sh が利用できます。 これはバイナリ辞書へのビルドと再プリントを介して変換を行うスクリプトです。

スクリプトの実行には、参照するシステムバイナリ辞書（V1 形式）を指定する必要があります。 別途配布ページから取得するか、手順に従ってビルドしてください。

V0 形式のソースファイル内でシステム辞書内の語を参照している場合、以前と異なるシステム辞書を用いると、参照先がずれる可能性があります。 このスクリプトの使用においては、対象 lexicon ファイルの作成時に参照したバージョンのシステム辞書を指定するか、変換後に内容を確認してください。 一度 V1 形式へ変換した lexicon CSV ファイルは任意のバージョンのシステム辞書と共にビルド可能になります。

例： dict/system.dic を参照し、old_lexicon.csv を変換したものを new_lexicon.csv に出力する

cd /path/to/sudachi
./scripts/migrate_user_lexicon_v0_to_v1.sh old_lexicon.csv ./dict/system.dic > new_lexicon.csv

バイナリ辞書

V0 形式の Sudachi バイナリ辞書は Sudachi v0.8.2 以降では読み込むことができません。 V1 形式のバイナリ辞書として再ビルドする必要があります。

1. lexicon CSV からの移行

対象のバイナリ辞書に対応する辞書ソースである lexicon CSV ファイルが存在する場合は、それを元に V1 形式のバイナリ辞書をビルドすることができます。 上記の辞書ソースファイルの移行方法に従い、V1 形式の lexicon ファイルに変換したのち、V1 形式でのビルドを行ってください。

V0 形式の lexicon ファイルからでもビルド可能ですが、非推奨です。 V0 形式のソースファイル内で語を行番号で参照している場合、以前と異なるシステム辞書を用いると、参照先がずれる可能性があります。

ユーザー辞書のビルドでは、参照するシステムバイナリ辞書（V1 形式）を指定する必要があります。 別途配布ページから取得してください。

なおユーザ辞書バイナリにはビルド時に使用したシステム辞書バイナリの識別情報が記録されます。 使用時にこれと異なるシステム辞書が指定された場合、エラーが出力されます。 これはシステム辞書の変更による語参照の解決結果の齟齬等を避けるためです。 ユーザ辞書バイナリのビルド時には、実行時に使用するシステム辞書を使用してください。

例： dict/system.dic を参照し、user_lexicon.csv からバイナリユーザー辞書 new_user.dic をビルドする

unzip -d "./sudachi" "./build/distributions/sudachi-executable-0.8.2.zip"
java -Dfile.encoding=UTF-8 \
    -cp ./sudachi/sudachi-0.8.2.jar \
    com.worksap.nlp.sudachi.dictionary.UserDictionaryBuilder \
    -s ./dict/system.dic -o new_user.dic user_lexicon.csv

システム辞書のビルド

V1 形式のシステム辞書を手元でビルドすることも可能です。

配布ページからソースファイルおよび matrix.def を取得します。 small 辞書のビルドには small_lex.csv、core 辞書のビルドには small_lex.csv, core_lex.csv、full 辞書のビルドには small_lex.csv, core_lex.csv, notcore_lex.csv が必要です。

V1 形式では加えて品詞リストを指定することができます。 配布のシステム辞書バイナリでは pos.csv を使用しています。

例：src/ 以下に配置した matrix.def, pos.csv, small_lex.csv, core_lex.csv から dict/system_core.dic をビルドする

java -Xmx8g -Dfile.encoding=UTF-8 -cp ./sudachi/sudachi-0.8.2.jar \
    com.worksap.nlp.sudachi.dictionary.DictionaryBuilder \
    -o ./dict/system_core.dic -m ./src/matrix.def -p ./src/pos.csv \
    ./src/small_lex.csv ./src/core_lex.csv

2. バイナリ辞書からの移行

バイナリ辞書のみが存在する場合、Sudachi v0.8.2 のみでは移行ができません。 バージョン v0.8.1 以前の Sudachi の DictionaryPrinter を用いて辞書ソースファイルへの変換を行ってください。 これは V0 形式での出力となるため、加えて上記の辞書ソースファイルの移行が必要となります。

ユーザー辞書のプリントでは、参照するシステムバイナリ辞書（V0 形式）を指定する必要があります。 別途配布ページから取得してください。

ユーザー辞書内で語を行番号で参照している場合、ビルド時と異なるシステム辞書を用いると、参照先がずれる可能性があります。 対象バイナリ辞書のビルドの際に参照したシステム辞書を指定するようにしてください。

例： dict/system.dic を参照し、バイナリユーザー辞書 user.dic の語を user_lexicon.csv に出力する

unzip -d "./sudachi" "./build/distributions/sudachi-executable-0.8.1.zip"
java -Dfile.encoding=UTF-8 \
    -cp ./sudachi/sudachi-0.8.1.jar \
    com.worksap.nlp.sudachi.dictionary.DictionaryPrinter \
    -s ./dict/system.dic -o user_lexicon.csv user.dic \