klevze/vision
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Gregor Klevže
2026-03-31 20:16:55 +02:00
parent 6ea91c3452
commit 3f925e17d5
2 changed files with 207 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
README.md
View File

@@ -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. and a **Gateway API** that can call them individually or together.
## Services & Ports ## Services & Ports
@@ -11,6 +11,7 @@ and a **Gateway API** that can call them individually or together.
- `yolo`: internal only - `yolo`: internal only
- `qdrant`: vector DB (port `6333` exposed for direct access) - `qdrant`: vector DB (port `6333` exposed for direct access)
- `qdrant-svc`: internal Qdrant API wrapper - `qdrant-svc`: internal Qdrant API wrapper
- `card-renderer`: internal card rendering service
## Run ## Run
@@ -129,14 +130,17 @@ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/up
```bash ```bash
curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/search \ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/search \
-H "Content-Type: application/json" \ -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 ### Search similar images by file upload
```bash ```bash
curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/search/file \ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/search/file \
-F "file=@/path/to/image.webp" \ -F "file=@/path/to/image.webp" \
-F "limit=5" -F "limit=5" \
-F 'filter_metadata_json={"is_public":true}'
``` ```
### List collections ### List collections
@@ -149,6 +153,38 @@ curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collection
curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collections/images curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collections/images
``` ```
### Full diagnostic inspect
```bash
curl -H "X-API-Key: <your-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: <your-api-key>" https://vision.klevze.net/vectors/collections/images/indexes
# Create a single index
curl -H "X-API-Key: <your-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: <your-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: <your-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 ### Delete points
```bash ```bash
curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/delete \ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/delete \
@@ -158,6 +194,38 @@ curl -H "X-API-Key: <your-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. 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: <your-api-key>" https://vision.klevze.net/cards/templates
```
### Render a card from a URL
```bash
curl -H "X-API-Key: <your-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: <your-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: <your-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 ## Notes
- This is a **starter scaffold**. Models are loaded at service startup. - This is a **starter scaffold**. Models are loaded at service startup.

144
USAGE.md
View File

@@ -4,7 +4,7 @@ This document explains how to run and use the Skinbase Vision Stack (Gateway + C
## Overview ## 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. - Gateway is the public API endpoint; the other services are internal.
## Model overview ## 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. - **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 ## Prerequisites
- Docker Desktop (with `docker compose`) or a Docker environment. - Docker Desktop (with `docker compose`) or a Docker environment.
@@ -219,8 +221,11 @@ Parameters:
- `url` (required): query image URL. - `url` (required): query image URL.
- `limit` (optional, default 5): number of results. - `limit` (optional, default 5): number of results.
- `score_threshold` (optional): minimum cosine similarity (0.0–1.0). - `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. - `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. 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 \ curl -X POST https://vision.klevze.net/vectors/search/file \
-H "X-API-Key: <your-api-key>" \ -H "X-API-Key: <your-api-key>" \
-F "file=@/path/to/image.webp" \ -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 #### Search by pre-computed vector
```bash ```bash
curl -X POST https://vision.klevze.net/vectors/search/vector \ curl -X POST https://vision.klevze.net/vectors/search/vector \
-H "X-API-Key: <your-api-key>" \ -H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \ -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 #### 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 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 #### Delete points
```bash ```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 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 ## Request/Response notes
- For URL requests use `Content-Type: application/json`. - 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. - `gateway/` — gateway FastAPI server.
- `clip/`, `blip/`, `yolo/` — service implementations and Dockerfiles. - `clip/`, `blip/`, `yolo/` — service implementations and Dockerfiles.
- `qdrant/` — Qdrant API wrapper service (FastAPI). - `qdrant/` — Qdrant API wrapper service (FastAPI).
- `card-renderer/` — card rendering service (FastAPI).
- `common/` — shared helpers (e.g., image I/O). - `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.