CLIP ViT-B/32

Schnellstart

1. Docker installieren

Führen Sie zur Installation von Docker folgende Befehle auf dem Entwicklungsboard aus:

# Download installation script
curl -fsSL https://get.docker.com -o get-docker.sh
# Install using Aliyun mirror source
sudo sh get-docker.sh --mirror Aliyun
# Start Docker and enable auto-start on boot
sudo systemctl enable docker
sudo systemctl start docker

2. Projekt ausführen (ein Befehl, Dual-Modus-Vorschau)

Dieses Projekt unterstützt Zero-Shot-Bildklassifizierung und natürlichsprachliche Bildsuche über einen Webbrowser. Sowohl der Bild- als auch der Text-Encoder laufen als RKNN-Modelle.

Schritt A: Images abrufen

sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3588-clip:latest
sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3576-clip:latest

Schritt B: mit einem Befehl starten

Für RK3588:

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-clip:latest

Aufruf: http://<Board_IP>:8000

Für RK3576:

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-clip:latest

Aufruf: http://<Board_IP>:8000

3. Inferenz über die Befehlszeile

Klassifizieren Sie ein Bild mit Kandidaten-Prompts:

python inference.py --platform rk3576 --model_dir model \
    --file samples/dog_224x224.jpg \
    --prompts 'a photo of a dog|a photo of a cat'

Sortieren Sie mehrere Bilder anhand einer natürlichsprachlichen Abfrage:

python inference.py --platform rk3576 --model_dir model \
    --files image1.jpg image2.jpg --query 'a red car' --topk 2

Verwenden Sie --platform rk3588, wenn Sie im RK3588-Quellverzeichnis arbeiten.

🔌 API-Dokumentation

Der Dienst bietet getrennte REST-Schnittstellen für Zero-Shot-Klassifikation und Text-zu-Bild-Suche. Die interaktive OpenAPI-Dokumentation ist unter http://<Board_IP>:8000/docs verfügbar.

1. Zero-Shot-Bildklassifikation

Endpunkt: POST /api/models/clip/predict

Anfrageparameter (Multipart/Form-Data):

• file: Erforderliche Bilddatei. Bilder werden auf 224 x 224 vorverarbeitet.
• prompts: Erforderliche Kandidatenlabels als JSON-Array, durch Zeilenumbrüche oder | getrennter Text. Höchstens 32 Labels werden akzeptiert.
• topk: Optionale Anzahl zurückgegebener Labels von 1 bis 32. Der Standardwert ist 5.

Anwendungsbeispiel:

curl -X POST "http://127.0.0.1:8000/api/models/clip/predict" \
    -F 'file=@samples/dog_224x224.jpg' \
    -F $'prompts=a photo of a dog\na photo of a cat' \
    -F 'topk=2'

Antwortformat (JSON):

{
  "success": true,
  "model": "clip",
  "platform": "rk3576",
  "inference_time_ms": 58.2,
  "result": {
    "mode": "classification",
    "image": {"width": 224, "height": 224},
    "candidate_count": 2,
    "predictions": [
      {"text": "a photo of a dog", "score": 0.97}
    ]
  }
}

2. Natürlichsprachliche Bildsuche

Endpunkt: POST /api/models/clip/retrieve

Anfrageparameter (Multipart/Form-Data):

• files: Erforderliches wiederholtes Feld mit 1–32 Bildern.
• text: Erforderliche natürlichsprachliche Abfrage.
• topk: Optionale Anzahl zurückgegebener Treffer von 1 bis 32.

Anwendungsbeispiel:

curl -X POST "http://127.0.0.1:8000/api/models/clip/retrieve" \
    -F 'files=@image1.jpg' \
    -F 'files=@image2.jpg' \
    -F 'text=a red car' \
    -F 'topk=2'

Der konvertierte Text-Encoder hat eine feste Eingabe von 20 Tokens; Prompts und Abfragen sollten deshalb kurz bleiben. Die Ähnlichkeit wird aus normalisierten Bild- und Textmerkmalen berechnet.

3. Schnittstelle zur Systemkonfiguration

Aktuelle Konfiguration abrufen

• Endpunkt: GET /api/config
• Antwort: {"topk": 5}

Konfiguration aktualisieren

curl -X POST "http://127.0.0.1:8000/api/config" \
    -H 'Content-Type: application/json' \
    -d '{"topk": 3}'

Prüfen Sie mit GET /api/health die aktive Plattform, die geladenen RKNN-Dateien und die Laufzeitfunktionen.

🛠️ Entwicklerhandbuch (Empfehlungen für den Produktionseinsatz)

Codebeschreibung

• web_service.py:
  • Web-API: Stellt die Browseroberfläche, die Vorhersage-API, die Such-API, die Konfigurations-API und den Systemstatus bereit.
  • Anfragevalidierung: Begrenzt Uploads auf 64 MB und die Suche auf 32 Bilder.
• task_runtime.py:
  • Bildverarbeitung: Skaliert die Eingabe auf 224 x 224 und normalisiert die Bildmerkmale.
  • Textverarbeitung: Tokenisiert Prompts mit clip_vocab.h und wendet die feste 20-Token-Eingabe des konvertierten Modells an.
  • Ranking: Berechnet die normalisierte Kosinus-Ähnlichkeit für Klassifikation und Suche.
• inference.py: Bietet einmalige Klassifikation und Suche über die Befehlszeile.

Modelldateien

Modelle ändern

1. Legen Sie kompatible .rknn-Dateien für Bild- und Text-Encoder im Verzeichnis model/ ab und behalten Sie die obigen Dateinamen bei.
2. Verwenden Sie die beiden Encoder und das Vokabular aus demselben Konvertierungspaket.
3. Stellen Sie vor der Bereitstellung sicher, dass der Ersatz die Bildeingabe von 224 x 224 und den festen 20-Token-Textvertrag einhält.

Das Upstream-Projekt liefert derzeit ein Modellpaket pro Plattform. Die beiden Encoder sind Pipeline-Komponenten und keine alternativen Quantisierungsgrößen; diese Version hat keinen Modellvarianten-Parameter.

Lokale Images erstellen

Im Stammverzeichnis von reComputer-RK-CV ausführen:

docker build -f docker/rk3576/clip.dockerfile \
    -t rk3576-clip:local src/rk3576_clip

docker build -f docker/rk3588/clip.dockerfile \
    -t rk3588-clip:local src/rk3588_clip