natsume-simpleは日本語の係り受け関係を検索できるシステム
本プロジェクトには以下の3つの開発環境のセットアップ方法があります：
VSCodeとDev Containersの拡張機能をインストールした後：
- このリポジトリをクローン：
git clone https://github.com/borh/natsume-simple.git- VSCodeでフォルダを開く
- 右下に表示される通知から、もしくはコマンドパレット（F1）から「Dev Containers: Reopen in Container」を選択（natsume-simple）
- コンテナのビルドが完了すると、必要な開発環境が自動的に設定されます
上記はローカルですが、Codespacesで作り、Githubクラウド上の仮想マシンで入ることもできます。 その場合は、Github上の「Code」ボタンから「Codespaces」を選択し、「Create codespace on main」でブラウザ経由でDev Containerに入れます。 また、同じことはVSCode内のGitHub Codespaces拡張機能でもできます。
- Determinate Nix InstallerでNixをインストール：
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | \
sh -s -- install- プロジェクトのセットアップ：
git clone https://github.com/borh/natsume-simple.git
cd natsume-simple
nix develop以下のツールを個別にインストールする必要があります：
- git
- Python 3.12以上
- uv
- Node.js
- pandoc
その後：
git clone https://github.com/borh/natsume-simple.git
cd natsume-simple
uv sync --extra backend
cd natsume-frontend && npm install && npm run build && cd ..開発環境に入るには以下のコメントを実行：
# 開発環境に入る
nix develop
# または direnvを使用している場合（推奨）
direnv allow注意：
- 各コマンドは自動的に必要な依存関係をインストールします
nix developで入る開発環境には以下が含まれています：- Python 3.12
- Node.js
- uv（Pythonパッケージマネージャー）
- pandoc
- その他開発に必要なツール
The following commands are available after entering the development environment:
watch-all- Start development servers (backend + frontend)
build-frontend- Build the frontend for productionwatch-frontend- Start frontend in development mode with hot reload
watch-dev-server- Start backend server in development modewatch-prod-server- Start backend server in production mode
ensure-database- Ensure database exists and is up-to-dateinitial-setup- Initialize Python environment and dependencies
prepare-data- Prepare corpus data and load into databaseextract-patterns- Extract patterns (collocations)
lint- Run all linters and formattersrun-tests- Run the test suite with pytest
run-all- Initialize database, prepare data, extract patterns and start server
ACCELERATOR- Current accelerator type (cpu/cuda/rocm)PC_PORT_NUM- Process compose port (default: 10011)
Type h to see this command overview again
Note: The default command (nix run) will start the backend server in production mode (watch-prod-server).
# Process all standard corpora
python src/natsume_simple/data.py --corpus-type all --data-dir data
# Process specific corpus types
python src/natsume_simple/data.py --corpus-type jnlp --name "自然言語処理" --data-dir data
python src/natsume_simple/data.py --corpus-type ted --name "TED" --data-dir data
python src/natsume_simple/data.py --corpus-type wikipedia --name "Wikipedia" --data-dir data
# Process generic corpus with custom directory
python src/natsume_simple/data.py --corpus-type generic --name "my-corpus" --dir path/to/corpus --data-dir data# Process all unprocessed sentences
python src/natsume_simple/pattern_extraction.py --data-dir data
# Process specific corpus with options
python src/natsume_simple/pattern_extraction.py \
--data-dir data \
--model ja_ginza \
--corpus ted \
--sample 0.1 \
--batch-size 1000 \
--clean \
--debug
# Process only unprocessed sentences
python src/natsume_simple/pattern_extraction.py \
--data-dir data \
--unprocessed-only
# Set custom random seed
python src/natsume_simple/pattern_extraction.py \
--data-dir data \
--seed 42# Show row counts for all tables
python src/natsume_simple/database.py \
--data-dir data \
--action show-counts
# Clean pattern data while preserving corpus data
python src/natsume_simple/database.py \
--data-dir data \
--action clean-patterns# Run with FastAPI CLI in development mode
uvicorn src.natsume_simple.server:app --reload
# Run with FastAPI CLI in production mode
uvicorn src.natsume_simple.server:app
# Available API endpoints:
# GET /corpus/stats - Get corpus statistics
# GET /corpus/norm - Get normalization factors
# GET /npv/{search_type}/{term} - Search for collocations
# GET /sentences/{n}/{p}/{v}/{limit} - Get example sentences
# GET /search/{query} - Search for terms
# Example API calls:
curl http://localhost:8000/corpus/stats
curl http://localhost:8000/npv/noun/本
curl http://localhost:8000/npv/verb/読む
curl http://localhost:8000/sentences/本/を/読む/5
curl http://localhost:8000/search/読The following modules provide functionality used by other modules but don't have direct CLI interfaces:
log.py- Logging configurationutils.py- Utility functions like random seed setting
Example usage in Python code:
from natsume_simple.log import setup_logger
from natsume_simple.utils import set_random_seed
logger = setup_logger(__name__)
set_random_seed(42)This project uses Nix flakes to manage the development environment and builds. The following commands are available:
# Format
nix fmt
# Build
nix build .#command-name
# Build results are linked in ./results
# Show development shell info
nix develop --print-build-logs- 特定の係り受け関係（名詞ー格助詞ー動詞，名詞ー格助詞ー形容詞など）における格助詞の左右にある語から検索できる
- 検索がブラウザを通して行われる
- 特定共起関係のジャンル間出現割合
- 特定共起関係のコーパスにおける例文表示
このプロジェクトは以下のファイルを含む：
.
├── data/ # コーパスとパターン抽出結果
│ └── corpus.db # データベース（ensure-databaseで取得可）
│
├── notebooks/ # 分析・可視化用Jupyterノートブック
│ ├── pattern_extraction.ipynb # パターン抽出処理の開発用
│ └── visualization.ipynb # データ可視化用
│
├── natsume-frontend/ # Svelteベースのフロントエンド
│ ├── src/ # アプリケーションソース
│ │ ├── routes/ # ページルーティング
│ │ └── tailwind.css # スタイル定義
│ ├── static/ # 静的アセット
│ └── tests/ # フロントエンドテスト
│
├── src/natsume_simple/ # バックエンドPythonパッケージ
│ ├── server.py # FastAPIサーバー
│ ├── database.py # データベース関連
│ ├── data.py # データ処理
│ ├── pattern_extraction.py # パターン抽出ロジック
│ ├── log.py # ログ設定
│ └── utils.py # ユーティリティ関数
│
├── scripts/ # データ準備スクリプト
│ ├── get-jnlp-corpus.py # コーパス取得
│ └── convert-jnlp-corpus.py # コーパス変換
│
├── tests/ # バックエンドテスト
│ └── test_models.py # モデルテスト
│
├── pyproject.toml # Python依存関係定義
├── flake.nix # Nix開発環境定義
└── README.md # プロジェクトドキュメント
各種のデータはdataに保存する。 特にscriptsやnotebooks下で行われる処理は，最終的にdataに書き込むようにする。
特に動的なプログラミングをするときや，データの性質を確認したいときに活用する。 ここでは，係り受け関係の抽出はすべてノートブック上で行う。
VSCodeなどでは，使用したいPythonの環境を選択の上，実行してください。
Google Colabで使用する場合は，リンクから開くか，pattern_extraction_colab.ipynbのファイルをColabにアップロードして利用する。
Jupyter Notebook/JupyterLabでは使用したPythonの環境をインストールの上，Jupterを立ち上げてください。
jupyter lab右上のメニューに選択できない場合は環境に入った上で下記コマンドを実行するとインストールされる：
python -m ipykernel install --user --name=$(basename $VIRTUAL_ENV)Svelte 5で書かれた検索インターフェース。
Svelteのインターフェース（html, css, jsファイル）は以下のコマンドで生成できる：
（natsume-frontend/フォルダから実行）
npm install
npm run buildSvelteの使用にはnodejsの環境整備が必要になる。
サーバ読む静的ファイルを含むファルダ。
上記のnpm run buildコマンド実行でstatic/下にフロントエンドのファイルが作成される。
ここに置かれるものは基本的にAPIのstatic/URL下で同一ファイル名でアクセス可能。
係り受け解析に使用されるモデルを利用するために以下のようにloadする必要がある。 環境設定が正常かどうかも以下のコードで検証できる。
import spacy
nlp = spacy.load('ja_ginza_bert_large')あるいは
import spacy
nlp = spacy.load('ja_ginza')notebooksにあるノートブックでは，優先的にja_ginza_bert_largeを使用するが，インストールされていない場合はja_ginzaを使用する。
プロジェクト環境内でノートブックを作れば，from natsume_simple.pattern_extraction import normalize_verb_spanなど個別に関数をインポートし，動的にテストすることができる。