HC2025 Word Forecaster

日本語テキスト予測のための機械学習アプリケーション

概要

HC2025 Word Forecasterは、日本語テキストを学習し、入力されたコンテキストに基づいて次の単語を予測するWebアプリケーションです。N-gram統計モデルを使用した実用的な言語モデルで、複数のデコーディング戦略をサポートしています。

主な機能

1. テキスト管理

• 日本語テキストファイルのアップロード（.txtファイル）
• アップロードしたテキストの一覧表示・管理
• テキストの削除機能

2. 学習モデル管理

• 学習モデルの作成とカスタマイズ
  • モデル次元（d_model）
  • 注意機構のヘッド数
  • エンコーダー・デコーダー層数
  • フィードフォワード次元
  • 最大シーケンス長
  • ドロップアウト率
• バックグラウンドジョブによる非同期学習
• 学習状態のリアルタイム確認
• 学習エラー時の再学習機能

3. テキスト予測

• 入力テキストからの次単語予測
• 複数のデコーディング戦略のサポート：
  • Greedy（貪欲法）: 最も確率が高い単語を選択
  • Temperature: 温度パラメータによるランダム性の制御
  • Top-K: 上位K個の候補からサンプリング
  • Top-P/Nucleus: 累積確率による動的候補選択
  • Beam Search: 複数経路の並行探索
• 予測結果の詳細表示（確率分布、候補トークンなど）
• 予測履歴の管理

画面イメージ

トップページ	予測結果一覧

アーキテクチャ

言語モデル

現在実装されている言語モデル：

N-gram モデル（現在使用中）

• 統計ベースの言語モデル
• コンテキスト（前のN-1トークン）から次のトークンを予測
• バックオフ戦略により、短いコンテキストにフォールバック
• 高速で軽量

Transformer（実装済み・将来的に使用可能）

• エンコーダー・デコーダーアーキテクチャ
• マルチヘッドアテンション機構
• ポジショナルエンコーディング
• レイヤー正規化とフィードフォワード層

トークナイゼーション

• MeCabによる日本語形態素解析
• 語彙辞書（Vocabulary）の管理
• トークン↔ID の双方向マッピング
• 特殊トークンのサポート（PAD, UNK, BOS, EOS）

デコーディング戦略

戦略	特徴	適用例
Greedy	決定的、高速	事実ベースの質問応答
Temperature	多様性を調整可能	創作文、対話
Top-K	品質と多様性のバランス	自然な会話生成
Top-P	動的候補選択	汎用的（推奨）
Beam Search	最適解の探索	翻訳、要約

技術スタック

バックエンド

• Ruby: 3.4.2
• Rails: 8.0.3
• データベース: SQLite3
• ジョブキュー: Solid Queue（Rails 8デフォルト）

フロントエンド

• Tailwind CSS: スタイリング
• Turbo: SPAライクなページ遷移

機械学習

• MeCab: 日本語形態素解析
• Natto: MeCabのRubyバインディング
• Numo::NArray: 数値計算（Transformerで使用）

その他

• Solid Cable: WebSocket通信
• Solid Cache: キャッシング

セットアップ

前提条件

• Ruby 3.4.2以上
• MeCab（日本語形態素解析器）

MeCabのインストール

macOS:

brew install mecab
brew install mecab-ipadic

Ubuntu/Debian:

sudo apt-get install mecab libmecab-dev mecab-ipadic-utf8

インストール手順

1. リポジトリのクローン

git clone <repository-url>
cd hc2025_word_forecaster

2. 依存関係のインストール

bundle install

3. データベースのセットアップ

rails db:create
rails db:migrate

4. MeCabライブラリパスの設定（必要に応じて）

# macOS (Homebrew)の場合
export MECAB_PATH=/opt/homebrew/lib/libmecab.dylib

# Linuxの場合
export MECAB_PATH=/usr/lib/x86_64-linux-gnu/libmecab.so.2

5. サーバーの起動

rails server

6. ブラウザで http://localhost:3000 にアクセス

使い方

1. テキストデータのアップロード

1. トップページの「新規テキスト追加」をクリック
2. テキストファイル（.txt）を選択してアップロード
3. 複数ファイルをアップロードして学習データを蓄積

2. 学習モデルの作成

1. 「学習モデル」メニューから「新規作成」
2. モデル名とパラメータを設定
3. 「作成」ボタンをクリック

3. モデルの学習

1. 作成したモデルの詳細ページへ移動
2. 学習パラメータ（エポック数、バッチサイズ、学習率）を設定
3. 「学習を開始」をクリック
4. バックグラウンドで学習が実行される
5. ページをリロードして進捗を確認

4. テキストの予測

1. 学習済みモデルの詳細ページから「予測実行」をクリック
2. 入力テキストを入力
3. デコーダータイプとパラメータを選択
4. 「予測実行」をクリック
5. 生成されたテキストと候補トークンを確認

ディレクトリ構成

app/
├── controllers/      # コントローラー
├── models/          # モデル
├── services/        # サービスクラス
├── jobs/            # バックグラウンドジョブ
└── views/           # ビュー

lib/
├── ml/              # 機械学習モジュール
│   ├── ngram_model.rb      # N-gramモデル
│   ├── encoder.rb          # Transformerエンコーダー
│   ├── decoder.rb          # Transformerデコーダー
│   ├── attention.rb        # アテンション機構
│   └── ...
└── tokenizer.rb     # トークナイザー

storage/
├── training_models/ # 学習済みモデルファイル
└── texts/          # アップロードされたテキストファイル

開発者向け情報

デバッグログの有効化

N-gramモデルの予測プロセスをデバッグするには、lib/ml/ngram_model.rbのログ出力を確認してください。開発環境ではデフォルトでdebugログが有効です。

テストの実行

# 全テストの実行（未実装）
rails test

# RSpecを使用する場合
bundle exec rspec

コードスタイル

• RuboCopを使用したコーディング規約
• インデント: 2スペース
• 文字列: ダブルクォート推奨

# コードスタイルチェック
rubocop

# 自動修正
rubocop -a

トラブルシューティング

MeCabエラー

エラー: cannot load such file -- natto

解決方法:

bundle install

エラー: MeCab library not found

解決方法:

# MeCabのインストールを確認
which mecab

# ライブラリパスを設定
export MECAB_PATH=/path/to/libmecab.so

学習が終わらない

• 学習データサイズが大きい場合、時間がかかることがあります
• サーバーログを確認してエラーがないか確認してください
• モデルの詳細ページをリロードして状態を確認

予測結果が空になる

• 学習データに入力テキストと類似のコンテキストが含まれているか確認
• より一般的な入力テキスト（例: "吾輩は"）で試してみる
• デバッグログでNo predictions foundのメッセージを確認

ライセンス

このプロジェクトは教育目的で作成されています。

貢献

プルリクエストを歓迎します。大きな変更の場合は、まずissueを開いて変更内容を議論してください。

今後の拡張予定

• Transformerモデルの実装と切り替え
• モデルの評価指標（Perplexity等）の表示
• テストの追加
• Docker化
• API機能の追加
• ユーザー認証機能