From 3f925e17d57746722b1d035ebba8fef5f5488681 Mon Sep 17 00:00:00 2001 From: Gregor Klevze Date: Tue, 31 Mar 2026 20:16:55 +0200 Subject: [PATCH] docs: update README and USAGE for card-renderer, Qdrant optimization endpoints, and search params --- README.md | 76 ++++++++++++++++++++++++++-- USAGE.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 207 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 937ca8d..4b11000 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Skinbase Vision Stack (CLIP + BLIP + YOLO + Qdrant) – Dockerized FastAPI +# Skinbase Vision Stack (CLIP + BLIP + YOLO + Qdrant + Card Renderer) – Dockerized FastAPI -This repository provides **four standalone vision services** (CLIP / BLIP / YOLO / Qdrant) +This repository provides **five standalone vision services** (CLIP / BLIP / YOLO / Qdrant / Card Renderer) and a **Gateway API** that can call them individually or together. ## Services & Ports @@ -11,6 +11,7 @@ and a **Gateway API** that can call them individually or together. - `yolo`: internal only - `qdrant`: vector DB (port `6333` exposed for direct access) - `qdrant-svc`: internal Qdrant API wrapper +- `card-renderer`: internal card rendering service ## Run @@ -129,14 +130,17 @@ curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/up ```bash curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/search \ -H "Content-Type: application/json" \ - -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","limit":5}' + -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","limit":5,"filter_metadata":{"is_public":true}}' ``` +Optional search parameters: `hnsw_ef` (int), `exact` (bool), `indexed_only` (bool), `score_threshold` (float), `filter_metadata` (object). + ### Search similar images by file upload ```bash curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/search/file \ -F "file=@/path/to/image.webp" \ - -F "limit=5" + -F "limit=5" \ + -F 'filter_metadata_json={"is_public":true}' ``` ### List collections @@ -149,6 +153,38 @@ curl -H "X-API-Key: " https://vision.klevze.net/vectors/collection curl -H "X-API-Key: " https://vision.klevze.net/vectors/collections/images ``` +### Full diagnostic inspect +```bash +curl -H "X-API-Key: " https://vision.klevze.net/vectors/inspect +``` + +Returns HNSW config, optimizer config, quantization, segment count, payload index coverage, and RAM estimate for every collection. + +### Payload index management +```bash +# List indexes +curl -H "X-API-Key: " https://vision.klevze.net/vectors/collections/images/indexes + +# Create a single index +curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/collections/images/indexes \ + -H "Content-Type: application/json" \ + -d '{"field":"is_public","type":"bool"}' + +# Ensure multiple indexes (idempotent) +curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/collections/images/ensure-indexes \ + -H "Content-Type: application/json" \ + -d '{"fields":[{"field":"is_public","type":"bool"},{"field":"category_id","type":"integer"}]}' +``` + +Supported index types: `keyword`, `integer`, `float`, `bool`, `geo`, `datetime`, `text`, `uuid`. + +### Collection configuration (HNSW / optimizer / quantization) +```bash +curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/collections/images/configure \ + -H "Content-Type: application/json" \ + -d '{"hnsw_m":16,"hnsw_ef_construct":200,"indexing_threshold":20000,"quantization_type":"int8"}' +``` + ### Delete points ```bash curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/delete \ @@ -158,6 +194,38 @@ curl -H "X-API-Key: " -X POST https://vision.klevze.net/vectors/de If you let the wrapper generate a UUID, use the returned `id` value for later `get`, `search`, or `delete` operations. +## Card Renderer + +### List available templates +```bash +curl -H "X-API-Key: " https://vision.klevze.net/cards/templates +``` + +### Render a card from a URL +```bash +curl -H "X-API-Key: " -X POST https://vision.klevze.net/cards/render \ + -H "Content-Type: application/json" \ + -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","title":"Artwork Title","username":"@artist","template":"nova-artwork-v1"}' +``` + +Returns binary image bytes (WebP by default). + +### Render a card from a file upload +```bash +curl -H "X-API-Key: " -X POST https://vision.klevze.net/cards/render/file \ + -F "file=@/path/to/image.webp" \ + -F "title=Artwork Title" \ + -F "username=@artist" \ + -F "template=nova-artwork-v1" +``` + +### Get card layout metadata (no image rendered) +```bash +curl -H "X-API-Key: " -X POST https://vision.klevze.net/cards/render/meta \ + -H "Content-Type: application/json" \ + -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","title":"Artwork Title"}' +``` + ## Notes - This is a **starter scaffold**. Models are loaded at service startup. diff --git a/USAGE.md b/USAGE.md index dc2e238..1c5282f 100644 --- 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: " \ -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: " \ -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: " -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: " 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: " 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: " \ + -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: " \ + -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: " \ + -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: " 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: " 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: " \ + -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: " \ + -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: " \ + -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.