CLIP ViT-B/32

Inicio rápido

1. Instalar Docker

Ejecute los siguientes comandos en la placa de desarrollo para instalar Docker:

# 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. Ejecutar el proyecto (un comando, vista previa de dos modos)

Este proyecto permite clasificar imágenes sin entrenamiento específico (zero-shot) y recuperar imágenes mediante lenguaje natural desde un navegador web. Tanto el codificador de imágenes como el de texto se ejecutan como modelos RKNN.

Paso A: descargar las imágenes

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

Paso B: ejecutar con un solo comando

Para 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

Acceda mediante: http://<Board_IP>:8000

Para 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

Acceda mediante: http://<Board_IP>:8000

3. Inferencia por línea de comandos

Clasificar una imagen con descripciones candidatas:

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

Ordenar varias imágenes mediante una consulta en lenguaje natural:

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

Use --platform rk3588 al ejecutar el directorio fuente de RK3588.

🔌 Documentación de la API

El servicio proporciona interfaces REST independientes para clasificación zero-shot y recuperación de imágenes a partir de texto. La documentación interactiva de OpenAPI está disponible en http://<Board_IP>:8000/docs.

1. Clasificación de imágenes zero-shot

Punto de acceso: POST /api/models/clip/predict

Parámetros de la solicitud (Multipart/Form-Data):

• file: Archivo de imagen obligatorio. Las imágenes se preprocesan a 224 x 224.
• prompts: Etiquetas candidatas obligatorias, como matriz JSON, texto separado por saltos de línea o texto separado por |. Se aceptan como máximo 32 etiquetas.
• topk: Número opcional de etiquetas devueltas, de 1 a 32. El valor predeterminado es 5.

Ejemplo de uso:

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'

Formato de respuesta (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. Recuperación de imágenes mediante lenguaje natural

Punto de acceso: POST /api/models/clip/retrieve

Parámetros de la solicitud (Multipart/Form-Data):

• files: Campo repetido obligatorio que contiene entre 1 y 32 imágenes.
• text: Consulta obligatoria en lenguaje natural.
• topk: Número opcional de coincidencias devueltas, de 1 a 32.

Ejemplo de uso:

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'

El codificador de texto convertido tiene una entrada fija de 20 tokens, por lo que las descripciones y consultas deben ser concisas. La similitud se calcula con características de imagen y texto normalizadas.

3. Interfaz de configuración del sistema

Obtener la configuración actual

• Punto de acceso: GET /api/config
• Respuesta: {"topk": 5}

Actualizar la configuración

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

Use GET /api/health para consultar la plataforma activa, los archivos RKNN cargados y las capacidades del entorno de ejecución.

🛠️ Guía para desarrolladores (recomendaciones de producción)

Descripción del código

• web_service.py:
  • API web: Proporciona la interfaz del navegador, la API de predicción, la API de recuperación, la API de configuración y el estado de salud.
  • Validación de solicitudes: Limita las cargas a 64 MB y la recuperación a 32 imágenes.
• task_runtime.py:
  • Procesamiento de imágenes: Redimensiona la entrada a 224 x 224 y normaliza las características de imagen.
  • Procesamiento de texto: Tokeniza las descripciones con clip_vocab.h y aplica la entrada fija de 20 tokens del modelo convertido.
  • Ordenación: Calcula la similitud coseno normalizada para clasificación y recuperación.
• inference.py: Proporciona clasificación y recuperación de una sola ejecución por línea de comandos.

Archivos del modelo

Modificar los modelos

1. Coloque archivos .rknn compatibles de los codificadores de imagen y texto en el directorio model/ y conserve los nombres indicados arriba.
2. Mantenga los dos codificadores y el vocabulario del mismo paquete de conversión.
3. Antes del despliegue, confirme que el reemplazo conserva la entrada de imagen 224 x 224 y el contrato de entrada de texto fija de 20 tokens.

Actualmente, el proyecto original proporciona un paquete de modelos por plataforma. Los dos codificadores son componentes de una canalización, no tamaños de cuantización alternativos; esta versión no tiene un parámetro de variante de modelo.

Crear imágenes locales

Ejecute desde la raíz de reComputer-RK-CV:

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