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：保留 patch/token 拓扑结构
• PC-CLIP：使用成对比较进行训练
• SpLiCE：稀疏、可解释的嵌入

2025：当前最佳实践

• 将 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。