RubyDoc.info: File: README_ja – Documentation for wp2txt (2.3.2)

Wikipediaダンプファイルからテキストコンテンツとカテゴリデータを抽出するコマンドラインツールキット

English | 日本語

クイックスタート

# インストール
gem install wp2txt

# 日本語Wikipediaからテキストを抽出（自動ダウンロード）
wp2txt --lang=ja -o ./output

# 特定の記事を抽出
wp2txt --lang=ja --articles="東京,京都" -o ./articles

# カテゴリから記事を抽出
wp2txt --lang=ja --from-category="日本の都市" -o ./cities

概要

WP2TXTはWikipediaダンプファイルからプレーンテキストとカテゴリ情報を抽出します。XMLダンプ（bzip2圧縮）を処理し、MediaWikiマークアップを除去して、コーパス言語学やテキストマイニングなどの研究に適したクリーンなテキストを出力します。

主な機能

自動ダウンロード - 言語コード指定でダンプを自動ダウンロード
タイトル指定抽出 - フルダンプをダウンロードせずに特定記事を抽出
カテゴリベース抽出 - 特定のWikipediaカテゴリから全記事を抽出
カテゴリメタデータ抽出 - 記事のカテゴリ情報を出力に保持
テンプレート展開 - 日付・単位・座標などの一般的なテンプレートを可読テキストに変換
多言語対応 - 350以上のWikipedia言語でカテゴリ・リダイレクトを検出
ストリーミング処理 - 中間ファイルなしで大規模ダンプを処理
JSON出力 - データパイプライン向けの機械可読JSONL形式
オフライン研究索引 - カテゴリ・節見出し・全文に対する悉皆的・版固定クエリ、言語間リンクによる言語版横断SQL
MCPサーバー - ローカルダンプをLLMエージェント（Claude、ChatGPT、Gemini、ローカルモデル）に公開

ユースケース

wp2txtは以下の用途に適しています：

カテゴリ情報を活用した分野別コーパスの構築
トピック領域を横断した比較言語研究
NLPタスク向けのメタデータ付きWikipediaテキスト抽出
並行カテゴリ構造を利用した対照言語研究
版固定のRAG知識ベース・LLM評価データセット
web検索では原理的に不可能な悉皆的言明（「このカテゴリのどの記事にもXへの言及がない」）

データアクセス

wp2txtは公式Wikipediaダンプファイルを使用します。これはバルクデータアクセスの推奨方法であり、Wikimediaのインフラガイドラインに準拠しています。

インストール

wp2txtのインストール

$ gem install wp2txt

システム要件

WP2TXTはbz2ファイルを解凍するために、以下のコマンドのいずれかが必要です：

lbzip2（推奨 - 複数CPUコアを使用）
pbzip2
bzip2（ほとんどのシステムにプリインストール済み）

macOS（Homebrew）：

$ brew install lbzip2

Windows：Bzip2 for WindowsをインストールしてPATHに追加。

Docker（代替方法）

docker run -it -v /path/to/localdata:/data ghcr.io/yohasebe/wp2txt

wp2txtコマンドはコンテナ内で使用可能です。入出力には/dataディレクトリを使用してください。

イメージはGitHub Container Registry（ghcr.io/yohasebe/wp2txt）で公開されています。旧 Docker Hub リポジトリ（yohasebe/wp2txt）は 2.3.1 以降更新されません。

基本的な使い方

自動ダウンロードと処理（推奨）

$ wp2txt --lang=ja -o ./text

日本語Wikipediaダンプを自動的にダウンロードし、プレーンテキストを抽出します。ダウンロードは~/.wp2txt/cache/にキャッシュされます。

タイトルで特定記事を抽出

$ wp2txt --lang=ja --articles="認知言語学,生成文法" -o ./articles

インデックスファイルと必要なデータストリームのみがダウンロードされるため、フルダンプの処理よりはるかに高速です。

カテゴリから記事を抽出

$ wp2txt --lang=ja --from-category="日本の都市" -o ./cities

--depthでサブカテゴリを含める：

$ wp2txt --lang=ja --from-category="日本の都市" --depth=2 -o ./cities

ダウンロードせずにプレビュー（記事数を表示）：

$ wp2txt --lang=ja --from-category="日本の都市" --dry-run

ローカルダンプファイルを処理

$ wp2txt -i ./jawiki-20220801-pages-articles.xml.bz2 -o ./text

その他の抽出モード

