Skip to content

Instantly share code, notes, and snippets.

@Netzach-Nyss
Created September 3, 2025 11:35
Show Gist options
  • Select an option

  • Save Netzach-Nyss/07b1002d9fd89e7ba1b70c432afef35a to your computer and use it in GitHub Desktop.

Select an option

Save Netzach-Nyss/07b1002d9fd89e7ba1b70c432afef35a to your computer and use it in GitHub Desktop.
"""
Simple FastAPI application for semantic image search using RavenDB and
SentenceTransformers.
To run the application locally:
.. code-block:: shell
uvicorn fastapi_ravendb_server:app --reload
Ensure that RavenDB is running on ``http://localhost:8080`` and that
the ``VectorSearchImages`` database exists. You will also need the
``sentence-transformers`` and ``ravendb`` packages installed.
"""
from __future__ import annotations
import mimetypes
import os
from typing import List, Optional
from fastapi import FastAPI, File, Form, HTTPException, Path, Query, UploadFile
from fastapi.responses import JSONResponse, Response
from pydantic import BaseModel
from ravendb import DocumentStore
from sentence_transformers import SentenceTransformer
import random
PRICE_MIN = float(os.environ.get("PRICE_MIN", "5"))
PRICE_MAX = float(os.environ.get("PRICE_MAX", "199"))
class Product(BaseModel):
"""Pydantic model representing a product stored in the database.
Each product has a name, a vector embedding describing its visual
content, and a corresponding image stored as an attachment. The
``embedding`` field is used for vector search, while the image
attachment can be retrieved by its document id and filename.
"""
Id: Optional[str] = None
name: str
price: float
embedding: List[float]
image_filename: str
# ---------------------------------------------------------------------------
# Configuration and application setup
# ---------------------------------------------------------------------------
RAVEN_DB_URL = os.environ.get("RAVEN_URL", "http://localhost:8080")
RAVEN_DATABASE = os.environ.get("RAVEN_DATABASE", "VectorSearchImages")
document_store = DocumentStore(RAVEN_DB_URL, RAVEN_DATABASE)
document_store.initialize()
EMBEDDING_MODEL_NAME = os.environ.get("EMBEDDING_MODEL", "clip-ViT-B-32")
_sentence_transformer: Optional[SentenceTransformer] = None
def get_model() -> SentenceTransformer:
"""Return a singleton SentenceTransformer instance."""
global _sentence_transformer
if _sentence_transformer is None:
_sentence_transformer = SentenceTransformer(EMBEDDING_MODEL_NAME)
return _sentence_transformer
def get_img_embedding(model: SentenceTransformer, img: bytes) -> List[float]:
"""Compute the embedding vector for an in-memory image."""
from PIL import Image
import io
with Image.open(io.BytesIO(img)) as img:
embedding = model.encode(img)
return embedding.tolist()
def get_txt_embedding(model: SentenceTransformer, txt: str) -> List[float]:
"""Compute the embedding vector for a text query."""
return model.encode(txt).tolist()
def store_product_with_attachment(
session, image: UploadFile, model: SentenceTransformer, name: str
) -> Product:
"""Store a product (image) and its embedding in RavenDB."""
file_bytes = image.file.read()
embedding = get_img_embedding(model, file_bytes)
doc = Product(
name=name.strip(),
price=round(random.uniform(PRICE_MIN, PRICE_MAX), 2), # random price
embedding=embedding,
image_filename=image.filename,
)
session.store(doc)
session.advanced.attachments.store(doc.Id, doc.image_filename, file_bytes)
return doc
def vector_search_common(query_embedding: List[float], limit: int):
"""Shared search path: vector query -> fetch attachments -> response payload."""
with document_store.open_session() as session:
results = (
session.query(object_type=Product)
.vector_search("embedding", query_embedding)
.take(limit)
)
products = list(results)
if not products:
raise HTTPException(status_code=404, detail="No products found")
return products
app = FastAPI(title="Semantic Image Search API", version="0.1.0")
@app.post(
"/products",
response_class=JSONResponse,
summary="Upload a product image and store it with its embedding",
)
async def upload_product(
file: UploadFile = File(...),
name: str = Form(..., min_length=1),
):
model = get_model()
with document_store.open_session() as session:
doc = store_product_with_attachment(session, file, model, name=name)
session.save_changes()
return {"id": doc.Id, "name": doc.name, "price": doc.price}
@app.get(
"/products",
response_class=JSONResponse,
summary="Find products similar to a text query",
)
async def search_products(
query: str = Query(..., description="Natural language description of the desired product"),
limit: int = Query(1, ge=1, le=50, description="Maximum number of similar products to return"),
):
model = get_model()
qvec = get_txt_embedding(model, query)
return vector_search_common(qvec, limit)
@app.post(
"/products/search-by-image",
response_class=JSONResponse,
summary="Find products similar to an uploaded image",
)
async def search_products_by_image(
image: UploadFile = File(..., description="Image file to use for the search"),
limit: int = Query(1, ge=1, le=50, description="Maximum number of similar products to return"),
):
model = get_model()
file_bytes = image.file.read()
qvec = get_img_embedding(model, file_bytes)
return vector_search_common(qvec, limit)
@app.get(
"/products/{product_id}/image/{filename}",
summary="Get a product image by ID and filename",
)
async def get_product_image(
product_id: str = Path(..., description="ID of the product"),
filename: str = Path(..., description="Filename of the image"),
):
with document_store.open_session() as session:
# Get the attachment
attachment = session.advanced.attachments.get(product_id, filename)
if attachment is None:
raise HTTPException(status_code=404, detail="Image not found")
# Determine content type
content_type, _ = mimetypes.guess_type(filename)
if content_type is None:
content_type = "application/octet-stream"
# Return the image
return Response(content=attachment.data, media_type=content_type)
if __name__ == "__main__":
# Minimal runner so you can do: python this_file.py
# For auto-reload, prefer the CLI:
# uvicorn this_file:app --reload
import uvicorn
host = os.environ.get("HOST", "0.0.0.0")
port = int(os.environ.get("PORT", "8000"))
log_level = os.environ.get("LOG_LEVEL", "info")
# Note: passing the app object disables --reload. Use the CLI form above if you need reload.
uvicorn.run(app, host=host, port=port, log_level=log_level)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment