qwen-groundingdino-visual-mcp

LM Studio + Qwen VL + GroundingDINO — üretim kalitesinde açık-kelime dağarcıklı nesne tespiti ve zekice yerleştirme öneri motoru, MCP protokolü üzerinden.

---

Mimari Özet

  ┌──────────────────────┐    stdio    ┌──────────────────────────────────────┐
  │  LM Studio           │◄───────────►│  annotator_mcp.py                    │
  │  Qwen VL (orkestratör)│            │  GroundingDINO (tespit motoru)        │
  │  function-calling UI │            │  Kural motoru (yerleştirme)           │
  └──────────────────────┘            │  Oturum belleği (session_memory.json) │
                                       └──────────────────────────────────────┘

Bileşen	Teknoloji	Notlar
Orkestratör LLM	Qwen VL (LM Studio'da)	Multimodal; ne zaman hangi tool'u çağıracağına kendisi karar verir
Tespit motoru	IDEA-Research/grounding-dino-base	transformers üzerinden, trust_remote_code=False
Transport	stdio	HTTP/ağ bağlantısı yoktur
Model format	safetensors	GGUF/llama.cpp ile hiçbir ilgisi yoktur

---

Kurulum

1. Python sanal ortamı oluştur

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/macOS
source .venv/bin/activate

2. Bağımlılıkları yükle

CPU-only (varsayılan):

pip install -r requirements.txt

CUDA 12.1 (GPU hızlandırma):

pip install torch==2.4.1+cu121 torchvision==0.19.1+cu121 \
    --index-url https://download.pytorch.org/whl/cu121

# Geri kalanı (torch'u tekrar yüklememek için --no-deps kullanma, sadece requirements'i yükle)
pip install transformers==4.44.2 accelerate==0.34.2 huggingface_hub==0.25.1 \
    Pillow==10.4.0 numpy==1.26.4 mcp==1.3.0 tokenizers==0.19.1

CUDA 11.8:

pip install torch==2.4.1+cu118 torchvision==0.19.1+cu118 \
    --index-url https://download.pytorch.org/whl/cu118
# ardından yukarıdaki diğer paketleri yükle

3. Sözdizimi doğrulaması

python -m py_compile annotator_mcp.py && echo "OK — sözdizimi hatası yok"

4. Model ön-indirme (isteğe bağlı)

İlk tool çağrısında model otomatik indirilir. İnternetsiz ortamlar için önden indirebilirsiniz:

python -c "
from transformers import AutoProcessor, AutoModelForZeroShotObjectDetection
AutoProcessor.from_pretrained('IDEA-Research/grounding-dino-base')
AutoModelForZeroShotObjectDetection.from_pretrained('IDEA-Research/grounding-dino-base')
print('Model önbelleğe alındı.')
"

---

LM Studio Yapılandırması — mcp.json

LM Studio'nun MCP ayarlar dosyasına aşağıdaki bloğu ekleyin:

{
  "mcpServers": {
    "groundingdino-annotator": {
      "command": "python",
      "args": [
        "C:/Users/ASUS/Projects/qwen-groundingdino-visual-mcp/annotator_mcp.py"
      ],
      "env": {
        "GROUNDING_DINO_MODEL_ID": "IDEA-Research/grounding-dino-base",
        "BOX_THRESHOLD": "0.35",
        "TEXT_THRESHOLD": "0.25"
      }
    }
  }
}

Not: command için sanal ortamdaki Python yolunu kullanmak daha güvenlidir: "C:/Users/ASUS/Projects/qwen-groundingdino-visual-mcp/.venv/Scripts/python.exe"

Hafif model (daha az bellek):

"GROUNDING_DINO_MODEL_ID": "IDEA-Research/grounding-dino-tiny"

---

Örnek Sohbet Akışı

Senaryo: "Masadaki vazoyu bul, ardından yanına bir kupa öner"

Kullanıcı:
  C:/sahne/mutfak.jpg görüntüsündeki masayı ve vazoyu bul.

Qwen → detect_objects({
  "image_path": "C:/sahne/mutfak.jpg",
  "query": "masa, vazo",
  "session_id": "mutfak_sahnesi"
})

Sunucu yanıtı:
{
  "session_id": "mutfak_sahnesi",
  "count": 2,
  "detections": [
    { "label": "masa",  "score": 0.82, "bbox": [120, 450, 880, 950] },
    { "label": "vazo",  "score": 0.74, "bbox": [400, 200, 600, 450] }
  ]
}

---

Kullanıcı:
  Vazonun sağına ideal kupa yerleştirme noktasını öner.

Qwen → suggest_ideal_placements({
  "session_id": "mutfak_sahnesi",
  "target_object": "kupa",
  "reference_object": "vazo",
  "relation": "right_of"
})

Sunucu yanıtı:
{
  "suggested_bbox": [610, 250, 760, 440],
  "score": 0.8712,
  "rule_breakdown": {
    "overlap_penalty": 1.0,
    "edge_margin": 0.82,
    "spacing_from_objects": 0.61,
    "prefer_center": 0.73
  }
}

---

Kullanıcı:
  Bu koordinatları görüntüye çiz ve kaydet.

Qwen → annotate_image({
  "image_path": "C:/sahne/mutfak.jpg",
  "output_path": "C:/sahne/mutfak_annotated.jpg",
  "session_id": "mutfak_sahnesi",
  "annotations": [
    { "label": "masa",  "bbox": [120, 450, 880, 950] },
    { "label": "vazo",  "bbox": [400, 200, 600, 450] },
    { "label": "kupa",  "bbox": [610, 250, 760, 440] }
  ]
})

Sonuç: 3 nesne kırmızı çerçeve + etiketle işaretlenmiş görüntü kaydedildi.

---

Koordinat Sistemi

Tüm bbox koordinatları 0-1000 normalize skalasında [x1, y1, x2, y2] formatındadır:

(0,0) ─────────────── (1000,0)
  │                        │
  │     görüntü alanı      │
  │                        │
(0,1000) ───────────(1000,1000)

Bu skala Qwen VL'nin koordinat çıktısıyla tutarlıdır.

---

Tool Referansı

Tool	Amaç	Zorunlu Parametreler
detect_objects	GroundingDINO tespiti	image_path, query
register_detected_objects	Manuel nesne kaydı	session_id, objects
annotate_image	Görüntü üzerine çizim	image_path, output_path, annotations
suggest_ideal_placements	Yerleştirme önerisi	session_id, target_object
list_session_objects	Oturum durumu	session_id
reset_session	Bellek temizleme	session_id

---

Doğrulama Testi

Aşağıdaki Python betiği, MCP olmadan doğrudan sunucunun tespit fonksiyonunu test eder:

# test_detect.py
import sys
sys.path.insert(0, ".")

from annotator_mcp import format_groundingdino_query, _run_detection_sync

# 1. Sorgu formatlama testi
q = format_groundingdino_query("Masa, VAZO, Kapı")
assert q == "masa . vazo . kapı .", f"Beklenen 'masa . vazo . kapı .' ama '{q}' geldi"
print(f"✓ format_groundingdino_query: '{q}'")

# 2. Gerçek tespit testi (bir görüntü gerektirir)
TEST_IMAGE = "test.jpg"   # Var olan bir .jpg yolu girin

import os
if os.path.isfile(TEST_IMAGE):
    results = _run_detection_sync(
        image_path=TEST_IMAGE,
        query="insan, masa, sandalye",
        box_threshold=0.35,
        text_threshold=0.25,
        session_id="test_session",
    )
    print(f"✓ Tespit tamamlandı: {len(results)} nesne bulundu")
    for r in results:
        print(f"   [{r['label']:15s}] skor={r['score']:.3f}  bbox={r['bbox']}")
else:
    print(f"⚠ {TEST_IMAGE} bulunamadı — tespit adımı atlandı")

print("\n✓ Tüm birim testler geçti.")

Çalıştırma:

python test_detect.py

Beklenen çıktı formatı:

{
  "session_id": "test_session",
  "count": 2,
  "detections": [
    { "label": "masa",    "score": 0.7812, "bbox": [45, 380, 955, 920] },
    { "label": "sandalye","score": 0.6531, "bbox": [20, 420, 300, 890] }
  ]
}

---

⚠️ Bilinen Tuzaklar

Bu bölüm, proje geliştirme sırasında gerçekten yaşanan sorunları belgeler. Gelecekteki geliştiriciler ve AI sistemleri için rehber niteliğindedir.

1. GGUF vs safetensors karışıklığı

Sorun: GroundingDINO'yu LM Studio'nun GGUF/llama.cpp arayüzüyle yüklemeye çalışmak.

Belirti: gguf_init_from_reader: tensor name too long veya benzeri anlamsız hatalar.

Neden: GroundingDINO (ve genel olarak tüm trust_remote_code/özel mimari modeller) llama.cpp ekosistemiyle uyumlu değildir. Bu model safetensors formatındadır ve GGUF'a dönüştürülemez.

Çözüm: Model yalnızca bu Python süreci içinde transformers.from_pretrained() ile, orijinal safetensors formatında yönetilmelidir. LM Studio'nun model arayüzüne hiç dokunmayın.

---

2. transformers sürüm uyumsuzluğu

Sorun: requirements.txt'te transformers sürümü pinlenmemişse en güncel sürüm kurulabilir ve API kırılabilir.

Belirti: TypeError: post_process_grounded_object_detection() got unexpected keyword argument 'input_ids' veya tam tersi.

Neden: post_process_grounded_object_detection'ın fonksiyon imzası transformers sürümleri arasında değişmiştir.

Çözüm (bu projede uygulanmıştır): requirements.txt'te transformers==4.44.2 olarak pinlendi. Ek olarak kod, yeni imzayı dener; TypeError alırsa eski imzaya otomatik düşer (try/except cascade). Yine de sürümü değiştirmeden önce mutlaka test edin.

---

3. Event loop bloklanması

Sorun: _run_detection_sync() veya _find_best_placement_sync() async call_tool handler'ından asyncio.to_thread olmadan doğrudan çağrılırsa.

Belirti: Inference süresince (1-5 saniye) MCP sunucusu tüm diğer isteklere (ping, iptal) kilitlenir.

Çözüm (bu projede uygulanmıştır): Tüm CPU/GPU-bound fonksiyonlar await asyncio.to_thread(...) ile sarılmıştır. Hiçbir zaman bu sarımı kaldırmayın.

---

4. Hayali dosya yolu (Hallucinated image_path)

Sorun: LLM, sohbete sürükle-bırak yapılan bir görseli "gördüğü" için (base64 olarak) bazen bu görselin disk yolunu uydurabilir.

Belirti: FileNotFoundError: 'C:/imagined/path.jpg'

Neden: Model görseli base64 olarak görüyor; gerçek disk yolunu bilmiyor.

Çözüm:

• Tool description'larında açıkça belirtilmiştir: image_path gerçek bir disk yolu olmalıdır.
• Kod, Image.open() başarısız olursa net hata döndürür: "Dosya bulunamadı: ... Lütfen diskte gerçekten var olan bir dosya yolu belirtin."
• Kullanıcıların her zaman gerçek dosya yolunu metin olarak yazması gerekir.

---

5. MCP handshake timeout

Sorun: Model import anında veya annotator_mcp.py başlangıcında yüklenirse.

Belirti: LM Studio, MCP sunucusunu başlatır ama ~3 saniye içinde handshake yanıtı alamaz ve bağlantıyı düşürür. Log: MCP server connection timed out veya benzeri.

Neden: Model yükleme (1-2 GB safetensors, birkaç saniye) handshake penceresini aşıyor.

Çözüm (bu projede uygulanmıştır): Lazy loading zorunludur. _model = None ile başlar; load_model() yalnızca ilk tool çağrısında tetiklenir. torch ve transformers import'ları da load_model() içinde yapılır (yavaş import'ları geciktirmek için).

---

6. Florence-2 ile karıştırma

Sorun: Florence-2 gibi trust_remote_code=True gerektiren modellerin kurulum mantığını GroundingDINO'ya uygulamak.

Fark: GroundingDINO, transformers 4.38+ sürümünde resmi olarak entegre edilmiştir ve trust_remote_code gerektirmez. Bu, Florence-2'ye göre önemli bir kararlılık avantajıdır — remote code her güncellemede kırılabilir, resmi entegre kod kırılmaz.

Çözüm: from_pretrained() çağrılarında trust_remote_code parametresi hiç kullanmayın.

---

Proje Yapısı

qwen-groundingdino-visual-mcp/
├── annotator_mcp.py       # Ana MCP sunucusu (tek dosya, tüm mantık burada)
├── requirements.txt       # Sabit sürümlü bağımlılıklar
├── README.md              # Bu dosya
└── session_memory.json    # Çalışma zamanında oluşturulur (otomatik)

---

Lisans

MIT — Dilediğiniz gibi kullanın, değiştirin ve dağıtın.