217 lines
5.7 KiB
Markdown
217 lines
5.7 KiB
Markdown
# Recommendation AI Production Readiness
|
|
|
|
This runbook covers the production prerequisites for the Skinbase recommendation AI stack:
|
|
|
|
- vision analysis via `VISION_GATEWAY_URL` or CLIP/YOLO endpoints
|
|
- embedding generation
|
|
- vector upsert/search via the vector gateway
|
|
- hybrid discovery feed v2/v3
|
|
- upload-triggered AI processing
|
|
|
|
## 1. Required runtime services
|
|
|
|
You need these services available before enabling the stack:
|
|
|
|
- Laravel queue workers
|
|
- a configured public files/CDN base so artwork derivatives resolve to public URLs
|
|
- a vision gateway for `/analyze/all`, or CLIP and YOLO services individually
|
|
- a vector gateway exposing `/vectors/upsert` and `/vectors/search`
|
|
- a queue backend suitable for async jobs, preferably Redis in production
|
|
|
|
## 2. Required environment variables
|
|
|
|
### Core queue and upload
|
|
|
|
```dotenv
|
|
QUEUE_CONNECTION=redis
|
|
UPLOAD_QUEUE_DERIVATIVES=true
|
|
VISION_QUEUE=vision
|
|
RECOMMENDATIONS_QUEUE=recommendations
|
|
DISCOVERY_QUEUE=discovery
|
|
```
|
|
|
|
If you do not want dedicated queues, leave the queue names unset or set them to `default`.
|
|
|
|
### Vision analysis
|
|
|
|
```dotenv
|
|
VISION_ENABLED=true
|
|
VISION_IMAGE_VARIANT=md
|
|
|
|
VISION_GATEWAY_URL=https://vision.example.com
|
|
VISION_GATEWAY_TIMEOUT=10
|
|
VISION_GATEWAY_CONNECT_TIMEOUT=3
|
|
|
|
CLIP_BASE_URL=https://clip.example.com
|
|
CLIP_ANALYZE_ENDPOINT=/analyze
|
|
CLIP_EMBED_ENDPOINT=/embed
|
|
|
|
YOLO_ENABLED=true
|
|
YOLO_BASE_URL=https://yolo.example.com
|
|
YOLO_ANALYZE_ENDPOINT=/analyze
|
|
YOLO_PHOTOGRAPHY_ONLY=true
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `VISION_GATEWAY_URL` is the preferred unified path because the app can ingest CLIP tags, BLIP caption, and YOLO objects from `/analyze/all`
|
|
- CLIP embedding generation still uses the CLIP embed endpoint configured in `config/recommendations.php`
|
|
|
|
### Vector search and indexing
|
|
|
|
```dotenv
|
|
VISION_VECTOR_GATEWAY_ENABLED=true
|
|
VISION_VECTOR_GATEWAY_URL=https://vector.example.com
|
|
VISION_VECTOR_GATEWAY_API_KEY=replace-me
|
|
VISION_VECTOR_GATEWAY_COLLECTION=images
|
|
VISION_VECTOR_GATEWAY_UPSERT_ENDPOINT=/vectors/upsert
|
|
VISION_VECTOR_GATEWAY_SEARCH_ENDPOINT=/vectors/search
|
|
VISION_VECTOR_GATEWAY_DELETE_ENDPOINT=/vectors/delete
|
|
```
|
|
|
|
### Discovery and rollout
|
|
|
|
```dotenv
|
|
DISCOVERY_V2_ENABLED=true
|
|
DISCOVERY_V2_ALGO_VERSION=clip-cosine-v2-adaptive
|
|
DISCOVERY_V2_ROLLOUT_PERCENTAGE=100
|
|
|
|
DISCOVERY_V3_ENABLED=true
|
|
DISCOVERY_V3_CACHE_TTL_MINUTES=5
|
|
DISCOVERY_V3_VECTOR_SIMILARITY_WEIGHT=0.8
|
|
DISCOVERY_V3_VECTOR_BASE_SCORE=0.75
|
|
DISCOVERY_V3_MAX_SEED_ARTWORKS=3
|
|
DISCOVERY_V3_VECTOR_CANDIDATE_POOL=60
|
|
```
|
|
|
|
### Embeddings
|
|
|
|
```dotenv
|
|
RECOMMENDATIONS_EMBEDDING_ENABLED=true
|
|
RECOMMENDATIONS_EMBEDDING_MODEL=clip
|
|
RECOMMENDATIONS_EMBEDDING_MODEL_VERSION=v1
|
|
RECOMMENDATIONS_ALGO_VERSION=clip-cosine-v1
|
|
RECOMMENDATIONS_MIN_DIM=64
|
|
RECOMMENDATIONS_MAX_DIM=4096
|
|
```
|
|
|
|
## 3. Queue worker coverage
|
|
|
|
The AI stack dispatches jobs onto these queue families:
|
|
|
|
- `vision` via `AutoTagArtworkJob`
|
|
- `recommendations` via embedding generation, vector backfill, and similarity jobs
|
|
- `discovery` via feed cache regeneration
|
|
- `default` if dedicated queue env vars are not set
|
|
|
|
The example worker configs in `deploy/` now listen on:
|
|
|
|
```text
|
|
forum-security,forum-moderation,vision,recommendations,discovery,mail,default
|
|
```
|
|
|
|
If you run separate workers per queue, ensure all configured queue names are consumed somewhere.
|
|
|
|
## 4. Upload pipeline behavior
|
|
|
|
Upload finish dispatches these async jobs after derivatives exist:
|
|
|
|
- `AutoTagArtworkJob`
|
|
- `GenerateArtworkEmbeddingJob`
|
|
|
|
If `UPLOAD_QUEUE_DERIVATIVES=true`, derivative generation is also queued before those jobs can run. That means a broken worker setup can block the entire AI post-processing chain even if uploads themselves succeed.
|
|
|
|
## 5. Database and schema expectations
|
|
|
|
Confirm the database includes the current AI/discovery schema:
|
|
|
|
- artwork AI metadata columns on `artworks`
|
|
- `last_vector_indexed_at` on `artworks`
|
|
- artwork embeddings table
|
|
- discovery cache and event tables used by feed generation
|
|
|
|
Recommended checks:
|
|
|
|
```bash
|
|
php artisan migrate --force
|
|
php artisan schema:audit-migrations
|
|
```
|
|
|
|
## 6. Deployment checklist
|
|
|
|
Run these after deploy:
|
|
|
|
```bash
|
|
php artisan config:cache
|
|
php artisan route:cache
|
|
php artisan queue:restart
|
|
php artisan optimize
|
|
```
|
|
|
|
If you changed frontend assets, also ensure the Vite manifest exists before smoke-testing browser flows.
|
|
|
|
## 7. Smoke tests
|
|
|
|
Recommended application-level checks:
|
|
|
|
```bash
|
|
php artisan artworks:vectors-index --limit=1
|
|
php artisan artworks:vectors-search {artwork_id} --limit=5
|
|
vendor/bin/pest tests/Feature/Vision/GenerateArtworkEmbeddingJobTest.php
|
|
vendor/bin/pest tests/Feature/Vision/AiArtworkSearchApiTest.php
|
|
vendor/bin/pest tests/Feature/Discovery/FeedEndpointV2Test.php
|
|
```
|
|
|
|
Recommended HTTP checks:
|
|
|
|
- `GET /api/art/{id}/similar-ai`
|
|
- `POST /api/search/image`
|
|
- `GET /api/v1/feed?algo_version=clip-cosine-v2-adaptive&limit=12`
|
|
|
|
## 8. Failure modes to watch
|
|
|
|
### Uploads succeed but AI fields stay empty
|
|
|
|
Likely causes:
|
|
|
|
- workers are not running
|
|
- workers do not consume `vision` or `recommendations`
|
|
- `VISION_ENABLED=false`
|
|
- derivative URLs are not publicly reachable by the vision services
|
|
|
|
### Similar AI endpoints return 503
|
|
|
|
Likely causes:
|
|
|
|
- `VISION_VECTOR_GATEWAY_ENABLED=false`
|
|
- missing `VISION_VECTOR_GATEWAY_URL`
|
|
- missing `VISION_VECTOR_GATEWAY_API_KEY`
|
|
|
|
### Feed works but has no vector influence
|
|
|
|
Likely causes:
|
|
|
|
- `DISCOVERY_V3_ENABLED=false`
|
|
- vector gateway search unavailable
|
|
- no recent user seed artworks
|
|
- artworks have local embeddings but were never upserted
|
|
|
|
### Vector repair/backfill stalls
|
|
|
|
Likely causes:
|
|
|
|
- `RECOMMENDATIONS_QUEUE` is set but workers do not listen on it
|
|
- queue backend is unhealthy
|
|
|
|
## 9. Operational recommendation
|
|
|
|
For first rollout, keep the queue names explicit but simple:
|
|
|
|
```dotenv
|
|
VISION_QUEUE=default
|
|
RECOMMENDATIONS_QUEUE=default
|
|
DISCOVERY_QUEUE=default
|
|
```
|
|
|
|
Once the stack is stable, split them into dedicated workers only if queue volume justifies it.
|