Metadata-Version: 2.4
Name: soramimi-phonetic-search-dataset
Version: 0.0.24
Summary: 音韻的類似性を考慮した検索システムの評価用データセット。替え歌の歌詞から構築された特定ジャンルの単語ペアを収録。
Project-URL: Homepage, https://github.com/jiroshimaya/soramimi-phonetic-search-dataset
Author: shimajiroxyz
License: MIT AND CDLA-Permissive-2.0
License-File: LICENSE-CODE
Keywords: Japanese,dataset,phonetic-search,あいまい検索,替え歌,評価用データセット,音韻検索,音韻類似性
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: editdistance>=0.8.1
Requires-Dist: jamorasep>=0.0.1
Requires-Dist: kanasim>=0.0.4
Requires-Dist: litellm>=1.83.0
Requires-Dist: openai>=2.30.0
Requires-Dist: pyopenjtalk-plus>=0.4.1.post8
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: tqdm>=4.67.1
Description-Content-Type: text/markdown

# soramimi-phonetic-search-dataset

音韻検索システムの評価用データセット。替え歌の歌詞から構築された特定ジャンルの単語ペアを収録。

[日本語](https://github.com/jiroshimaya/soramimi-phonetic-search-dataset/blob/main/README.md) | [English](https://github.com/jiroshimaya/soramimi-phonetic-search-dataset/blob/main/README.en.md)
## 概要

このデータセットは、音韻が類似した単語を検索するシステムの評価に使用できます。
特定ジャンルの単語だけで歌詞の音韻を模倣する替え歌（いわゆる「〇〇で歌ってみた」）から抽出した単語ペアを含み、特に韻やリズムの一致を重視する音韻検索の評価に適しています。

各手法の評価結果は[leaderboard](https://github.com/jiroshimaya/soramimi-phonetic-search-dataset/blob/main/leaderboard.md)をご覧ください。
細かな prompt/input の派生実験や probe スクリプトは、別リポジトリの [soramimi-phonetic-search-experiments](https://github.com/jiroshimaya/soramimi-phonetic-search-experiments) で管理します。

## データセット形式

デフォルトのデータセット [src/soramimi_phonetic_search_dataset/data/baseball.json](src/soramimi_phonetic_search_dataset/data/baseball.json) は、各 query について以下の情報を持ちます。

- `query`: 検索クエリ
- `positive`: 正解となる単語の一覧
- `hard_negatives`: 正解ではないが音韻的に紛らわしい負例の一覧
- `subset` (optional): `easy` / `medium` / `hard` の難易度ラベル

データセットのルート `metadata` には、難易度の算出条件（`k`、優先順位、判定ルール）を記録しています。

`hard_negatives` は、各 query に対して単語リスト全体を `rank_by_vowel_consonant_editdistance` に `vowel_ratio=0.5` を指定して並べ替え、その順位から `positive` に含まれる単語を除いた上位100件として作成しています。

## 使い方

### インストール

```bash
pip install soramimi-phonetic-search-dataset
```

### 基本的な使用例

```python
from soramimi_phonetic_search_dataset import evaluate_ranking_function

# カスタムのランキング関数を定義
def my_ranking_function(
  query_texts: list[str], wordlists: list[list[str]]
) -> list[list[str]]:
    # ここにあなたの音韻的類似度に基づくランキングロジックを実装
    return ranked_wordlists

# 評価の実行
results = evaluate_ranking_function(ranking_func=my_ranking_function, topn=10)
print(f"Recall@10: {results.metrics.recall}")
```

LLMでの試行回数を減らしたい場合は、先頭10件のクエリだけを使う小データセットも利用できます。

```python
from soramimi_phonetic_search_dataset import (
    evaluate_ranking_function,
    load_small_dataset,
)

small_dataset = load_small_dataset()
results = evaluate_ranking_function(
    ranking_func=my_ranking_function,
    topn=10,
    dataset=small_dataset,
)
print(f"Recall@10 on small dataset: {results.metrics.recall}")
```

リポジトリ内のサンプルスクリプトでも `--dataset_size small` を指定すると、同じ10件版で評価できます。

### サンプルのランキング関数

以下のランキング関数が実装済みです：

- `rank_by_mora_editdistance`: モーラ編集距離によるランキング
- `rank_by_vowel_consonant_editdistance`: 母音と子音の編集距離によるランキング
- `rank_by_phoneme_editdistance`: 音素編集距離によるランキング
- `rank_by_kanasim`: [KanaSim](https://github.com/jiroshimaya/kanasim)によるランキング

```python
from soramimi_phonetic_search_dataset import rank_by_mora_editdistance

results = evaluate_ranking_function(ranking_func=rank_by_mora_editdistance, topn=10)
print(results.metrics.recall)
```

## ライセンス

- **ソースコード**は**MITライセンス**の下で提供されています。詳細は[`LICENSE-CODE`](https://github.com/jiroshimaya/soramimi-phonetic-search-dataset/blob/main/LICENSE-CODE)をご覧ください。
- **データセット**は**CDLA-Permissive-2.0**の下で提供されています。詳細は[`src/soramimi_phonetic_search_dataset/data/LICENSE`](https://github.com/jiroshimaya/soramimi-phonetic-search-dataset/blob/main/src/soramimi_phonetic_search_dataset/data/LICENSE)をご覧ください。

## データセット使用上の注意

- このデータセットは、歌詞や実在の人名・キャラクター等の単語リストといった第三者のコンテンツを含んでいます。歌詞データは文節単位で分割・再構成され、元の文脈を復元できないよう慎重に加工されています。また、単語リストは一般に公開されている情報のみを使用しています。

- 研究目的での利用については、商用・非商用を問わず可能です。ただし、以下の点にご注意ください：
  - データセットの利用に関する法令遵守はユーザーの責任となります
  - データセットから元の歌詞を復元する行為は避けてください
  - 単語リストは音韻検索の評価以外の目的での使用はお控えください

## 引用

このデータセットを引用する場合は、以下の形式を使用してください：

```
@inproceedings{島谷2025soramimi,  
  author={島谷 二郎},  
  title={「〇〇で歌ってみた」替え歌を用いた音韻類似単語検索ベンチマークの構築},  
  booktitle={言語処理学会第31回年次大会 併設ワークショップ JLR2025},
  url={https://github.com/jiroshimaya/soramimi-phonetic-search-dataset},  
  year={2025},  
  month={3},  
}
```
