DINOv3 Embeddings API

Batch-first FastAPI service for generating image embeddings with DINOv3. Supports image URLs or base64 payloads, CPU/GPU execution, and Docker/Kubernetes deployment.

Features

• Batch-first embeddings: Always send images: [...], even for single-image requests
• GPU-ready: CUDA 13 base image and DEVICE=cuda toggle
• Secure URL fetch: SSRF protections with denylist/allowlist support
• Ops-friendly: Docker + K8s manifests and health checks

Setup and Installation

Prerequisites

• Docker and Docker Compose
• NVIDIA GPU with CUDA support (optional, but recommended for faster performance)

Quick Start

1. Clone the repository:

   git clone <repo-url>
   cd tool-dinov3-embeddings-api

2. Build and run with Docker:

   docker compose up --build

3. Access the application:

   • API: http://localhost:8000/v1/health

User Guide

Using the Tool

1. Check health:

   curl http://localhost:8000/v1/health

2. Request embeddings (single image = batch of 1):

   curl -X POST http://localhost:8000/v1/embeddings \
     -H "Content-Type: application/json" \
     -d '{
       "images": [
         {"image_url": "https://example.com/image.jpg", "id": "img-1"}
       ]
     }'

Recommendations

• For GPU, set DEVICE=cuda and run with the NVIDIA container runtime.
• Use BATCH_SIZE to cap request size and manage latency.

Limitations

• Model download time: First start will download the model from Hugging Face.
• URL inputs: Only http/https are allowed, and internal IPs are blocked by default.

References

• Hugging Face Transformers
• DINOv3 model card

Author

• AI Service Centre Berlin Brandenburg

License

See LICENSE.

---

Acknowledgements

The AI Service Centre Berlin Brandenburg is funded by the Federal Ministry of Research, Technology and Space under the funding code 01IS22092.