clip-aware-embeddings

CLIP対応画像埋め込み

CLIPが有効な場合と、代替手段を使うべき場合を判断する、スマートな画像とテキストのマッチングです。

MCP連携

MCP	目的
Firecrawl	最新のCLIP代替モデルとベンチマークを調査します
Hugging Face（設定されている場合）	モデルカードとドキュメントにアクセスします

クイック判断ツリー

Your task:
├─ Semantic search ("find beach images") → CLIP ✓
├─ Zero-shot classification (broad categories) → CLIP ✓
├─ Counting objects → DETR, Faster R-CNN ✗
├─ Fine-grained ID (celebrities, car models) → Specialized model ✗
├─ Spatial relations ("cat left of dog") → GQA, SWIG ✗
└─ Compositional ("red car AND blue truck") → DCSMs, PC-CLIP ✗

このスキルを使う場面

✅ 次の用途に使います：

• セマンティック画像検索
• 大まかなカテゴリ分類
• 画像の類似度マッチング
• 新しいカテゴリでのゼロショットタスク

❌ 次の用途には使わないでください：

• 画像内の物体の数え上げ
• きめ細かな分類
• 空間理解
• 属性の結び付け
• 否定の処理

インストール

pip install transformers pillow torch sentence-transformers --break-system-packages

検証：python scripts/validate_setup.pyを実行します。

基本的な使い方

画像検索

from transformers import CLIPProcessor, CLIPModel
from PIL import Image

model = CLIPModel.from_pretrained("openai/clip-vit-large-patch14")
processor = CLIPProcessor.from_pretrained("openai/clip-vit-large-patch14")

# Embed images
images = [Image.open(f"img{i}.jpg") for i in range(10)]
inputs = processor(images=images, return_tensors="pt")
image_features = model.get_image_features(**inputs)

# Search with text
text_inputs = processor(text=["a beach at sunset"], return_tensors="pt")
text_features = model.get_text_features(**text_inputs)

# Compute similarity
similarity = (image_features @ text_features.T).softmax(dim=0)

よくあるアンチパターン

アンチパターン1：「何でもCLIPで対応」

❌ 誤り：

# Using CLIP to count cars in an image
prompt = "How many cars are in this image?"
# CLIP cannot count - it will give nonsense results

誤りである理由：CLIPのアーキテクチャは、空間情報を単一のベクトルに集約します。文字どおり、数を数えることはできません。

✓ 正しい方法：

from transformers import DetrImageProcessor, DetrForObjectDetection

processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")

# Detect objects
results = model(**processor(images=image, return_tensors="pt"))
# Filter for cars and count
car_detections = [d for d in results if d['label'] == 'car']
count = len(car_detections)

検出方法：クエリに「いくつ」「数える」や数量に関する質問が含まれている場合は、物体検出を使います。

---

アンチパターン2：きめ細かな分類

❌ 誤り：

# Trying to identify specific celebrities with CLIP
prompts = ["Tom Hanks", "Brad Pitt", "Morgan Freeman"]
# CLIP will perform poorly - not trained for fine-grained face ID

誤りである理由：CLIPは大まかなカテゴリで学習されています。顔の細かな分類、車種、花の種の識別には、専用モデルが必要です。

✓ 正しい方法：

# Use a fine-tuned face recognition model
from transformers import AutoFeatureExtractor, AutoModelForImageClassification

model = AutoModelForImageClassification.from_pretrained(
    "microsoft/resnet-50"  # Then fine-tune on celebrity dataset
)
# Or use dedicated face recognition: ArcFace, CosFace

検出方法：同じカテゴリに属する類似した対象を区別するようクエリで求められている場合は、専用モデルを使います。

---

アンチパターン3：空間理解

❌ 誤り：

# CLIP cannot understand spatial relationships
prompts = [
    "cat to the left of dog",
    "cat to the right of dog"
]
# Will give nearly identical scores

誤りである理由：CLIPの埋め込みでは、空間的なトポロジーが失われます。「左」と「右」は単語の集合として扱われます。

✓ 正しい方法：

# Use a spatial reasoning model
# Examples: GQA models, Visual Genome models, SWIG
from swig_model import SpatialRelationModel

model = SpatialRelationModel()
result = model.predict_relation(image, "cat", "dog")
# Returns: "left", "right", "above", "below", etc.

検出方法：クエリに方向を表す語（左、右、上、下、隣など）が含まれている場合は、空間モデルを使います。

---

アンチパターン4：属性の結び付け

❌ 誤り：

prompts = [
    "red car and blue truck",
    "blue car and red truck"
]
# CLIP often gives similar scores for both

