Image Search API

Advanced semantic search for products using AI-powered image and text queries

Overview

The Image Search API provides powerful semantic search capabilities for product catalogs using state-of-the-art CLIP models and vector databases.

🔍 Image Search

Upload product images to find visually similar items in your catalog

📝 Text Search

Use natural language queries to discover products

🤖 AI-Powered

Advanced CLIP models for superior understanding of images and text

⚡ Fast & Scalable

Vector databases for lightning-fast search across millions of products

Key Features

  • Multi-modal Search: Search by image, text, or both
  • Advanced Filtering: Filter by price, category, brand, and more
  • Smart Reranking: AI-powered result optimization
  • Multiple Vector Stores: ChromaDB, Pinecone, Qdrant, Weaviate, pgVector
  • Database Flexibility: SQLite, PostgreSQL, MySQL support
  • Auto-monitoring: Automatic indexing of new products

Quick Start

🚀 Get started in 3 steps:
  1. Configure your database and vector store
  2. Run the setup script
  3. Start the API

1. Configuration

Copy the example configuration and customize it:

cp config.example.yaml config.yaml # Edit config.yaml with your database settings

2. Setup

# Validate configuration and test connections python setup.py

3. Run

# Start the API (automatically indexes your products) python run.py

Your API will be available at http://localhost:8000

API Endpoints

Search Products

POST /search

Search for products using image upload or text query

Parameters

Parameter Type Required Description
file File Optional Image file to search with
query String Optional Text query for search
top_k Integer Optional Number of results to return (default: 10)
min_price Float Optional Minimum price filter
max_price Float Optional Maximum price filter
title_substr String Optional Title substring filter

Example Request

# Image search curl -X POST "http://localhost:8000/search" \ -F "file=@product.jpg" \ -F "top_k=5" # Text search curl -X POST "http://localhost:8000/search" \ -F "query=wireless headphones" \ -F "top_k=10" \ -F "min_price=50" \ -F "max_price=200"

Response

{ "results": [ { "id": "prod_123", "title": "Wireless Bluetooth Headphones", "image_url": "https://example.com/headphones.jpg", "price": 99.99, "category": "Electronics", "brand": "TechBrand", "score": 0.95, "rank": 1 } ], "latency_ms": 45 }

Product Management

GET /products

Get list of products with optional filtering

Query Parameters

Parameter Type Description
limit Integer Number of products to return (default: 20, max: 100)
offset Integer Number of products to skip (default: 0)
category String Filter by category
brand String Filter by brand
min_price Float Minimum price filter
max_price Float Maximum price filter
GET /products/{product_id}

Get a specific product by ID

POST /products

Create a new product (requires admin token)

PUT /products/{product_id}

Update an existing product (requires admin token)

DELETE /products/{product_id}

Delete a product (requires admin token)

Administration

GET /admin/stats

Get database and system statistics (requires admin token)

GET /admin/metrics

Get search performance metrics (requires admin token)

POST /admin/reindex

Trigger reindexing of all products (requires admin token)

Health & Monitoring

GET /health

Check system health and status

GET /metrics

Get Prometheus-format metrics

Configuration

The API uses a YAML configuration file to specify database connections, vector store settings, and other options.

Configuration File Structure

# Database Configuration database: type: sqlite # sqlite, postgresql, mysql connection_string: "sqlite:///./my_products.db" table_name: "products" columns: id: "product_id" title: "name" image_url: "image" category: "category" brand: "brand" price: "price" rating: "rating" description: "description" # Vector Store Configuration vector_store: type: chromadb # chromadb, pinecone, qdrant, weaviate, pgvector collection_name: "product_embeddings" chromadb: mode: persistent path: "./data/chroma_db" # AI Configuration ai: clip_model: "clip-ViT-L-14" # or clip-ViT-B-32 # API Configuration api: host: "0.0.0.0" port: 8000 reload: false # Auto-monitoring monitoring: enabled: true interval: 60 # seconds

Supported Databases