# カテゴリ情報のみ（タイトル + カテゴリ）
$ wp2txt -g --lang=ja -o ./category

# サマリーのみ（タイトル + カテゴリ + 冒頭段落）
$ wp2txt -s --lang=ja -o ./summary

# メタデータのみ（タイトル + セクション見出し + カテゴリ）
$ wp2txt -M --lang=ja --format json -o ./metadata

# 特定記事から特定セクションを抽出（高速）
# セクション名は大文字小文字を区別しません。エイリアスマッチングもデフォルトで有効です
$ wp2txt --lang=ja --articles="東京" --sections="summary,概要,歴史" --format json -o ./sections

# カテゴリ内の記事から特定セクションを抽出（中速）
$ wp2txt --lang=ja --from-category="日本の都市" --sections="summary,概要,歴史" --format json -o ./sections

# フルダンプから特定セクションを抽出（低速 - 全記事を処理）
$ wp2txt --lang=ja --sections="summary,概要,歴史,関連項目" --format json -o ./sections

# セクション見出しの統計（抽出前のセクション名の調査に便利）
$ wp2txt --lang=ja --section-stats -o ./stats

# JSON/JSONL出力
$ wp2txt --format json --lang=ja -o ./json

出力サンプル

テキスト出力

[[

JSON/JSONL出力

各行に1つのJSONオブジェクト：

{"title": "記事タイトル", "categories": ["カテゴリ1", "カテゴリ2"], "text": "...", "redirect": null}

リダイレクト記事の場合：

{"title": "NYC", "categories": [], "text": "", "redirect": "New York City"}

キャッシュ管理

$ wp2txt --cache-status           # キャッシュ状態を表示
$ wp2txt --cache-clear            # 全キャッシュをクリア
$ wp2txt --cache-clear --lang=ja  # 日本語のみクリア
$ wp2txt --update-cache           # 強制的に新規ダウンロード

キャッシュが有効期限（デフォルト: 30日）を超えると、wp2txtは警告を表示しますが、キャッシュされたデータの使用は許可されます。

詳細オプション

コンテンツタイプマーカー

特殊コンテンツはデフォルトでマーカープレースホルダーに置き換えられます：

インラインマーカー（文中に出現）：

マーカー	コンテンツタイプ
`[MATH]`	数式
`[CODE]`	インラインコード
`[CHEM]`	化学式
`[IPA]`	IPA発音記号

ブロックマーカー（独立したコンテンツ）：

マーカー	コンテンツタイプ
`[CODEBLOCK]`	ソースコードブロック
`[TABLE]`	Wikiテーブル
`[INFOBOX]`	情報ボックス
`[NAVBOX]`	ナビゲーションボックス
`[GALLERY]`	画像ギャラリー
`[REFERENCES]`	参考文献リスト
`[SCORE]`	楽譜
`[TIMELINE]`	タイムライングラフィック
`[GRAPH]`	グラフ/チャート
`[SIDEBAR]`	サイドバーテンプレート
`[MAPFRAME]`	インタラクティブ地図
`[IMAGEMAP]`	クリッカブル画像マップ

--markersで設定：

$ wp2txt --lang=ja --markers=all -o ./text        # 全マーカー（デフォルト）
$ wp2txt --lang=ja --markers=math,code -o ./text  # MATHとCODEのみ

注意: --markers=noneは非推奨です。特殊コンテンツの完全な削除は周囲のテキストを意味不明にする可能性があります。

テンプレート展開

一般的なMediaWikiテンプレートは自動的に展開されます（デフォルトで有効）：

テンプレート	出力
`date\	1990\	5\	15}`	May 15, 1990
`	100\	km\	mi}`	100 km (62 mi)
`	35\	41\	N\	139\	41\	E}`	35°41′N 139°41′E
`	ja\	日本語}`	日本語
`	Tokyo\	東京\	Tōkyō}`	Tokyo (東京, Tōkyō)
`	1\	2}`	1/2
`	1900}`	c. 1900

サポート対象：日付/年齢テンプレート、単位変換、座標、言語タグ、引用、分数など。パーサー関数（{{#if:}}、{{#switch:}}）とマジックワード（{{PAGENAME}}、{{CURRENTYEAR}}）もサポート。

--no-expand-templatesで無効化。

引用抽出

デフォルトでは引用テンプレートは削除されます。--extract-citationsでフォーマットされた引用を抽出：

$ wp2txt --lang=ja --extract-citations -o ./text

サポート対象：{{cite book}}、{{cite web}}、{{cite news}}、{{cite journal}}、{{Citation}}など。

コマンドラインオプション

Usage: wp2txt [options]

設定ファイル

永続的な設定を作成：

$ wp2txt --config-init

~/.wp2txt/config.ymlが作成されます：

cache:
  dump_expiry_days: 30      # ダンプが古いと見なされるまでの日数（1-365）
  category_expiry_days: 7   # カテゴリキャッシュの有効期限（1-90）
  directory: ~/.wp2txt/cache

defaults:
  format: text              # デフォルト出力形式
  depth: 0                  # デフォルトサブカテゴリ深度

コマンドラインオプションは設定ファイルの設定を上書きします。

オフライン索引・クエリ・MCPサーバー

テキスト抽出に加えて、wp2txtはダンプをローカルな版固定データベースに変換できます。カテゴリ・節見出し・リダイレクト・（オプションで）記事全文のSQLite索引、言語版横断比較のための言語間リンク（langlinks）— すべてオフラインで悉皆的にクエリでき、MCPサーバー経由で LLMエージェントにも公開できます。

$ wp2txt --build-index --fulltext --lang=ja      # 索引の構築
$ wp2txt --find-articles --in-category "映画作品" -D 3 --has-section "あらすじ" --lang=ja
$ wp2txt --search "タイムループ" --in-category "映画作品" -D 3 --lang=ja
$ wp2txt --import-langlinks -L ja --langlinks-langs en,de,fr,zh,ko
$ wp2txt-mcp --lang=ja                           # LLMエージェント向けMCPサーバー

これらのクエリは全記事を走査します（0件 は当該ダンプ版にその語が存在しないことを意味します）。抽出結果には dump 版とクエリを記録した .meta.json サイドカーが付き、あとから再現できます。

→ 詳細は docs/INDEXES.md（英語）を参照：索引構築、オフラインクエリ、全文検索、言語間リンク、言語版横断SQL、MCPツール一覧。

パフォーマンス

MacBook Air M4でのベンチマーク結果（7並列プロセス、ターボモード、ダウンロード時間除く）:

Wikipedia	ダンプサイズ	記事数	処理時間	出力
日本語	4.37 GB	1,485,937	約27分	463ファイル (4.5 GB)
英語	24.2 GB	約680万	約2時間	2,000ファイル (20 GB)

ターボモード（デフォルト）はbz2をXMLチャンクに分割してから並列処理します。ディスク容量を節約するには--no-turboを使用してください（処理速度は低下します）。

注意事項

特殊コンテンツ（数式、コードなど）はデフォルトでプレースホルダーでマークされます。
マークアップのバリエーションや言語固有のフォーマットにより、一部のテキストが正しく抽出されない場合があります。

変更履歴

詳細なリリースノートはCHANGELOG.mdを参照してください。

v2.3.0（2026年7月）: 言語間リンク取り込み、言語版横断SQL（multi-dump ATTACH）、明示タイトル集合の抽出、SQL結果のファイル出力と再現性サイドカー、GHCRイメージ公開。

v2.2.0（2026年7月）: オフラインメタデータ索引、FTS5全文検索、MCPサーバー、query_sql、抽出ジョブ。

v2.1.0（2026年2月）: SQLiteキャッシュ、Ractor並列処理（Ruby 4.0+）、テンプレート展開、コンテンツマーカー、Dockerイメージ更新。

v2.0.0（2026年1月）: 自動ダウンロードモード、カテゴリベース抽出、タイトル指定抽出、JSON出力、ストリーミング処理、Ruby 4.0サポート。

便利なリンク

Wikipedia Database backup dumps

著者

長谷部陽一郎 ([email protected])

参考文献

研究で以下のいずれかを言及していただけると幸いです。

Yoichiro HASEBE. 2006. Method for using Wikipedia as Japanese corpus. Doshisha Studies in Language and Culture 9(2), 373-403.
長谷部陽一郎. 2006. Wikipedia日本語版をコーパスとして用いた言語研究の手法. 『言語文化』9(2), 373-403.

BibTeX:

@misc{wp2txt_2026,
  author = {Yoichiro Hasebe},
  title = {WP2TXT: A command-line toolkit to extract text content and category data from Wikipedia dump files},
  url = {https://github.com/yohasebe/wp2txt},
  year = {2026}
}

ライセンス

このソフトウェアはMITライセンスの下で配布されています。LICENSEファイルを参照してください。