キーワード検索機能（タタキ台）について
キーワード検索機能の検討用タタキ台として作成したリポジトリのREADMEを整理した内容です。 GitHub上のリポジトリは社内向け・非公開のため、フォルダそのものを共有しています。 ※実装仕様書ではなく、機能理解・検討用の資料です。
動作確認はMac 環境で行っています。
求人・求職者キーワードマッチングシステム (Cognavi Keyword)
理系学生(大学4年生・大学院生)を対象にした、企業の求人情報と求職者のプロフィールをキーワードベースでマッチングさせるシステム
本番環境（外部アクセス可）
https://cognavi-keyword.cap.six1.jp
機能
- 求人データからのキーワード自動抽出
- キーワード間の意味的類似度に基づく関連キーワード検索
- 関連キーワードを含めた拡張検索
- キーワードクラスタリング (HDBSCAN)
- Web UI による検索インターフェース
技術スタック
バックエンド
- Python 3.10+
- NLP: SudachiPy, GiNZA, sentence-transformers
- ML: scikit-learn, HDBSCAN
- Web: FastAPI
- CLI: Typer
フロントエンド
- Tailwind CSS v3
- 静的HTML + JavaScript
アーキテクチャ
cognavi-keyword/
├── data/ # データファイル
│ ├── raw/ # 元のExcelファイル
│ ├── processed/ # 前処理済みCSV
│ ├── keywords/ # 抽出キーワード
│ ├── related/ # 関連キーワードデータ
│ ├── clusters/ # クラスタリング結果
│ └── embeddings/ # 埋め込みベクトル
├── config/ # 設定ファイル
├── src/cognavi_keyword/ # ソースコード
│ ├── api/ # FastAPI
│ ├── cli/ # CLIツール
│ ├── nlp/ # NLP処理
│ ├── db/ # リポジトリ
│ └── common/ # 共通ユーティリティ
├── static/ # 静的ファイル (HTML/CSS/JS)
├── tests/ # テスト
└── docs/ # ドキュメント
セットアップ (初めての方へ)
1. リポジトリのクローン
git clone <https://github.com/tomohirof/cognavi-keyword.git>
cd cognavi-keyword
2. Python仮想環境の作成
python3 -m venv venv
source venv/bin/activate # Windowsの場合: venv\\Scripts\\activate
3. 依存パッケージのインストール
pip install -e ".[dev]"
4. spaCyモデルのダウンロード
python -m spacy download ja_ginza
5. Node.jsパッケージのインストール (CSS開発時のみ)
npm install
6. 設定ファイルのコピー
cp config/.env.example config/.env
# 必要に応じて.envファイルを編集
7. データファイルの確認
以下のファイルが必要です:
data/raw/求人データ.xlsx- 求人データ (元データ)data/raw/企業.xlsx- 企業データ (元データ)
これらは事前に data/keywords/ と data/related/ に処理済みデータとして含まれています。
開発サーバーの起動
source venv/bin/activate
uvicorn cognavi_keyword.api.main:app --host 0.0.0.0 --port 8000 --reload
ブラウザで以下にアクセス:
- 検索UI: http://localhost:8000/
- API Docs: http://localhost:8000/docs
CLIコマンド
データ取り込み (Excel → CSV)
ckw ingest --input data/raw/求人データ.xlsx --output data/processed/jobs.csv
キーワード抽出
# v2キーワード抽出 (推奨)
ckw keywords-v2 --input data/processed/jobs.csv --output data/keywords/jobs_keywords_v2.csv
関連キーワード計算
ckw related --input data/keywords/jobs_keywords_v2.csv --output data/related/jobs_related_v2.json
API エンドポイント
キーワード検索
# v2検索API (推奨)
curl -X POST <http://localhost:8000/api/v2/search> \\
-H "Content-Type: application/json" \\
-d '{"query": "機械設計", "top_k": 10, "include_related": true}'
関連キーワード取得
curl "<http://localhost:8000/api/v1/keywords/機械学習/related?limit=5>"
クラスタAPI
クラスタリング関連の仕様およびAPIの詳細については、
本資料とあわせて共有しているフォルダ内（docs 配下）に含まれる資料を参照してください。
# クラスタリング実行
curl -X POST <http://localhost:8000/api/v1/clusters/create> \\
-H "Content-Type: application/json" \\
-d '{"keywords": ["機械学習", "深層学習"], "min_cluster_size": 3}'
# クラスタ一覧
curl <http://localhost:8000/api/v1/clusters>
テスト
# 全テスト実行
pytest
# 高速テストのみ (MLモデル不使用)
pytest -m "not slow and not ml"
# 特定のテストファイル
pytest tests/unit/test_cluster_api.py -v
Tailwind CSS
CSSの変更時は以下でコンパイル:
npm run build:css
監視モード (開発時):
npm run watch:css
デプロイ (CapRover)
caprover deploy
データ仕様
キーワードデータ (v2)
- 総キーワード数: 2,895語 (ストップワード適用後)
- ソース: 713件の求人データ
- フォーマット: CSV (
data/keywords/jobs_keywords_v2.csv)
関連キーワードデータ
- 類似度閾値: 0.45
- フォーマット: JSON (
data/related/jobs_related_v2.json) - 埋め込みベクトル: NumPy配列 (
data/related/jobs_keywords_v2_embeddings.npy)
トラブルシューティング
spaCyモデルのエラー
python -m spacy download ja_ginza
Tailwind CSSが適用されない
npm run build:css
APIサーバーが起動しない
仮想環境が有効になっていることを確認:
source venv/bin/activate
which python # venv内のPythonが表示されるはず
ドキュメント
- 設計構想・将来計画
- システムの設計思想および、今後の発展案をまとめた資料
- Cluster API仕様書
- クラスタリングAPIの詳細仕様を記載した資料
※上記資料は、共有しているフォルダ内（docs 配下）に含まれています。
ライセンス
MIT License
作成者
Fukuda Tomohiro