Upload folder using huggingface_hub

README.md

@@ -82,6 +82,14 @@ source .venv/bin/activate
 uv sync
 ```
 
+### Running on Hugging Face Spaces (CPU)
+- Use Python 3.11 in Space settings (or metadata).
+- Add `requirements.txt` and `packages.txt` from this repo to the Space root.
+  - `requirements.txt` pins `numpy<2` and CPU wheels for PyTorch 2.2.x and PyG.
+  - `packages.txt` installs MeCab and JUMANDIC via apt.
+- Rebuild the Space and verify:
+  - `python -c "import numpy, torch; print(numpy.__version__, torch.__version__)"` shows NumPy 1.26.x and Torch 2.2.x.
+
 ## Quickstart (Morphological analysis)
 
 ```bash

packages.txt

@@ -2,4 +2,4 @@ mecab
 mecab-utils
 libmecab-dev
 mecab-jumandic-utf8
-mecab-ipadic-utf8
+

readme2.md

@@ -0,0 +1,195 @@
+# Mecari (Japanese Morphological Analysis with Graph Neural Networks)
+
+本ドキュメントは既存の README を整理し、セットアップや再現、評価の手順、既知の制限やトラブルシュートを強化した改訂版です。
+
+- Demo: https://huggingface.co/spaces/zbller/Mecari （推論デモ。CPU/ブラウザ実行、学習は未対応）
+
+## 目次
+- 概要
+- 結果（KWDLC）
+- 動作環境
+- MeCab のセットアップ
+- プロジェクトセットアップ（uv / pip）
+- クイックスタート（形態素解析）
+- 学習と評価（KWDLC）
+- コンフィグ概要
+- 実験ディレクトリと再開
+- トラブルシュート
+- 既知の制限
+- ライセンスと謝辞
+- 参考文献
+
+## 概要
+Mecari は、公開研究 [1] のアイデアに着想を得た GNN（Graph Neural Network）ベースの日本語形態素解析器です。MeCab（JUMANDIC）の候補からグラフを構築し、部分アノテーション（'+'/'-'、'?'は学習で無視）で学習可能、学習・推論の高速化を重視しています。ノードには JUMAN++ 風のユニグラム特徴量、エッジは無向（双方向）として扱い、GATv2 [2] を学習します。推論ではノードスコアに基づき Viterbi で非重複の最適経路を探索します。
+
+## 結果（KWDLC）
+- 学習済み（`sample_model`）: Seg F1 0.9725, POS F1 0.9562
+- MeCab（JUMANDIC）: Seg F1 0.9677, POS F1 0.9465
+
+再現メモ
+- データ: 公式 KWDLC の `dev.id`/`test.id` 分割を使用
+- コンフィグ: `configs/gatv2.yaml`（`extends: base.yaml`）
+- 乱数: `training.seed: 42`
+- 決定性: 既定は `deterministic: false`（高速重視）。厳密再現性が必要なら true を推奨（速度低下に注意）
+
+## 動作環境
+- OS: Ubuntu 24.04.3 LTS（確認済）
+- Python: 3.11.3（`>=3.11,<3.12`）
+- PyTorch: 2.2.2+cu121（CPU でも可）
+- CUDA ランタイム: 12.1（GPU 使用時）
+- MeCab: 0.996、JUMANDIC: `/var/lib/mecab/dic/juman-utf8`
+- 備考: Mac/Windows は未検証。PyTorch Geometric のホイール互換に注意
+
+## MeCab のセットアップ（Ubuntu 24.04）
+1) インストール（JUMANDIC 同梱）
+```bash
+sudo apt update
+sudo apt install -y mecab mecab-utils libmecab-dev mecab-jumandic-utf8
+```
+2) 確認
+```bash
+mecab -v                           # 例: 0.996
+[ -d /var/lib/mecab/dic/juman-utf8 ] && echo "JUMANDIC OK"
+```
+ヒント
+- MeCab バイナリは `MECAB_BIN` で上書き可（例: `MECAB_BIN=/usr/local/bin/mecab`）。
+- JUMANDIC のパスは前処理（`preprocess.py`）で `--jumandic-path` を指定可能。
+- `infer.py`/`evaluate.py` はデフォルトで `/var/lib/mecab/dic/juman-utf8` を参照します。
+
+## プロジェクトセットアップ
+選択肢 A: uv を使用（推奨）
+```bash
+# uv インストール（未導入の場合）
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 仮想環境作成と依存解決
+uv venv
+source .venv/bin/activate
+uv sync
+```
+`pyproject.toml` の `[tool.uv.find-links]` で PyG の CUDA 12.1 対応ホイールを指定済みです。
+
+選択肢 B: pip を使用
+```bash
+python -m venv .venv
+source .venv/bin/activate
+# PyG ホイールの互換 URL を指定（Torch 2.2.x + cu121）
+pip install torch==2.2.*
+pip install --find-links https://data.pyg.org/whl/torch-2.2.0+cu121.html torch-geometric==2.4.*
+# 残りをインストール
+pip install -e .
+```
+CPU のみで使う場合は CUDA 関連の依存は不要ですが、PyG の互換は維持してください。
+
+## クイックスタート（形態素解析）
+```bash
+# サンプルモデルで 1 文を解析
+python infer.py --text "東京都の外国人参政権"
+
+# 対話モード
+python infer.py
+
+# 学習後の実験を指定して推論
+python infer.py --experiment gatv2_YYYYMMDD_HHMMSS --text "..."
+```
+注意
+- 実験未指定時は `sample_model/` を読み込み。
+- 既定デバイスは CPU。実験情報により GPU を使用する場合があります。
+
+出力例（概形）
+```
+東京都 名詞,固有名詞,*,*,*,*,トウキョウト
+の     助詞,連体化,*,*,*,*,ノ
+外国人 名詞,一般,*,*,*,*,ガイコクジン
+参政 権 名詞,一般,*,*,*,*,サンセイケン
+```
+
+## 学習と評価（KWDLC）
+KWDLC の取得
+```bash
+cd /path/to/Mecari
+git clone --depth 1 https://github.com/ku-nlp/KWDLC
+```
+- ライセンス・利用許諾は KWDLC リポジトリを参照。
+- 分割は公式 `dev.id` / `test.id` に厳密に従います。
+
+前処理（アノテーションとグラフ生成）
+```bash
+python preprocess.py --config configs/gatv2.yaml
+# 必要に応じて辞書パスを明示
+# python preprocess.py --config configs/gatv2.yaml --jumandic-path /path/to/juman-utf8
+```
+- 出力先は `training.annotations_dir`（既定: `annotations`）。未設定の場合は `annotations_kwdlc_juman` に保存されます。
+- MeCab 解析結果は候補整形・重複除去後、'+'/'-'/ '?' を付与して保存し��す。
+
+学習
+```bash
+python train.py --config configs/gatv2.yaml
+# 例: ロギングを無効化
+# python train.py --config configs/gatv2.yaml --no-wandb
+```
+- 結果は `experiments/<name>/` に保存され、`config.yaml` と `checkpoints/` が生成されます。
+- 乱数 `seed=42`。`deterministic` を true にすると再現性は上がりますが、速度が低下します。
+
+評価
+```bash
+python evaluate.py --experiment gatv2_YYYYMMDD_HHMMSS --max-samples 50
+```
+- `evaluate.py` は CPU で評価します。
+- MeCab（JUMANDIC）の辞書パスは現状 `'/var/lib/mecab/dic/juman-utf8'` に固定されています。環境差がある場合はシンボリックリンク作成かコードの該当箇所を変更してください。
+
+## コンフィグ概要
+主なキー（`configs/gatv2.yaml` は `base.yaml` を継承）
+- features.lexical_feature_dim: ユニグラム特徴量の次元（既定 100000）
+- edge_features.use_bidirectional_edges: 双方向エッジの使用（既定 true）
+- model.type: `gatv2` のみ対応
+- model.hidden_dim/num_layers/num_heads/dropout: GATv2 の主要ハイパラ
+- training.learning_rate/batch_size/max_steps: 学習率・バッチサイズ・ステップ数
+- training.patience: 早期終了の待機ステップ
+- training.gradient_clip_val/algorithm: 勾配クリップ
+- training.num_workers: DataLoader のワーカ数
+- training.accumulate_grad_batches: 勾配蓄積
+- training.seed: 乱数シード（既定 42）
+- training.use_wandb: Weights & Biases ロギング（既定 true）
+- training.annotations_dir: 前処理出力の読込先（既定 `annotations`）
+- inference.checkpoint_dir: 推論用チェックポイント探索ルート（既定 `experiments`）
+- loss.use_pos_weight: 不均衡対策での正例重み付け
+
+## 実験ディレクトリと再開
+- 構成: `experiments/<name>/config.yaml`, `experiments/<name>/checkpoints/*.ckpt`
+- 学習再開
+```bash
+python train.py --config configs/gatv2.yaml --resume gatv2_YYYYMMDD_HHMMSS
+```
+- 推論で学習済みモデルを指定
+```bash
+python infer.py --experiment gatv2_YYYYMMDD_HHMMSS --text "..."
+```
+
+## トラブルシュート
+- MeCab の辞書パスが見つからない: `/var/lib/mecab/dic/juman-utf8` を確認。場所が異なる場合はリンク作成、または `preprocess.py` の `--jumandic-path` を使用。
+- PyG ホイール不整合: Torch と CUDA バージョンに合致する `find-links` を指定。
+- kyoto-reader が見つからない/解析失敗: `pip install kyoto-reader` を確認。KNP ファイルのエンコーディングに注意。
+- GPU メモリ不足: バッチサイズを下げる、`precision="16-mixed"` 既定の確認、あるいは CPU での学習を検討。
+- uv が使えない: pip 手順（上記）を使用。
+- ネットワーク制限で W&B 失敗: `--no-wandb` または `training.use_wandb: false` に設定。
+
+## 既知の制限
+- 学習は KWDLC 前提（他コーパス未対応）。
+- '?' は学習時に無視。'+' と重なりを持つ候補は '-' に降格。
+- 品詞体系は JUMANDIC に依存。
+- 推論・評価は単一路（ベストパス）。
+- Mac/Windows は未検証。
+
+## ライセンスと謝辞
+- ライセンス: CC BY-NC 4.0（非商用）。コード・学習済みモデル・ドキュメントに適用。
+- 免責: 教育・研究目的の独立実装です。Google 等と関係はありません。
+- 謝辞: MeCab/JUMANDIC、kyoto-reader、PyTorch / PyTorch Geometric、Weights & Biases ほか関連 OSS に感謝します。
+
+## 参考文献
+- [1] Gleb Mazovetskiy, Taku Kudo, "Data processing for Japanese text-to-pronunciation models", NLP2024 Workshop on Japanese Language Resources. https://jedworkshop.github.io/JLR2024/materials/b-2.pdf （pp. 19–23）
+- [2] Shaked Brody, Uri Alon, Eran Yahav, "How Attentive are Graph Attention Networks?", ICLR 2022. https://openreview.net/forum?id=R7Pl7yr-KX
+
+---
+補足: 既存の `README.md` は簡潔な導入として維持し、本ファイル（`readme2.md`）は詳細版として併用する想定です。
+

requirements.txt

@@ -1,20 +1,14 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
 --find-links https://data.pyg.org/whl/torch-2.2.0+cpu.html
 
-# Core runtime
+# Pin to NumPy 1.x to avoid ABI issues on Spaces
+numpy<2
+
+# CPU PyTorch and compatible PyG
 torch==2.2.2
-torch-scatter
-torch-sparse
-torch-cluster
-torch-spline-conv
-torch-geometric==2.4.0
-pytorch-lightning==2.5.2
-numpy>=1.24,<2.1
-pyyaml>=6.0
-tqdm>=4.65.0
-kyoto-reader>=2.5.0
+torch-geometric==2.4.*
 
-# UI
-gradio>=4.37.0
+# Project runtime deps
+pyyaml>=6
+tqdm>=4.65
 
-# Optional logger (disabled at runtime)
-wandb>=0.15.0