README.ja_JP.md

d2vg

d2vg, A Doc2Vec grep.

Doc2Vecモデルを使って、クエリのフレーズに似た部分を含む文書ファイルを検索します。

• テキストファイル（.txt）、PDFファイル（.pdf）、MS Wordファイル（.docx）からの検索に対応
• 対応言語は日本語、英語。実験的に、中文、韓国語に対応しました。
• インデックス化を行うことで性能向上

インストール

→ Ubuntuでのインストール
→ Windowsでのインストール

中文の場合は、インストールの手順で、次の行のd2vg[ja]をd2vg[zh]に変更してください。 韓国語の場合は、同様に、d2vg[ja]をd2vg[ko]に変更してください。

pip3 install d2vg[ja]

利用法

d2vg -v <クエリとなるフレーズ> <ファイル>...

英語のドキュメントとして検索する場合には、オプション -l en を指定してください:

d2vg -l en -v <query_phrase> <files>...

実行例:

オプション

d2vgにはいくつかオプションがあります。よく使われるであろうものを説明します。

--verbose, -v
Verboseオプションです。指定すると、検索の進行中に、その時点までの進捗状況や、最も類似度の高いドキュメントを表示します。

--lang=LANG, -l LANG
言語に対応したDoc2Vecモデルを選択します。使用可能な言語は、en、ja、ko、zhです。

--unknown-word-as-keyword, -K
未知の単語を含むパターンの場合、そのような単語はキーワードとみなされます。パターンにマッチし、キーワードを含むドキュメントのみが検索結果として返されます。

--topn=NUM, -t NUM
上位のNUMドキュメントを結果として表示します。既定値は20です。 0を指定すると、検索されたすべての文書を、パターンとの一致度でソートして表示します。

--paragraph, -p
このオプションを指定すると、1つの文書ファイル内のそれぞれのパラグラフがドキュメントとみなされます。検索結果に一つの文書ファイルの複数の段落が出力されるようになります。 このオプションが指定されていない場合、1つの文書ファイルが1つのドキュメントとみなされます。検索結果に一つの文書ファイルはたかだか1回だけ表示されます。

--window=NUM, -w NUM
この数字で指定された行のかたまりを1つの段落として認識します。 既定値は20です。

--normalize-by-length, -n
クエリとの類似性を計算する際には、文書の長さで正規化します。パラグラフの長さの差が大きい場合は、短いパラグラフが優先的に検索結果に表示されるようになります。

--worker=NUM, -j NUM
ワーカープロセスの数。0を指定するとCPUコア数と解釈されます。 これにより、特にインデックスが作成されていない文書から検索する場合に、検索速度が向上する可能性があります。

キーワード検索

オプション-Kをつけると、クエリのフレーズ中に（Doc2Vecモデルの）未知語があった場合は、それらの語をキーワードに指定します。 キーワードが指定された場合は、キーワードがすべて含まれる部分のみが検索結果に表示されます。さらに、指定されたキーワードが「> keywords:」という行に表示されます。

実行例: 「HCI」がキーワードに指定された例

インデックス化

d2vgにドキュメント（検索対象のファイル）のインデックスを作成させることで、同じドキュメント（の集合）から何度も検索を行う場合に、2回目以降の検索の速度を向上させることができます。

d2vgは以下の条件のときに、インデックスDBを作成して参照します。

• d2vgを実行するときのカレントディレクトリに.d2vgというサブディレクトリがある
• 対象のドキュメントが相対パスで指定されている

インデックス化を開始するには、ドキュメントのディレクトリに行って、 .d2vg ディレクトリを作成してください。

cd ドキュメントのディレクトリ
mkdir .d2vg

インデックスDBは検索を行う度にインクリメンタルに更新されます。 すなわち、新しいドキュメントが追加されて検索の対象になったタイミングで、そのドキュメントのインデックスを作成しインデックスDBに追加します。

その一方で、削除されたドキュメントのインデックスをデータベースから自動的に削除する機能は無いので、必要に応じて明示的に.d2vgディレクトリを削除してください。

cd ドキュメントのディレクトリ
rm -rf .d2vg

DOSプロンプトやPowershellの場合は、それぞれ、rd /s /q .d2vgあるいはrm -r -fo .d2vgとしてください。

インデックス化を有効にしたときの実行例:
(この例では、インデックス化をしていないときは70秒以上かかっていたものが、4秒に短縮されました。)

トラブルシューティング

Q: Doc2Vecモデルをインストールしたのに「Error: not found Doc2Vec model for language: jp」というエラーが出ます。
A: 言語の指定が間違っています。「jp」ではなく「ja」です。

Q: d2vgがハングアップします。
A: インデックス化が有効な（ディレクトリ.d2vgを作成している）ときに、強制終了すると、次回実行時にインデックスDBが開けなくなってハングアップすることがあるようです。ディレクトリ.d2vgを削除してください。

開発

Doc2Vecモデルの作成の方法については、making_doc2vec_model/にある、Doc2Vecモデルを作成したスクリプトを参考にしてください。 モデルを作成するときのパラメーターについては、スクリプトのtrim_docs.pyやtrain.pyのヘルプメッセージが参考になるかもしれません。

添付しているモデルは、言語によって異なりますが、語彙が4万語から6万5千語であり、100次元のベクトルでドキュメントを表現するものです。 不足していると感じる場合には、スクリプトを利用して、強化したより良いモデルを作成してください。 添付しているモデルを作成するときに利用したパラメータは、その言語で利用可能なコーパスの文書量や、含まれている語彙の量に大きく依存したものです。また、githubのリリースページでの単一ファイルの上限に収まるサイズになるように調整されています。

協力のお願い: 特に自分の母国語の日本語以外については、モデルを十分にチューニングできているかどうか自信がありません。モデルの作成に興味を持たれている方、プルリクエスト、作成したモデルを公開しているURL等、大歓迎です。 🙇

Doc2Vecモデルの配布ファイル

Doc2Vecモデルは、Gensim v4で作成されたものとしてください。 <言語.ref>というファイル(「言語」はオプション-lで指定する言語の名前です)に、Doc2Vecモデルのファイルへの相対パスを記述してください。

例えば、日本語のDoc2Vecモデルの場合には、ja.refというファイルの中身はjawiki-janome-m100-c400-d100.modelという行になっています。

~/.config/d2vg/models/jawiki-janome-m100-c400-d100
├── ja.ref
├── jawiki-janome-m100-c400-d100.model
└── jawiki-janome-m100-c400-d100.model.dv.vectors.npy

Todo

• ドキュメントファイルのインデックス化の導入による最適化
• 最新版のgensim v4と互換性のあるDoc2Vecデータの準備
• Windowsでのインストールを確認
• キーワード検索の併用
• インストールを容易に
• より多くの言語サポートおよびチューニング(実験的サポート: ko, zh)
• 検索対象のファイルが数百万個になったときのための明示的なインデックス化コマンド

謝辞

Doc2Vecモデルの作成には次のサイトを参考にしました:
日本語Wikipediaで学習したdoc2vecモデル

koとzhのDoc2Vecモデルの作成は、次のソースを参考にしました:
https://github.com/Kyubyong/wordvectors/blob/master/build_corpus.py

膨大な言語コーパスを提供されているWikipediaに感謝いたします:
https://dumps.wikimedia.org/

ライセンス

d2vgは BSD-2 ライセンスで配布されます。