Database Connection String Format Best For
SQLite sqlite:///./database.db Development, small catalogs
PostgreSQL postgresql://user:pass@host:port/db Production, large catalogs
MySQL mysql://user:pass@host:port/db Production, existing MySQL setups

Supported Vector Stores

Vector Store Type Best For
ChromaDB chromadb Development, small catalogs
Pinecone pinecone Production, managed service
Qdrant qdrant Self-hosted, production
Weaviate weaviate Self-hosted, production
pgVector pgvector PostgreSQL integration

Examples

Python Client Example

import requests # Search by image with open('product.jpg', 'rb') as f: response = requests.post('http://localhost:8000/search', files={'file': f}, data={'top_k': 5}) # Search by text response = requests.post('http://localhost:8000/search', data={'query': 'wireless headphones', 'top_k': 10, 'min_price': 50, 'max_price': 200}) results = response.json()['results'] for product in results: print(f"{product['title']} - ${product['price']} (Score: {product['score']:.3f})")

JavaScript/Node.js Example

const FormData = require('form-data'); const fs = require('fs'); // Search by image const form = new FormData(); form.append('file', fs.createReadStream('product.jpg')); form.append('top_k', '5'); fetch('http://localhost:8000/search', { method: 'POST', body: form }) .then(response => response.json()) .then(data => { console.log('Search results:', data.results); }); // Search by text fetch('http://localhost:8000/search', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: 'query=wireless headphones&top_k=10&min_price=50&max_price=200' }) .then(response => response.json()) .then(data => { console.log('Search results:', data.results); });

cURL Examples

# Image search curl -X POST "http://localhost:8000/search" \ -F "file=@product.jpg" \ -F "top_k=5" # Text search with filters curl -X POST "http://localhost:8000/search" \ -F "query=wireless headphones" \ -F "top_k=10" \ -F "min_price=50" \ -F "max_price=200" # Get product list curl "http://localhost:8000/products?limit=20&category=Electronics" # Health check curl "http://localhost:8000/health"

Python SDK

The Image Search SDK provides a Python client for easy integration with your applications.

Installation

pip install image-search-sdk

Quick Start

from image_search_sdk import ImageSearchClient, Product, SearchOptions # Initialize client client = ImageSearchClient( data_dir="./my_data", model_name="clip-ViT-L-14", vector_store_type="chromadb", vector_store_config={ "mode": "persistent", "path": "./data/chroma" } ) # Connect to your database client.connect_database( connection_string="sqlite:///products.db", table_name="products", id_column="product_id", title_column="name", image_url_column="image" ) # Initialize embeddings stats = client.initialize() print(f"Indexed {stats['indexed_products']} products") # Search by image results = client.search_by_image("query.jpg", SearchOptions(top_k=5)) # Search by text results = client.search_by_text("wireless headphones", SearchOptions(top_k=10)) # Add new product new_product = Product( id="prod_123", title="New Product", image_url="https://example.com/image.jpg", category="Electronics", price=99.99 ) client.add_product(new_product)

SDK Features

  • Local Processing: No API calls - everything runs locally
  • Multiple Vector Stores: ChromaDB, Pinecone, Qdrant, Weaviate, pgVector
  • Database Flexibility: Works with any SQL database
  • Auto-monitoring: Automatically index new products
  • Schema Mapping: Flexible column mapping for any database schema

Configuration Examples

ChromaDB (Local Development)

client = ImageSearchClient( vector_store_type="chromadb", vector_store_config={ "mode": "persistent", "path": "./data/chroma" } )

Pinecone (Production)

client = ImageSearchClient( vector_store_type="pinecone", vector_store_config={ "api_key": "your-pinecone-key", "environment": "us-west1-gcp", "index_name": "product-search" } )

Qdrant (Self-hosted)

client = ImageSearchClient( vector_store_type="qdrant", vector_store_config={ "mode": "server", "host": "localhost", "port": 6333, "api_key": "your-qdrant-key" } )