| name | search-model-builder |
| description | HuggingFace/sentence-transformers ベースの検索・情報検索モデル（Bi-Encoder, Cross-Encoder, ColBERT, SPLADE 等）構築ガイド。Web調査による最新コード取得、データ前処理、訓練ループ設計、Weights & Biases連携、計算効率最適化をカバー。検索モデルの新規構築・ファインチューニング・評価時に使用。 |
検索モデル構築ガイド
HuggingFace/sentence-transformers ベースの検索・情報検索モデル構築ガイド。
重要: HuggingFace のAPI・コードは頻繁に変更される。モデル実装の具体的なコードは毎回 WebFetch/WebSearch で最新情報を取得すること。本スキルには安定的な知識（訓練ループ、前処理パターン等）のみを記載する。
ワークフロー
1. 要件確認 → タスク種別・データ・制約を整理
2. リソース見積もり → GPU/VRAM/ディスク/訓練時間の概算（下記参照）
3. Web調査 → 最新API・モデルクラス・損失関数を調査
4. データ前処理 → データ読み込み・前処理・DataLoader構築
5. モデル構築 → Web調査結果を基にモデルを構築
6. 訓練設定 → optimizer/scheduler/W&B設定
7. スモークテスト → 小規模データ（100件）で訓練ループが回ることを確認
8. 訓練実行 → 訓練ループ実行・進捗監視
9. 評価 → 検索指標で性能評価
10. 保存・共有 → モデル保存・HuggingFace Hub公開（任意）
リソース見積もり（必須）
訓練開始前に必ず以下を確認:
GPU:
- torch.cuda.is_available() で GPU が利用可能か確認
- GPU 無しでの BERT ファインチューニングは非現実的（1エポック数日）
- VRAM 容量に応じたバッチサイズを選択（後述の目安表参照）
訓練時間の概算:
total_steps = len(dataset) / batch_size * num_epochs
→ 1ステップあたりの時間をスモークテストで計測
→ total_steps * step_time で総訓練時間を見積もる
→ 24時間を超える場合はデータ量・エポック数・モデルサイズを再検討
ディスク容量:
- ベースモデル: 0.4〜2GB（ダウンロード時）
- チェックポイント: モデルサイズ x 3（model + optimizer state）x 保存数
- 例: 335Mモデル + AdamW = 約4GB/チェックポイント
- 10エポック保存 = 40GB+（cleanup_checkpoints で古いものを削除）
RAM:
- データセット全件メモリ展開: 件数 x 平均テキストサイズで概算
- 100万件超は streaming=True を検討
モデルアーキテクチャ選択ガイド
特性比較
| アーキテクチャ | レイテンシ | 精度 | インデックス | 主な用途 |
|---|
| Bi-Encoder | 低（事前計算可） | 中 | ベクトル検索 | 大規模検索、セマンティック検索 |
| Cross-Encoder | 高（ペア推論） | 高 | 不可 | リランキング、小規模分類 |
| ColBERT | 中 | 高 | トークンレベル | 高精度検索、遅延インタラクション |
| SPLADE | 低〜中 | 中〜高 | スパースインデックス | スパース検索、ハイブリッド検索 |
判断フロー
大規模コーパスから検索したい？
├→ Yes → レイテンシ制約厳しい？
│ ├→ Yes → Bi-Encoder（ANN検索と組み合わせ）
│ └→ No → ColBERT or Bi-Encoder + Cross-Encoder リランキング
└→ No → ペア単位の精密判定？
├→ Yes → Cross-Encoder
└→ No → SPLADE（キーワード＋セマンティック両立）
Web調査プロトコル（概要）
HuggingFace エコシステムは変化が速いため、実装前に必ず最新情報を取得する。
調査すべきリソース
1. sentence-transformers 公式ドキュメント
→ https://www.sbert.net/
2. HuggingFace Hub - モデルカード
→ https://huggingface.co/models?library=sentence-transformers
3. sentence-transformers GitHub リポジトリ
→ https://github.com/UKPLab/sentence-transformers
4. HuggingFace Transformers ドキュメント
→ https://huggingface.co/docs/transformers/
5. PyPI - sentence-transformers
→ バージョン・変更履歴の確認
WebSearch 検索クエリテンプレート
- "sentence-transformers {version} training example {year}"
- "sentence-transformers {loss_function} usage {year}"
- "huggingface {model_type} fine-tuning tutorial {year}"
- "sentence-transformers CrossEncoder training guide {year}"
- "ColBERT v2 training huggingface {year}"
- "SPLADE training sentence-transformers {year}"
調査手順
1. WebSearch で最新のチュートリアル・公式ドキュメントを検索
2. WebFetch で公式ドキュメント・GitHub の具体的コードを取得
3. 取得したコードのバージョン互換性を確認
4. 既存コードベースの依存バージョンと照合
5. 不整合があればフォールバック戦略を実行
詳細: references/web-research-protocol.md
訓練データ準備（概要）
データ形式分類
| 形式 | 構造 | 主な用途 |
|---|
| Pair | (query, positive) | Bi-Encoder基本訓練 |
| Triplet | (anchor, positive, negative) | コントラスティブ学習 |
| Pair + Score | (text1, text2, score) | STS回帰タスク |
| Query + Docs + Labels | (query, doc, relevance) | ランキング学習 |
ネガティブサンプリング
Random Negative → 簡単、だが非効率
Hard Negative → BM25/既存モデルで取得、高品質
In-Batch Negative → バッチ内の他ペアを流用、GPU効率良
DataLoader設計の原則
- Dynamic Padding: バッチ内の最大長に合わせてパディング
- collate_fn でバッチ構築ロジックをカスタム
- num_workers はCPUコア数の半分を目安
- pin_memory=True（GPU使用時）
詳細: references/data-preprocessing.md
訓練の基本構造（概要）
訓練ループスケルトン
for epoch in range(num_epochs):
model.train()
for batch in tqdm(train_dataloader, desc=f"Epoch {epoch+1}"):
optimizer.zero_grad()
loss = compute_loss(model, batch)
loss.backward()
optimizer.step()
scheduler.step()
evaluate(model, val_dataloader)
save_checkpoint(model, epoch)
損失関数選択
| 損失関数 | データ形式 | 用途 |
|---|
| MultipleNegativesRankingLoss | (anchor, positive) | コントラスティブ学習の定番 |
| CosineSimilarityLoss | (text1, text2, score) | 類似度回帰 |
| TripletLoss | (anchor, pos, neg) | トリプレット学習 |
| ContrastiveLoss | (text1, text2, label) | ペア分類 |
| InfoNCE / NTXentLoss | (anchor, positive) | 対照学習 |
| MarginMSELoss | (query, pos, neg, scores) | 知識蒸留 |
損失関数クラスの具体的なimportパスと引数は Web調査で確認すること
詳細: references/training-loop-patterns.md
W&B連携（概要）
基本設定
import wandb
wandb.init(
project="search-model-training",
name=f"{model_name}-{dataset_name}",
config={
"model_name": model_name,
"learning_rate": lr,
"batch_size": batch_size,
"num_epochs": num_epochs,
"loss_function": loss_fn_name,
"max_seq_length": max_seq_length,
},
)
ログ指標一覧
| カテゴリ | 指標 | 頻度 |
|---|
| 訓練 | train/loss, train/lr | ステップ毎 |
| 検証 | val/loss, val/mrr, val/ndcg | エポック毎 |
| システム | gpu/memory, gpu/utilization | 自動 |
| ハイパラ | 全ハイパーパラメータ | 初期化時 |
詳細: references/wandb-integration.md
計算効率の原則
Mixed Precision
- fp16: NVIDIA Volta以降（V100, A100, RTX 30xx+）
- bf16: Ampere以降（A100, RTX 30xx+）、勾配のダイナミックレンジ広い
- 選択: bf16対応GPU → bf16、それ以外 → fp16
Gradient Accumulation
実効バッチサイズ = バッチサイズ × accumulation_steps
→ VRAM不足時にバッチサイズを擬似的に拡大
→ accumulation_steps = 目標バッチサイズ / GPUバッチサイズ
Gradient Checkpointing
- VRAM使用量を大幅削減（計算時間は10-20%増）
- 大規模モデル（>300Mパラメータ）で特に有効
- model.gradient_checkpointing_enable() で有効化
tqdm 使用指針
- エポック進捗: tqdm(range(num_epochs), desc="Training")
- ステップ進捗: tqdm(dataloader, desc=f"Epoch {epoch}")
- postfix で loss/lr をリアルタイム表示
- tqdm.write() でログ出力（進捗バーを崩さない）
GPU VRAM別バッチサイズ目安
| GPU | VRAM | base (128tok) | large (512tok) |
|---|
| RTX 3090 | 24GB | 64-128 | 16-32 |
| A100 40GB | 40GB | 128-256 | 32-64 |
| A100 80GB | 80GB | 256-512 | 64-128 |
| H100 | 80GB | 256-512+ | 64-128+ |
※ fp16/bf16使用時。モデルサイズ・系列長で大きく変動する。詳細（モデルサイズ別・Cross-Encoder別）は references/data-preprocessing.md を参照
評価指標
| 指標 | 説明 | 範囲 | 用途 |
|---|
| MRR@k | 最初の正解文書の逆順位の平均 | [0, 1] | ランキング品質 |
| NDCG@k | 理想順位との比較（段階的関連度対応） | [0, 1] | 多段階関連度評価 |
| Recall@k | 上位kに含まれる正解の割合 | [0, 1] | 網羅性評価 |
| MAP | 各クエリの平均適合率の平均 | [0, 1] | 全体的なランキング品質 |
| Hit@k | 上位kに1つでも正解があるかの割合 | [0, 1] | 検索成功率 |
| P@k | 上位kの適合率 | [0, 1] | 上位精度 |
レビューチェックリスト
リソース安全性（最優先）:
実装品質:
リファレンス
