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:
- Configure your database and vector store
- Run the setup script
- 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"
}
)