MinishLab/semhash

SemHashとは？

SemHashは、テキスト、画像、音声、その他のあらゆるモダリティの大規模なデータコレクションをクリーンアップするための 軽量なPythonライブラリ です。以下の機能を提供します：

重複項目の削除（セマンティック重複排除）
外れ値のフィルタリング（データの残りの部分に適合しない項目を除去）
代表的なサンプルの選択（コレクション全体の多様性を捉える小さなサンプルセットを選択）。

各レコードをベクトル埋め込みに変換し（テキストには付属の model2vec ライブラリ、または提供するカスタムエンコーダーを使用）、Vicinity（ANNライブラリ）を使用して高速な類似性検索を実行します。APIを使用すると、単一のデータセットで操作したり、2つのデータセットを比較したり（例：学習・テストデータのリーク防止）できます。

なぜこれが必要なのか

高速 – 近似最近傍検索を使用しているため、数百万件のレコードでもCPU上で数秒で処理可能です。
マルチモーダル – テキストと画像にすぐ対応しており、小さな encode プロトコルに従うエンコーダーを提供することで、あらゆるモダリティを追加できます。
説明可能 – 重複排除後、どの項目が重複とみなされたかを確認し、類似度スコアをチェックし、パイプライン全体を再実行することなく閾値を再調整できます。
柔軟なデータ形式 – Pythonのリスト、辞書、Pandas DataFrames、Hugging‑Faceの datasets オブジェクトを受け入れ、複数列のレコード（例：QAペア）も処理できます。

基本概念

概念	機能
Embedding	生データ（テキスト、画像など）を固定サイズの数値ベクトルに変換します。SemHashはデフォルトでテキストに `model2vec` を使用しますが、任意のエンコーダー（Sentence‑Transformers、CLIP、カスタムビジョンモデルなど）をプラグインできます。
ANN backend	類似性検索エンジン。デフォルトは USearch（Vicinity経由）で、高い再現率と速度を実現します。代替としてFAISSや単純な完全一致バックエンドも使用可能です。
SemHash instance	`SemHash.from_records(...)`（または事前計算された埋め込み）で作成されます。データセットと選択したエンコーダー/バックエンドを保持します。
Operations	`self_deduplicate`、`deduplicate`、`self_filter_outliers`、`filter_outliers`、`self_find_representative`、`find_representative`。それぞれが結果オブジェクト（`DeduplicationResult` または `FilterResult`）を返します。
Result objects	`.selected`（保持されたレコード）、`.filtered`（削除されたレコード）、統計（`duplicate_ratio` など）、および `get_least_similar_from_duplicates` や `rethreshold` などのヘルパーメソッドを提供します。

クイックスタート例（テキスト）

from datasets import load_dataset
from semhash import SemHash

texts = load_dataset("ag_news", split="train")["text"]
semhash = SemHash.from_records(records=texts)

# 1️⃣ 重複を削除
clean = semhash.self_deduplicate().selected

# 2️⃣ 外れ値を除去
clean = semhash.self_filter_outliers().selected

# 3️⃣ 小さく多様なサブセットを選択
representative = semhash.self_find_representative().selected

SemHash オブジェクトが構築されれば、これら3つのステップはすべて1行で実行できます。

内部の仕組み（概要）

Embedding – 各レコードは提供されたエンコーダーを通過し、密ベクトルになります。
Indexing – ベクトルはVicinityのANNインデックス（デフォルトはUSearch）に挿入されます。
Similarity search – 各ベクトルに対して最近傍が取得されます。類似度閾値により、2つの項目が重複か外れ値かが決定されます。
Clustering – 重複項目はクラスターにグループ化され、最も中心的な項目が保持されます。
Representative selection – 貪欲な最遠点アルゴリズムにより、埋め込み空間のカバー率を最大化するサブセットが選択されます。

SemHashの用途

学習前のデータクリーニング – モデルにバイアスをかける可能性のある、ほぼ重複した文章や画像を削除します。
リーク検出 – テストセットに学習セットと類似しすぎた項目が含まれていないことを確認します。
データセットの要約 – クイックプロトタイプや人間によるアノテーションのために、小さく多様なサブセットを作成します。
クロスモーダルパイプライン – アイテムを埋め込めるあらゆるドメイン（音声、動画、コード）で、カスタムエンコーダーを使用して重複排除が可能です。

制限事項と注意点

品質はエンコーダーに依存 – 埋め込みモデルがセマンティクスをうまく捉えられない場合、重複が見逃されたり、誤検知が発生したりする可能性があります。
閾値の調整 – デフォルトの類似度閾値は多くのケースで機能しますが、調整が必要な場合があります。ライブラリには rethreshold や get_least_similar_from_duplicates などのツールが用意されています。
メモリ – ANNは計算量を削減しますが、埋め込みの全セットはRAM上に存在するため、非常に大規模なデータセットではバッチ処理やストリーミングが必要になる場合があります。

詳細情報

パッケージ – pip install semhash でインストール（PyPIバッジで現在のバージョンを確認）。
ソースコード – https://github.com/MinishLab/semhash
ドキュメントと例 – READMEには、テキスト、画像、カスタムエンコーダー、Pandas、および異なるANNバックエンドの使用に関する広範なコードスニペットが含まれています。
コミュニティ – サポートや議論のためのDiscordリンクはバッジにあります。
ベンチマーク – パフォーマンス数値については benchmarks/README.md を参照してください（例：CPU上で1.8M件のテキストレコードを約74秒で処理）。

要約

SemHashは、高速でマルチモーダルな重複排除およびフィルタリングツールキットです。生データを埋め込みに変換し、ANNインデックスで重複に近いものを探し、結果を検査または再調整できます。大規模な学習コーパスのクリーニング、データリークの防止、代表的なサブセットの抽出に役立つ、依存関係の少ない軽量なPythonパッケージです。