誤りである理由：CLIPは属性を物体に結び付けられません。「赤、青、車、トラック」を概念の集合として認識します。

✓ 正しい方法 — PC-CLIPまたはDCSMsを使う：

# PC-CLIP: Fine-tuned for pairwise comparisons
from pc_clip import PCCLIPModel

model = PCCLIPModel.from_pretrained("pc-clip-vit-l")
# Or use DCSMs (Dense Cosine Similarity Maps)

検出方法：異なる属性を持つ複数の物体がクエリに含まれている場合は、構成的モデルを使います。

---

発展のタイムライン

2021年：CLIPのリリース

• 革新的なゼロショット対応、4億組の画像とテキストのペアで学習
• あらゆる用途に広く採用
• 制約はまだ理解されていませんでした

2022〜2023年：制約の発見

• 物体の数を数えられない
• きめ細かな分類が苦手
• 空間推論に失敗する
• 属性を結び付けられない

2024年：代替モデルの登場

• DCSMs：パッチ／トークンのトポロジーを保持
• PC-CLIP：ペア単位の比較で学習
• SpLiCE：疎で解釈可能な埋め込み

2025年：現在のベストプラクティス

• CLIPが得意な用途にはCLIPを使う
• 制約のあるタスクにはタスク専用モデルを使う
• 複雑なクエリには構成的モデルを使う

LLMの誤り：2021〜2023年のデータで学習したLLMは、制約が広く知られていなかったため、何でもCLIPを使うよう提案します。このスキルはそれを修正します。

---

検証スクリプト

CLIPを使う前に、適切かどうかを確認します。

python scripts/validate_clip_usage.py \
    --query "your query here" \
    --check-all

次の結果が返されます：

• ✅ CLIPが適切です
• ❌ 代替手段を使います（提案を提示）

タスク別のガイダンス

画像検索（CLIP ✓）

# Good use of CLIP
queries = ["beach", "mountain", "city skyline"]
# Works well for broad semantic concepts

ゼロショット分類（CLIP ✓）

# Good: Broad categories
categories = ["indoor", "outdoor", "nature", "urban"]
# CLIP excels at this

物体の数え上げ（CLIP ✗）

# Use object detection instead
from transformers import DetrImageProcessor, DetrForObjectDetection
# See /references/object_detection.md

きめ細かな分類（CLIP ✗）

# Use specialized models
# See /references/fine_grained_models.md

空間推論（CLIP ✗）

# Use spatial relation models
# See /references/spatial_models.md

---

トラブルシューティング

問題：CLIPが予想外の結果を返す

確認事項：

1. 数え上げタスクですか？ → 物体検出を使います
2. きめ細かな分類ですか？ → 専用モデルを使います
3. 空間に関するクエリですか？ → 空間モデルを使います
4. 属性を持つ物体が複数ありますか？ → 構成的モデルを使います

検証：

python scripts/diagnose_clip_issue.py --image path/to/image --query "your query"

問題：類似度スコアが低い

考えられる原因：

1. クエリが具体的すぎる（CLIPは大まかな概念のほうが適しています）
2. きめ細かなタスクである（CLIPの得意分野ではありません）
3. しきい値の調整が必要

解決策：より大まかなクエリを試すか、代替モデルを使います

---

モデル選択ガイド

モデル	最適な用途	避けるべき用途
CLIP ViT-L/14	セマンティック検索、幅広いカテゴリ	数のカウント、細粒度の識別、空間認識
DETR	オブジェクト検出、数のカウント	セマンティック類似性
DINOv2	細粒度の特徴抽出	テキストと画像のマッチング
PC-CLIP	属性の対応付け、比較	汎用埋め込み
DCSMs	合成的推論	単純な類似性

パフォーマンスに関する注意

CLIP モデル：

• ViT-B/32：高速ですが、品質は低めです
• ViT-L/14：バランスが取れています（推奨）
• ViT-g-14：最高品質ですが、処理は遅めです

推論時間（単一画像、CPU）：

• ViT-B/32：約100ms
• ViT-L/14：約300ms
• ViT-g-14：約1000ms

さらに詳しく

• /references/clip_limitations.md - CLIP の失敗に関する詳細な分析
• /references/alternatives.md - モデルの使い分け
• /references/compositional_reasoning.md - DCSMs と PC-CLIP の詳細解説
• /scripts/validate_clip_usage.py - 事前検証ツール
• /scripts/diagnose_clip_issue.py - 予期しない結果のデバッグ

---

バージョン履歴については CHANGELOG.md をご覧ください。