huggingface/sentence-transformers

Sentence-Transformers とは？

Sentence-Transformersは、Hugging Face Transformersをベースにした テキスト埋め込み (text embedding) モデルを簡単に扱えるようにするPythonライブラリです。以下のような機能のための、軽量で使いやすいAPIを提供します：

高密度または疎な文埋め込みの計算（各文を、保存、比較、インデックス化可能な固定サイズのベクトルに変換します）。
Cross-Encoderによるリランキング – クエリとドキュメント のペアを直接スコアリングするモデルで、検索・リランクパイプラインの第2段階に役立ちます。
後期相互作用 / マルチベクトルエンコーダー (ColBERTスタイル) – トークンレベルのベクトルを保持し、より正確な類似度を実現します。
トレーニング / 微調整 – 上記のモデルタイプを独自のデータでトレーニングまたは微調整できます。

これらすべてが単一のパッケージにまとめられており、Hugging Face Hubでホストされている 15,000以上の事前学習済みモデル を利用して、多くの言語やタスクをカバーできます。

クイックスタート（コピー＆ペースト可能なコード）

# ライブラリのインストール (Python 3.10+, PyTorch 2.2+, transformers 5.0+ を推奨)
# pip install -U sentence-transformers

# 1️⃣ 既存の高密度埋め込みモデルをロード
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium."
]
emb = model.encode(sentences)          # 形状 → (3, 384)
print(emb.shape)

# 2️⃣ ペアごとの類似度を計算（コサイン類似度のようなスコア）
print(model.similarity(emb, emb))

リランキングの例 (Cross-Encoder)：

from sentence_transformers import CrossEncoder
ranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
query = "How many people live in Berlin?"
passages = [
    "Berlin had a population of 3,520,031 registered inhabitants…",
    "Berlin has a yearly total of about 135 million day visitors…",
    "In 2013 around 600,000 Berliners were registered in sport clubs."
]
# 各 (クエリ, パッセージ) ペアをスコアリング
scores = ranker.predict([(query, p) for p in passages])
print(scores)
# またはライブラリにランキングを任せる
print(ranker.rank(query, passages, return_documents=True))

疎な埋め込みの例：

from sentence_transformers import SparseEncoder
sparse = SparseEncoder("naver/splade-cocondenser-ensembledistil")
emb = sparse.encode(["The weather is lovely today."])
print(emb.shape)          # 例: (1, 30522) – 語彙トークンごとに1次元
print(SparseEncoder.sparsity(emb))

後期相互作用 (マルチベクトル) の例：

from sentence_transformers import MultiVectorEncoder
mv = MultiVectorEncoder("lightonai/GTE-ModernColBERT-v1")
q_emb = mv.encode_query(["What is the capital of France?"])
 d_emb = mv.encode_document(["Paris is the capital of France.", "Berlin is the capital of Germany."])
print(mv.similarity(q_emb, d_emb))

どのような時に使用するか？

シナリオ	推奨モデルタイプ	Sentence-Transformersを使う理由
セマンティック検索 / 検索	高密度または疎エンコーダー	`model.encode` 1行でFAISSやAnnoyなどでインデックス可能なベクトルを作成
トップk結果のリランク	Cross-Encoder (リランカー)	クエリとドキュメントのペアを直接スコアリングし、精度を向上
ハイブリッド検索 (高密度 + 疎)	高密度エンコーダーと疎エンコーダーの組み合わせ	語彙マッチングとセマンティック類似度を同時に活用
多言語類似度	多言語 Sentence-BERT モデル	100以上の言語でそのまま動作
RAMが限られた大規模コーパス	疎または Matryoshka 埋め込み	疎ベクトルは非常に小さく、Matryoshkaはオンザフライで切り詰め可能
カスタムデータセットでの微調整	4つのモデルファミリーのいずれか	20以上の損失関数とトレーニングユーティリティを同梱

内部の仕組み

ベースTransformer – 🤗 TransformersのBERT/RoBERTaなどのモデル。
プーリング層 – 高密度モデルでは、トークン埋め込みを単一の文ベクトルに集約します（平均、CLS、最大プーリングなど）。
Cross-Encoderヘッド – 連結されたペア [CLS] query [SEP] passage を受け取り、関連性スコアを出力する分類ヘッド。
疎ヘッド – 語彙分布を予測し、高次元の疎ベクトル（SPLADEなど）を生成します。
マルチベクトルヘッド – トークンレベルの埋め込みを保持し、単一ベクトルに集約せずに後期相互作用スコアリングを可能にします。

これらのコンポーネントはすべて `sentence_transformers` パッケージに統合されているため、ボイラープレートコードを自分で書く必要はありません。

ライブラリの入手

# 推奨されるPythonバージョン
pip install -U sentence-transformers

オプションの追加機能（pip install "sentence-transformers[train]" などでインストール）により、以下がサポートされます：

画像 / 音声 / 動画 エンコーダー ([image], [audio], [video])
ONNX / OpenVINO エクスポートによる高速推論 ([onnx], [openvino])
トレーニングユーティリティ ([train])
開発ツール ([dev])

ドキュメントとコミュニティ

完全なドキュメント：www.sbert.net – インストールガイド、APIリファレンス、チュートリアル、モデルZooが含まれています。
モデルハブ：🤗 Hub – library=sentence-transformers – 15,000以上の事前学習済みモデルを閲覧できます。
ブログ記事：トレーニングガイド、マルチモーダル拡張、効率化のヒント（Matryoshka、静的埋め込み、量子化）。
問題と貢献：CONTRIBUTING.md を参照してください。メンテナーは Tom Aarsen (🤗 Hugging Face) です。

引用

研究でこのライブラリを使用する場合は、オリジナルのSentence-BERT論文 (Reimers & Gurevych 2019) を、多言語モデルの場合は2020年の蒸留論文を引用してください。書誌情報はREADMEに記載されています。