docs: update README and USAGE for card-renderer, Qdrant optimization endpoints, and search params

2026-03-31 20:16:55 +02:00
parent 6ea91c3452
commit 3f925e17d5
2 changed files with 207 additions and 13 deletions
--- a/USAGE.md
+++ b/USAGE.md
@@ -4,7 +4,7 @@ This document explains how to run and use the Skinbase Vision Stack (Gateway + C

 ## Overview

- Services: `gateway`, `clip`, `blip`, `yolo`, `qdrant`, `qdrant-svc` (FastAPI each, except `qdrant` which is the official Qdrant DB).
+- Services: `gateway`, `clip`, `blip`, `yolo`, `qdrant`, `qdrant-svc`, `card-renderer` (FastAPI each, except `qdrant` which is the official Qdrant DB).
 - Gateway is the public API endpoint; the other services are internal.

 ## Model overview
@@ -17,6 +17,8 @@ This document explains how to run and use the Skinbase Vision Stack (Gateway + C

 - **Qdrant**: High-performance vector similarity search engine. Stores CLIP image embeddings and enables reverse image search (find similar images). The `qdrant-svc` wrapper auto-embeds images via CLIP before upserting.

+- **Card Renderer**: Generates branded social-card images (e.g. Open Graph previews) from artwork images. Applies smart center-weighted cropping, gradient overlays, title/username/tag text, and an optional logo. Returns binary image bytes (WebP by default). Template: `nova-artwork-v1`.
+
 ## Prerequisites

 - Docker Desktop (with `docker compose`) or a Docker environment.
@@ -219,8 +221,11 @@ Parameters:
 - `url` (required): query image URL.
 - `limit` (optional, default 5): number of results.
 - `score_threshold` (optional): minimum cosine similarity (0.0–1.0).
- `filter_metadata` (optional): filter results by metadata, e.g. `{"category":"wallpaper"}`.
+- `filter_metadata` (optional): filter results by payload fields, e.g. `{"is_public":true,"category_id":3}`.
 - `collection` (optional): collection to search.
+- `hnsw_ef` (optional, int): override the HNSW ef parameter at query time. Higher = better recall, slightly more latency.
+- `exact` (optional, bool, default false): brute-force exact search. Avoid on large collections.
+- `indexed_only` (optional, bool, default false): restrict search to fully indexed segments only. Useful during bulk ingest.

 Return: list of `{"id", "score", "metadata"}` sorted by similarity.

@@ -230,16 +235,19 @@ Return: list of `{"id", "score", "metadata"}` sorted by similarity.
 curl -X POST https://vision.klevze.net/vectors/search/file \
  -H "X-API-Key: <your-api-key>" \
  -F "file=@/path/to/image.webp" \
-  -F "limit=5"
+  -F "limit=5" \
+  -F 'filter_metadata_json={"is_public":true}'
 ```

+All URL search parameters are available as form fields; use `filter_metadata_json` (JSON string) for filters.
+
 #### Search by pre-computed vector

 ```bash
 curl -X POST https://vision.klevze.net/vectors/search/vector \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
-  -d '{"vector":[0.1,0.2,...],"limit":5}'
+  -d '{"vector":[0.1,0.2,...],"limit":5,"hnsw_ef":128}'
 ```

 #### Collection management
@@ -267,6 +275,67 @@ Delete a collection:
 curl -H "X-API-Key: <your-api-key>" -X DELETE https://vision.klevze.net/vectors/collections/my_collection
 ```

+#### Full diagnostic inspect
+
+Returns HNSW config, optimizer config, quantization, segment count, payload index coverage percentages, and RAM footprint estimate for every collection.
+
+```bash
+curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/inspect
+```
+
+#### Payload index management
+
+Payload indexes are critical for fast filtered vector search. Always create indexes for fields used in `filter_metadata` filters.
+
+```bash
+# List existing indexes
+curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collections/images/indexes
+
+# Create a single index
+curl -X POST https://vision.klevze.net/vectors/collections/images/indexes \
+  -H "X-API-Key: <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"field":"is_public","type":"bool"}'
+
+# Ensure multiple indexes exist (idempotent — safe to run multiple times)
+curl -X POST https://vision.klevze.net/vectors/collections/images/ensure-indexes \
+  -H "X-API-Key: <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"fields":[{"field":"is_public","type":"bool"},{"field":"is_deleted","type":"bool"},{"field":"category_id","type":"integer"},{"field":"user_id","type":"keyword"}]}'
+```
+
+Supported index types: `keyword`, `integer`, `float`, `bool`, `geo`, `datetime`, `text`, `uuid`.
+
+#### Collection configuration (HNSW / optimizer / quantization)
+
+Updates HNSW, optimizer, or scalar quantization settings on an existing collection without data loss. HNSW graph and segment changes apply to newly created segments.
+
+```bash
+curl -X POST https://vision.klevze.net/vectors/collections/images/configure \
+  -H "X-API-Key: <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "hnsw_m": 16,
+    "hnsw_ef_construct": 200,
+    "hnsw_on_disk": false,
+    "indexing_threshold": 20000,
+    "default_segment_number": 4,
+    "quantization_type": "int8",
+    "quantization_quantile": 0.99,
+    "quantization_always_ram": true
+  }'
+```
+
+Parameters:
+- `hnsw_m` (int, 4–64): edges per node in the HNSW graph.
+- `hnsw_ef_construct` (int, 10–1000): ef during index construction.
+- `hnsw_on_disk` (bool): store HNSW graph on disk (saves RAM, slightly slower queries).
+- `indexing_threshold` (int): minimum vector changes before a segment is indexed.
+- `default_segment_number` (int, 1–32): target segment count for parallelism.
+- `quantization_type` (string, `"int8"` or null): enable scalar quantization (~4× RAM reduction).
+- `quantization_quantile` (float, 0.5–1.0, default 0.99): calibration quantile.
+- `quantization_always_ram` (bool, default true): keep quantized vectors in RAM.
+
 #### Delete points

 ```bash
@@ -290,6 +359,67 @@ If the wrapper had to replace your string `id` with a generated UUID, the origin
 curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/points/by-original-id/img-001
 ```

+## Card Renderer
+
+The card renderer generates branded social-card images from artwork photos. It applies smart center-weighted cropping, a gradient overlay, title/subtitle/username/category text, optional tags, and an optional logo.
+
+Default output: 1200×630 WebP (`nova-artwork-v1` template).
+
+### List available templates
+
+```bash
+curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/cards/templates
+```
+
+### Render a card from a URL
+
+```bash
+curl -X POST https://vision.klevze.net/cards/render \
+  -H "X-API-Key: <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://files.skinbase.org/img/aa/bb/cc/md.webp",
+    "title": "Artwork Title",
+    "subtitle": "Optional subtitle",
+    "username": "@artist",
+    "category": "Digital Art",
+    "tags": ["surreal", "landscape"],
+    "template": "nova-artwork-v1",
+    "width": 1200,
+    "height": 630,
+    "output": "webp",
+    "quality": 90,
+    "show_logo": true
+  }'
+```
+
+Returns binary image bytes with `Content-Type: image/webp`.
+
+### Render a card from a file upload
+
+```bash
+curl -X POST https://vision.klevze.net/cards/render/file \
+  -H "X-API-Key: <your-api-key>" \
+  -F "file=@/path/to/image.webp" \
+  -F "title=Artwork Title" \
+  -F "username=@artist" \
+  -F "template=nova-artwork-v1" \
+  -F "show_logo=true"
+```
+
+Returns binary image bytes.
+
+### Get card layout metadata (no image rendered)
+
+```bash
+curl -X POST https://vision.klevze.net/cards/render/meta \
+  -H "X-API-Key: <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","title":"Artwork Title"}'
+```
+
+Returns crop coordinates and layout data without producing an image.
+
 ## Request/Response notes

 - For URL requests use `Content-Type: application/json`.
@@ -340,9 +470,5 @@ uvicorn main:app --host 0.0.0.0 --port 8000
 - `gateway/` — gateway FastAPI server.
 - `clip/`, `blip/`, `yolo/` — service implementations and Dockerfiles.
 - `qdrant/` — Qdrant API wrapper service (FastAPI).
+- `card-renderer/` — card rendering service (FastAPI).
 - `common/` — shared helpers (e.g., image I/O).
-
---
-
-If you want, I can merge these same contents into the project `README.md`,
-create a Postman collection, or add example response schemas for each endpoint.