quaduxit/siglip2-embeddings repository overview

Copyright © 2025-2026 Quadux IT GmbH

License: Quadux files Apache 2.0 (see LICENSE), SigLIP model: Apache 2.0 (Google) Author: Walter Hoffmann

⁠SigLIP Embeddings API

Cross-Modal Text-Image Embeddings that actually work!

⁠Warum dieses Projekt?

Wir haben diese Software geschrieben, um echte Cross-Modal-Suche zwischen Text und Bildern zu ermöglichen. SigLIP ist speziell für Text-zu-Bild-Matching trainiert - im Gegensatz zu vielen anderen Modellen, die zwar Text- und Bild-Embeddings bieten, aber nicht im gleichen Vektorraum arbeiten.

Mit diesem Projekt erhalten Sie:

• 🔍 Text-zu-Bild-Suche - Finden Sie Bilder anhand von Textbeschreibungen
• 🖼️ Bild-zu-Text-Matching - Ordnen Sie Bilder zu passenden Beschreibungen zu
• 🎯 Echtes kontrastives Training - Text und Bild im gleichen Vektorraum
• 🚀 Schnell und ressourcensparend - Nur ~400MB Modellgröße, ~2GB VRAM

⁠Model

google/siglip2-base-patch16-224

• Base model (~400MB)
• 768 dimensions
• 224px image resolution
• Apache 2.0 License
• Echtes kontrastives Training - Text und Bild im gleichen Vektorraum!

Alternative größere Modelle:

• siglip2-so400m-patch14-384 (400M params, 1152 dim, 384px)

⁠Sprachunterstützung

⚠️ Wichtig: SigLIP wurde primär auf englischen Bild-Text-Paaren trainiert (WebLI Dataset).

⁠Optionen für nicht-englische Texte

Empfehlung: Deutsche Suchanfragen vor dem Embedding ins Englische übersetzen (z.B. via DeepL API oder lokales Übersetzungsmodell wie Helsinki-NLP/opus-mt-de-en).

Der Vision-Encoder ist sprachneutral - Bilder selbst brauchen keine Anpassung. Nur der Text-Encoder bevorzugt Englisch.

⁠Text-Stil und Matching-Qualität

📊 Wichtige Erkenntnis aus Tests mit klassischer Literatur:

⁠Warum?

SigLIP wurde auf Bild-Beschreibungen trainiert (Alt-Text, Captions), nicht auf metaphorische Literatur:

• ✅ Funktioniert gut: "colorful spring flowers blooming in the sun"
• ❌ Funktioniert schlecht: "I wandered lonely as a cloud" (Wordsworth)
• ❌ Funktioniert schlecht: "Tyger Tyger, burning bright, In the forests of the night" (Blake)

⁠Empfehlung für Produktiveinsatz

✅ DO:  Kurze, beschreibende englische Queries verwenden
✅ DO:  Konkrete Objekte und Szenen beschreiben
❌ DON'T: Metaphorische oder abstrakte Sprache verwenden
❌ DON'T: Lange literarische Texte als Suchquery nutzen

Die klassischen Texte im Test (test/texts/classic_texts.js) dienen als Benchmark für die Grenzen des Modells, nicht als Beispiel für produktive Nutzung.

⁠API Endpoints

⁠Quick Start

⁠Mit Start-Scripts (empfohlen)

.\start.bat          # Windows
./start.sh           # Linux/macOS

⁠Manuell mit Docker

# Lokales Build
docker build -t quaduxit/siglip-embeddings .

# Oder von Docker Hub:
docker pull quaduxit/siglip-embeddings:latest

# Container starten
docker run -d --name siglip-embed \
  --gpus all \
  -p 8091:8000 \
  quaduxit/siglip-embeddings

# Health Check
curl http://localhost:8091/health

⁠Usage Examples

⁠Text Embedding

curl -X POST http://localhost:8091/embed/text \
  -H "Content-Type: application/json" \
  -d '{"texts": ["a photo of a cat", "a photo of a dog"]}'

⁠Image Embedding

curl -X POST http://localhost:8091/embed/image \
  -F "[email protected]"

⁠Cross-Modal Similarity (THE MAIN USE CASE!)

curl -X POST http://localhost:8091/similarity \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "texts=[\"a photo of a cat\", \"a photo of a dog\"]"

Response:

{
  "similarities": [
    [0.85, 0.12], // "cat" query: 85% cat.jpg, 12% dog.jpg
    [0.15, 0.82] // "dog" query: 15% cat.jpg, 82% dog.jpg
  ]
}

⁠Rank Images by Query

curl -X POST http://localhost:8091/rank \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "query=a sunset over mountains"

⁠Vergleich mit Jina v4

⁠Empfehlung

• Text-Suche (RAG, Dokumente): Jina v4 (Port 8090)
• Bild-Suche (Text→Image): SigLIP (Port 8091)

⁠Umgebungsvariablen

⁠Tests

cd test
node test.js

Testet:

• ✅ Health endpoint
• ✅ Text embeddings
• ✅ Image embeddings
• ✅ Cross-modal similarity
• ✅ Image ranking

⁠Verzeichnisstruktur

siglip-embeddings-docker/
├── build/
│   ├── Dockerfile          # Container-Definition
│   ├── app.py              # FastAPI Server
│   ├── download_model.py   # Model Download Script
│   └── requirements.txt    # Python-Abhängigkeiten
├── test/
│   ├── photos/             # Testbilder (Unsplash)
│   ├── texts/              # Testtexte (Public Domain)
│   └── test.js             # Test-Suite
├── LICENSE                 # Apache 2.0-Lizenz (Quadux-Dateien)
├── NOTICE                  # Third-Party-Hinweise (Google SigLIP)
├── CHANGELOG.md            # Änderungsprotokoll
├── NOTICE                  # Third-Party-Hinweise (Google SigLIP)
├── start.bat               # Windows Start-Script
├── start.sh                # Linux/macOS Start-Script
└── README.md               # Diese Dokumentation

⁠Technische Details

• Base Image: pytorch/pytorch:2.9.1-cuda13.0-cudnn9-runtime
• GPU: CUDA 13.0 Support (RTX 5090 Blackwell sm_120)
• Model: google/siglip2-base-patch16-224
• Embedding Dimension: 768
• Max. Image Resolution: 224x224
• Framework: FastAPI + Uvicorn

⁠Lizenz

Dieser Docker-Container und die Quadux-spezifischen Container-Steuerungen stehen unter der Apache License 2.0 (siehe LICENSE⁠).

⁠SigLIP Model

Das Modell google/siglip2-base-patch16-224 ist ebenfalls unter der Apache License 2.0 von Google LLC lizenziert:

• ✅ Kommerzielle Nutzung erlaubt ohne Einschränkungen
• ✅ Patent-Grant enthalten
• ✅ Keine Trademark-Rechte

Weitere Details:

• NOTICE⁠ – Third-Party-Hinweise für Google SigLIP
• Apache License 2.0⁠ – Volltext der Lizenz

⁠Test Assets

Die Testbilder stammen von Unsplash und unterliegen der Unsplash License⁠ (kostenlose kommerzielle Nutzung, keine Attribution erforderlich, aber Credits in test/photos/SOURCES.md⁠ angegeben).

Die Testtexte sind gemeinfreie klassische Literatur (Public Domain) mit Quellenangaben in test/texts/SOURCES.md⁠.

⁠Support & Haftungsausschluss

⁠Impressum

Impressum Quadux IT GmbH⁠