Spaces:
Sleeping
Sleeping
Upload 14 files
#1
by kajalan - opened
- .env.example +48 -0
- README.md +340 -10
- config.py +64 -0
- job_store.py +99 -0
- main.py +131 -0
- pipeline_manager.py +199 -0
- requirements.txt +20 -0
- routes/__init__.py +0 -0
- routes/generate.py +81 -0
- routes/health.py +111 -0
- routes/jobs.py +160 -0
- schemas.py +132 -0
- start.sh +44 -0
- worker.py +179 -0
.env.example
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ── HF CPU Image Generation API — environment configuration ──────────────────
|
| 2 |
+
# Copy this file to .env and edit as needed.
|
| 3 |
+
# All values shown here are the defaults.
|
| 4 |
+
|
| 5 |
+
# ── Server ────────────────────────────────────────────────────────────────────
|
| 6 |
+
HOST=0.0.0.0
|
| 7 |
+
PORT=8000
|
| 8 |
+
DEBUG=false
|
| 9 |
+
|
| 10 |
+
# ── Model ─────────────────────────────────────────────────────────────────────
|
| 11 |
+
# Recommended CPU models (smallest to largest):
|
| 12 |
+
#
|
| 13 |
+
# nota-ai/bk-sdm-small ~500 MB — fastest on CPU (default)
|
| 14 |
+
# runwayml/stable-diffusion-v1-5 ~4 GB — best quality/compat balance
|
| 15 |
+
# stabilityai/stable-diffusion-2-1-base ~5 GB — highest quality
|
| 16 |
+
#
|
| 17 |
+
MODEL_ID=nota-ai/bk-sdm-small
|
| 18 |
+
MODEL_CACHE_DIR=./model_cache
|
| 19 |
+
|
| 20 |
+
# Load the model at startup so the first job doesn't pay cold-start cost.
|
| 21 |
+
# Set to false if you want to control loading manually via POST /models/load
|
| 22 |
+
AUTO_LOAD_MODEL=true
|
| 23 |
+
|
| 24 |
+
# ── CPU Tuning ─────────────────────────────────────────────────────────────────
|
| 25 |
+
# 0 = use all logical CPU cores (recommended)
|
| 26 |
+
CPU_THREADS=0
|
| 27 |
+
|
| 28 |
+
# Slice attention into smaller chunks — lowers peak RAM, minimal speed cost
|
| 29 |
+
ENABLE_ATTENTION_SLICING=true
|
| 30 |
+
|
| 31 |
+
# ── Generation defaults ────────────────────────────────────────────────────────
|
| 32 |
+
# DPM++ scheduler converges well at 20 steps — good CPU/quality balance
|
| 33 |
+
DEFAULT_STEPS=20
|
| 34 |
+
MAX_STEPS=50
|
| 35 |
+
|
| 36 |
+
# 512×512 is ideal for SD v1.x — larger sizes increase RAM and time significantly
|
| 37 |
+
DEFAULT_WIDTH=512
|
| 38 |
+
DEFAULT_HEIGHT=512
|
| 39 |
+
MAX_WIDTH=768
|
| 40 |
+
MAX_HEIGHT=768
|
| 41 |
+
|
| 42 |
+
DEFAULT_GUIDANCE_SCALE=7.5
|
| 43 |
+
|
| 44 |
+
# ── Storage ────────────────────────────────────────────────────────────────────
|
| 45 |
+
OUTPUTS_DIR=./outputs
|
| 46 |
+
|
| 47 |
+
# Auto-delete jobs after N seconds (0 = keep forever)
|
| 48 |
+
JOB_TTL_SECONDS=0
|
README.md
CHANGED
|
@@ -1,13 +1,343 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
---
|
| 2 |
-
|
| 3 |
-
|
| 4 |
-
|
| 5 |
-
|
| 6 |
-
|
| 7 |
-
|
| 8 |
-
|
| 9 |
-
|
| 10 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11 |
---
|
| 12 |
|
| 13 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# HF CPU Image Generation API
|
| 2 |
+
|
| 3 |
+
A production-ready REST API for **Stable Diffusion image generation on CPU** using Hugging Face Diffusers. Built on top of the architecture patterns from [Local AI Image Generator](https://github.com/techjarves/Local-AI-Image-Generator) and redesigned as a stateless, job-queue-based HTTP API.
|
| 4 |
+
|
| 5 |
+
---
|
| 6 |
+
|
| 7 |
+
## Architecture Overview
|
| 8 |
+
|
| 9 |
+
```
|
| 10 |
+
Client
|
| 11 |
+
│
|
| 12 |
+
│ POST /generate → { job_id, status: "queued" }
|
| 13 |
+
│
|
| 14 |
+
│ GET /jobs/{id} → { status: "processing", progress: 45 }
|
| 15 |
+
│ GET /jobs/{id} → { status: "completed", download_url: "..." }
|
| 16 |
+
│
|
| 17 |
+
│ GET /jobs/{id}/download → image.png
|
| 18 |
+
│
|
| 19 |
+
│ DELETE /jobs/{id} → { ok: true }
|
| 20 |
+
│
|
| 21 |
+
▼
|
| 22 |
+
|
| 23 |
+
┌─────────────────────────────────────────────────────────────┐
|
| 24 |
+
│ FastAPI (main.py) │
|
| 25 |
+
│ ├── POST /generate → enqueue job, return job_id │
|
| 26 |
+
│ ├── GET /jobs → list / filter jobs │
|
| 27 |
+
│ ├── GET /jobs/{id} → status + progress │
|
| 28 |
+
│ ├── GET /jobs/{id}/download → FileResponse (PNG) │
|
| 29 |
+
│ ├── DELETE /jobs/{id} → delete job + image │
|
| 30 |
+
│ ├── GET /health → pipeline & queue status │
|
| 31 |
+
│ └── POST /models/load → hot-swap model │
|
| 32 |
+
│ │
|
| 33 |
+
│ job_store.py — thread-safe in-memory job registry │
|
| 34 |
+
│ worker.py — background daemon thread + FIFO queue │
|
| 35 |
+
│ pipeline_manager.py — HF Diffusers pipeline (CPU-tuned) │
|
| 36 |
+
└─────────────────────────────────────────────────────────────┘
|
| 37 |
+
│
|
| 38 |
+
┌────────▼────────┐
|
| 39 |
+
│ outputs/ │
|
| 40 |
+
│ (PNG files) │
|
| 41 |
+
└─────────────────┘
|
| 42 |
+
```
|
| 43 |
+
|
| 44 |
+
---
|
| 45 |
+
|
| 46 |
+
## Quick Start
|
| 47 |
+
|
| 48 |
+
### Prerequisites
|
| 49 |
+
- Python 3.9 or higher
|
| 50 |
+
- 4 GB+ RAM (8 GB recommended for SD v1.5)
|
| 51 |
+
- Internet connection on first run (to download model weights)
|
| 52 |
+
|
| 53 |
+
### 1. Install
|
| 54 |
+
|
| 55 |
+
```bash
|
| 56 |
+
git clone <this-repo>
|
| 57 |
+
cd hf-image-api
|
| 58 |
+
|
| 59 |
+
# Linux / macOS — one command setup:
|
| 60 |
+
bash start.sh
|
| 61 |
+
|
| 62 |
+
# Windows:
|
| 63 |
+
python -m venv .venv
|
| 64 |
+
.venv\Scripts\activate
|
| 65 |
+
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
|
| 66 |
+
pip install -r requirements.txt
|
| 67 |
+
copy .env.example .env
|
| 68 |
+
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
|
| 69 |
+
```
|
| 70 |
+
|
| 71 |
+
### 2. Open the interactive docs
|
| 72 |
+
|
| 73 |
+
```
|
| 74 |
+
http://localhost:8000/docs
|
| 75 |
+
```
|
| 76 |
+
|
| 77 |
+
---
|
| 78 |
+
|
| 79 |
+
## CPU Performance Guide
|
| 80 |
+
|
| 81 |
+
| Model | Size | 512×512 @ 20 steps | Notes |
|
| 82 |
+
|---|---|---|---|
|
| 83 |
+
| `nota-ai/bk-sdm-small` | ~500 MB | **~60–120 s** | Best for CPU — default |
|
| 84 |
+
| `runwayml/stable-diffusion-v1-5` | ~4 GB | ~150–300 s | Standard quality |
|
| 85 |
+
| `stabilityai/stable-diffusion-2-1-base` | ~5 GB | ~200–400 s | Highest quality |
|
| 86 |
+
|
| 87 |
+
### Optimisations applied automatically
|
| 88 |
+
|
| 89 |
+
| Optimisation | Effect |
|
| 90 |
+
|---|---|
|
| 91 |
+
| `torch.float32` | Mandatory for CPU (float16 causes NaN) |
|
| 92 |
+
| `low_cpu_mem_usage=True` | Streams weights into RAM — avoids double-buffering |
|
| 93 |
+
| `enable_attention_slicing(1)` | Lowers peak RAM ~30 %, minimal speed cost |
|
| 94 |
+
| `DPMSolverMultistepScheduler` + Karras sigmas | Converges well at 15–20 steps |
|
| 95 |
+
| `safety_checker=None` | Skips NSFW classifier, saves ~300 MB RAM |
|
| 96 |
+
| `torch.set_num_threads(N)` | Saturates all logical CPU cores |
|
| 97 |
+
| `torch.inference_mode()` | Disables autograd, reduces overhead |
|
| 98 |
+
|
| 99 |
+
### Tips to speed up CPU generation
|
| 100 |
+
- Use **`nota-ai/bk-sdm-small`** — it is specifically distilled for speed
|
| 101 |
+
- Keep images at **512×512** (larger = much slower on SD v1.x)
|
| 102 |
+
- Use **20 steps with DPM++** (better than 50 steps with PNDM)
|
| 103 |
+
- Set `CPU_THREADS=0` in `.env` to use all logical cores
|
| 104 |
+
- Avoid running other CPU-heavy workloads during generation
|
| 105 |
+
|
| 106 |
+
---
|
| 107 |
+
|
| 108 |
+
## API Reference
|
| 109 |
+
|
| 110 |
+
### Submit a generation job
|
| 111 |
+
|
| 112 |
+
```
|
| 113 |
+
POST /generate
|
| 114 |
+
```
|
| 115 |
+
|
| 116 |
+
**Request body:**
|
| 117 |
+
```json
|
| 118 |
+
{
|
| 119 |
+
"prompt": "a photorealistic mountain landscape at golden hour",
|
| 120 |
+
"negative_prompt": "blurry, low quality, watermark",
|
| 121 |
+
"width": 512,
|
| 122 |
+
"height": 512,
|
| 123 |
+
"num_inference_steps": 20,
|
| 124 |
+
"guidance_scale": 7.5,
|
| 125 |
+
"seed": -1,
|
| 126 |
+
"scheduler": "dpm++"
|
| 127 |
+
}
|
| 128 |
+
```
|
| 129 |
+
|
| 130 |
+
**Schedulers:** `dpm++` (best), `euler_a`, `euler`, `pndm`
|
| 131 |
+
|
| 132 |
+
**Response `202 Accepted`:**
|
| 133 |
+
```json
|
| 134 |
+
{
|
| 135 |
+
"job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
|
| 136 |
+
"status": "queued",
|
| 137 |
+
"created_at": "2024-06-01T12:00:00Z",
|
| 138 |
+
"queue_position": 1,
|
| 139 |
+
"message": "Job is next in queue and will start immediately."
|
| 140 |
+
}
|
| 141 |
+
```
|
| 142 |
+
|
| 143 |
+
---
|
| 144 |
+
|
| 145 |
+
### Check job status
|
| 146 |
+
|
| 147 |
+
```
|
| 148 |
+
GET /jobs/{job_id}
|
| 149 |
+
```
|
| 150 |
+
|
| 151 |
+
**While processing:**
|
| 152 |
+
```json
|
| 153 |
+
{
|
| 154 |
+
"job_id": "3fa85f64-...",
|
| 155 |
+
"status": "processing",
|
| 156 |
+
"progress": 45,
|
| 157 |
+
"current_step": 9,
|
| 158 |
+
"total_steps": 20,
|
| 159 |
+
"started_at": "2024-06-01T12:00:01Z"
|
| 160 |
+
}
|
| 161 |
+
```
|
| 162 |
+
|
| 163 |
+
**When completed:**
|
| 164 |
+
```json
|
| 165 |
+
{
|
| 166 |
+
"job_id": "3fa85f64-...",
|
| 167 |
+
"status": "completed",
|
| 168 |
+
"progress": 100,
|
| 169 |
+
"download_url": "/jobs/3fa85f64-.../download",
|
| 170 |
+
"image_filename": "20240601_120045_3fa85f64_42.png",
|
| 171 |
+
"duration_seconds": 87.3,
|
| 172 |
+
"completed_at": "2024-06-01T12:01:28Z"
|
| 173 |
+
}
|
| 174 |
+
```
|
| 175 |
+
|
| 176 |
+
---
|
| 177 |
+
|
| 178 |
+
### Download the image
|
| 179 |
+
|
| 180 |
+
```
|
| 181 |
+
GET /jobs/{job_id}/download
|
| 182 |
+
```
|
| 183 |
+
|
| 184 |
+
Returns the PNG as a file attachment. Returns `202` if still processing.
|
| 185 |
+
|
| 186 |
---
|
| 187 |
+
|
| 188 |
+
### Delete a job and its image
|
| 189 |
+
|
| 190 |
+
```
|
| 191 |
+
DELETE /jobs/{job_id}
|
| 192 |
+
```
|
| 193 |
+
|
| 194 |
+
Removes the job record and deletes the PNG from disk.
|
| 195 |
+
|
| 196 |
+
```json
|
| 197 |
+
{
|
| 198 |
+
"ok": true,
|
| 199 |
+
"job_id": "3fa85f64-...",
|
| 200 |
+
"image_deleted": true,
|
| 201 |
+
"message": "Job deleted. Image file removed from disk."
|
| 202 |
+
}
|
| 203 |
+
```
|
| 204 |
+
|
| 205 |
---
|
| 206 |
|
| 207 |
+
### List all jobs
|
| 208 |
+
|
| 209 |
+
```
|
| 210 |
+
GET /jobs?status=completed&limit=50&offset=0
|
| 211 |
+
```
|
| 212 |
+
|
| 213 |
+
Status filter options: `queued`, `processing`, `completed`, `failed`
|
| 214 |
+
|
| 215 |
+
---
|
| 216 |
+
|
| 217 |
+
### Health check
|
| 218 |
+
|
| 219 |
+
```
|
| 220 |
+
GET /health
|
| 221 |
+
```
|
| 222 |
+
|
| 223 |
+
```json
|
| 224 |
+
{
|
| 225 |
+
"status": "ok",
|
| 226 |
+
"model_id": "nota-ai/bk-sdm-small",
|
| 227 |
+
"pipeline_loaded": true,
|
| 228 |
+
"loading": false,
|
| 229 |
+
"queue_size": 2,
|
| 230 |
+
"jobs_total": 15,
|
| 231 |
+
"jobs_by_status": {
|
| 232 |
+
"queued": 2,
|
| 233 |
+
"processing": 1,
|
| 234 |
+
"completed": 11,
|
| 235 |
+
"failed": 1
|
| 236 |
+
},
|
| 237 |
+
"cpu_threads": 8
|
| 238 |
+
}
|
| 239 |
+
```
|
| 240 |
+
|
| 241 |
+
---
|
| 242 |
+
|
| 243 |
+
### Hot-swap model
|
| 244 |
+
|
| 245 |
+
```
|
| 246 |
+
POST /models/load
|
| 247 |
+
Content-Type: application/json
|
| 248 |
+
|
| 249 |
+
{ "model_id": "runwayml/stable-diffusion-v1-5" }
|
| 250 |
+
```
|
| 251 |
+
|
| 252 |
+
Loads the new model in the background. Poll `GET /health` to confirm `pipeline_loaded: true`.
|
| 253 |
+
|
| 254 |
+
---
|
| 255 |
+
|
| 256 |
+
## Example: Full workflow with curl
|
| 257 |
+
|
| 258 |
+
```bash
|
| 259 |
+
# 1. Check service is ready
|
| 260 |
+
curl http://localhost:8000/health | jq .pipeline_loaded
|
| 261 |
+
|
| 262 |
+
# 2. Submit a generation job
|
| 263 |
+
JOB=$(curl -s -X POST http://localhost:8000/generate \
|
| 264 |
+
-H "Content-Type: application/json" \
|
| 265 |
+
-d '{
|
| 266 |
+
"prompt": "a serene Japanese garden with koi pond, watercolor style",
|
| 267 |
+
"negative_prompt": "low quality, blurry, cartoon",
|
| 268 |
+
"width": 512,
|
| 269 |
+
"height": 512,
|
| 270 |
+
"num_inference_steps": 20,
|
| 271 |
+
"guidance_scale": 7.5,
|
| 272 |
+
"seed": 42,
|
| 273 |
+
"scheduler": "dpm++"
|
| 274 |
+
}')
|
| 275 |
+
echo $JOB | jq .
|
| 276 |
+
|
| 277 |
+
JOB_ID=$(echo $JOB | jq -r .job_id)
|
| 278 |
+
|
| 279 |
+
# 3. Poll until completed
|
| 280 |
+
while true; do
|
| 281 |
+
STATUS=$(curl -s http://localhost:8000/jobs/$JOB_ID | jq -r .status)
|
| 282 |
+
PROGRESS=$(curl -s http://localhost:8000/jobs/$JOB_ID | jq -r .progress)
|
| 283 |
+
echo "Status: $STATUS Progress: $PROGRESS%"
|
| 284 |
+
[ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
|
| 285 |
+
sleep 5
|
| 286 |
+
done
|
| 287 |
+
|
| 288 |
+
# 4. Download the image
|
| 289 |
+
curl -s http://localhost:8000/jobs/$JOB_ID/download -o output.png
|
| 290 |
+
echo "Saved to output.png"
|
| 291 |
+
|
| 292 |
+
# 5. Delete the job + image
|
| 293 |
+
curl -s -X DELETE http://localhost:8000/jobs/$JOB_ID | jq .
|
| 294 |
+
```
|
| 295 |
+
|
| 296 |
+
---
|
| 297 |
+
|
| 298 |
+
## Configuration (`.env`)
|
| 299 |
+
|
| 300 |
+
| Variable | Default | Description |
|
| 301 |
+
|---|---|---|
|
| 302 |
+
| `MODEL_ID` | `nota-ai/bk-sdm-small` | Hugging Face model repo ID |
|
| 303 |
+
| `MODEL_CACHE_DIR` | `./model_cache` | Where weights are cached |
|
| 304 |
+
| `AUTO_LOAD_MODEL` | `true` | Load model at startup |
|
| 305 |
+
| `CPU_THREADS` | `0` (all cores) | PyTorch thread count |
|
| 306 |
+
| `ENABLE_ATTENTION_SLICING` | `true` | Lower peak RAM usage |
|
| 307 |
+
| `DEFAULT_STEPS` | `20` | Default inference steps |
|
| 308 |
+
| `MAX_STEPS` | `50` | Request cap |
|
| 309 |
+
| `DEFAULT_WIDTH/HEIGHT` | `512` | Default image dimensions |
|
| 310 |
+
| `MAX_WIDTH/HEIGHT` | `768` | Request cap |
|
| 311 |
+
| `OUTPUTS_DIR` | `./outputs` | Where PNGs are saved |
|
| 312 |
+
| `PORT` | `8000` | HTTP port |
|
| 313 |
+
| `DEBUG` | `false` | Verbose logging + auto-reload |
|
| 314 |
+
|
| 315 |
+
---
|
| 316 |
+
|
| 317 |
+
## File Structure
|
| 318 |
+
|
| 319 |
+
```
|
| 320 |
+
hf-image-api/
|
| 321 |
+
├── main.py # FastAPI app + lifespan (startup/shutdown)
|
| 322 |
+
├── config.py # Settings from environment / .env
|
| 323 |
+
├── schemas.py # All Pydantic request & response models
|
| 324 |
+
├── job_store.py # Thread-safe in-memory job registry
|
| 325 |
+
├── pipeline_manager.py # HuggingFace Diffusers pipeline (CPU-tuned)
|
| 326 |
+
├── worker.py # Background worker thread + FIFO job queue
|
| 327 |
+
├── routes/
|
| 328 |
+
│ ├── generate.py # POST /generate
|
| 329 |
+
│ ├── jobs.py # GET/DELETE /jobs and /jobs/{id}/download
|
| 330 |
+
│ └── health.py # GET /health, GET /models, POST /models/load
|
| 331 |
+
├── outputs/ # Generated PNG files (auto-created)
|
| 332 |
+
├── model_cache/ # HuggingFace model weights cache (auto-created)
|
| 333 |
+
├── requirements.txt
|
| 334 |
+
├── .env.example
|
| 335 |
+
├── start.sh
|
| 336 |
+
└── README.md
|
| 337 |
+
```
|
| 338 |
+
|
| 339 |
+
---
|
| 340 |
+
|
| 341 |
+
## License
|
| 342 |
+
|
| 343 |
+
MIT — free to use and modify.
|
config.py
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
config.py — All runtime settings loaded from environment / .env file.
|
| 3 |
+
"""
|
| 4 |
+
from pydantic_settings import BaseSettings
|
| 5 |
+
from pydantic import Field
|
| 6 |
+
import os
|
| 7 |
+
|
| 8 |
+
|
| 9 |
+
class Settings(BaseSettings):
|
| 10 |
+
# ── Server ────────────────────────────────────────────────────────────────
|
| 11 |
+
host: str = Field("0.0.0.0", env="HOST")
|
| 12 |
+
port: int = Field(8000, env="PORT")
|
| 13 |
+
debug: bool = Field(False, env="DEBUG")
|
| 14 |
+
|
| 15 |
+
# ── Model ─────────────────────────────────────────────────────────────────
|
| 16 |
+
# Best CPU models (small → fast):
|
| 17 |
+
# "nota-ai/bk-sdm-small" (~500 MB, very fast on CPU)
|
| 18 |
+
# "runwayml/stable-diffusion-v1-5" (~4 GB, standard quality)
|
| 19 |
+
# "stabilityai/stable-diffusion-2-1-base" (~5 GB, higher quality)
|
| 20 |
+
model_id: str = Field(
|
| 21 |
+
"nota-ai/bk-sdm-small",
|
| 22 |
+
env="MODEL_ID",
|
| 23 |
+
)
|
| 24 |
+
model_cache_dir: str = Field("./model_cache", env="MODEL_CACHE_DIR")
|
| 25 |
+
|
| 26 |
+
# Load the pipeline at startup (recommended — avoids cold-start on first job)
|
| 27 |
+
auto_load_model: bool = Field(True, env="AUTO_LOAD_MODEL")
|
| 28 |
+
|
| 29 |
+
# ── CPU Optimisation ──────────────────────────────────────────────────────
|
| 30 |
+
# Number of CPU threads for PyTorch inference (0 = use all logical cores)
|
| 31 |
+
cpu_threads: int = Field(0, env="CPU_THREADS")
|
| 32 |
+
|
| 33 |
+
# Enable attention slicing (reduces peak RAM at slight speed cost)
|
| 34 |
+
enable_attention_slicing: bool = Field(True, env="ENABLE_ATTENTION_SLICING")
|
| 35 |
+
|
| 36 |
+
# Default inference steps (DPM++ scheduler works well at 20 steps on CPU)
|
| 37 |
+
default_steps: int = Field(20, env="DEFAULT_STEPS")
|
| 38 |
+
max_steps: int = Field(50, env="MAX_STEPS")
|
| 39 |
+
|
| 40 |
+
# Default image dimensions (512×512 is ideal for SD v1.x on CPU)
|
| 41 |
+
default_width: int = Field(512, env="DEFAULT_WIDTH")
|
| 42 |
+
default_height: int = Field(512, env="DEFAULT_HEIGHT")
|
| 43 |
+
max_width: int = Field(768, env="MAX_WIDTH")
|
| 44 |
+
max_height: int = Field(768, env="MAX_HEIGHT")
|
| 45 |
+
|
| 46 |
+
# Default guidance scale
|
| 47 |
+
default_guidance_scale: float = Field(7.5, env="DEFAULT_GUIDANCE_SCALE")
|
| 48 |
+
|
| 49 |
+
# ── Storage ───────────────────────────────────────────────────────────────
|
| 50 |
+
outputs_dir: str = Field("./outputs", env="OUTPUTS_DIR")
|
| 51 |
+
|
| 52 |
+
# Auto-delete completed jobs after N seconds (0 = never)
|
| 53 |
+
job_ttl_seconds: int = Field(0, env="JOB_TTL_SECONDS")
|
| 54 |
+
|
| 55 |
+
class Config:
|
| 56 |
+
env_file = ".env"
|
| 57 |
+
env_file_encoding = "utf-8"
|
| 58 |
+
|
| 59 |
+
|
| 60 |
+
settings = Settings()
|
| 61 |
+
|
| 62 |
+
# Resolve absolute output path
|
| 63 |
+
os.makedirs(settings.outputs_dir, exist_ok=True)
|
| 64 |
+
os.makedirs(settings.model_cache_dir, exist_ok=True)
|
job_store.py
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
job_store.py — Thread-safe in-memory store for generation jobs.
|
| 3 |
+
|
| 4 |
+
Uses a plain threading.Lock so it is safe to call from both the FastAPI
|
| 5 |
+
async event-loop (via run_in_executor) and from the background worker thread.
|
| 6 |
+
"""
|
| 7 |
+
from __future__ import annotations
|
| 8 |
+
|
| 9 |
+
import threading
|
| 10 |
+
import uuid
|
| 11 |
+
from datetime import datetime, timezone
|
| 12 |
+
from typing import Dict, List, Optional
|
| 13 |
+
|
| 14 |
+
from schemas import Job, JobStatus
|
| 15 |
+
|
| 16 |
+
|
| 17 |
+
class JobStore:
|
| 18 |
+
"""Central store for all generation jobs."""
|
| 19 |
+
|
| 20 |
+
def __init__(self) -> None:
|
| 21 |
+
self._jobs: Dict[str, Job] = {}
|
| 22 |
+
self._lock = threading.Lock()
|
| 23 |
+
|
| 24 |
+
# ── Write operations ───────────────────────────────────────────────────────
|
| 25 |
+
|
| 26 |
+
def create(
|
| 27 |
+
self,
|
| 28 |
+
prompt: str,
|
| 29 |
+
negative_prompt: str,
|
| 30 |
+
params: dict,
|
| 31 |
+
model_id: Optional[str] = None,
|
| 32 |
+
) -> Job:
|
| 33 |
+
job_id = str(uuid.uuid4())
|
| 34 |
+
job = Job(
|
| 35 |
+
job_id=job_id,
|
| 36 |
+
status=JobStatus.QUEUED,
|
| 37 |
+
prompt=prompt,
|
| 38 |
+
negative_prompt=negative_prompt,
|
| 39 |
+
params=params,
|
| 40 |
+
created_at=datetime.now(timezone.utc),
|
| 41 |
+
total_steps=params.get("num_inference_steps", 20),
|
| 42 |
+
model_id=model_id,
|
| 43 |
+
)
|
| 44 |
+
with self._lock:
|
| 45 |
+
self._jobs[job_id] = job
|
| 46 |
+
return job
|
| 47 |
+
|
| 48 |
+
def update(self, job_id: str, **kwargs) -> Optional[Job]:
|
| 49 |
+
with self._lock:
|
| 50 |
+
job = self._jobs.get(job_id)
|
| 51 |
+
if not job:
|
| 52 |
+
return None
|
| 53 |
+
for key, val in kwargs.items():
|
| 54 |
+
if hasattr(job, key):
|
| 55 |
+
setattr(job, key, val)
|
| 56 |
+
return job
|
| 57 |
+
|
| 58 |
+
def delete(self, job_id: str) -> Optional[Job]:
|
| 59 |
+
with self._lock:
|
| 60 |
+
return self._jobs.pop(job_id, None)
|
| 61 |
+
|
| 62 |
+
# ── Read operations ────────────────────────────────────────────────────────
|
| 63 |
+
|
| 64 |
+
def get(self, job_id: str) -> Optional[Job]:
|
| 65 |
+
with self._lock:
|
| 66 |
+
return self._jobs.get(job_id)
|
| 67 |
+
|
| 68 |
+
def list_all(
|
| 69 |
+
self,
|
| 70 |
+
status_filter: Optional[JobStatus] = None,
|
| 71 |
+
limit: int = 100,
|
| 72 |
+
offset: int = 0,
|
| 73 |
+
) -> List[Job]:
|
| 74 |
+
with self._lock:
|
| 75 |
+
jobs = list(self._jobs.values())
|
| 76 |
+
|
| 77 |
+
# Apply optional status filter
|
| 78 |
+
if status_filter is not None:
|
| 79 |
+
jobs = [j for j in jobs if j.status == status_filter]
|
| 80 |
+
|
| 81 |
+
# Sort newest first
|
| 82 |
+
jobs.sort(key=lambda j: j.created_at, reverse=True)
|
| 83 |
+
return jobs[offset : offset + limit]
|
| 84 |
+
|
| 85 |
+
def counts_by_status(self) -> Dict[str, int]:
|
| 86 |
+
with self._lock:
|
| 87 |
+
result: Dict[str, int] = {s.value: 0 for s in JobStatus}
|
| 88 |
+
for job in self._jobs.values():
|
| 89 |
+
result[job.status.value] += 1
|
| 90 |
+
return result
|
| 91 |
+
|
| 92 |
+
@property
|
| 93 |
+
def total(self) -> int:
|
| 94 |
+
with self._lock:
|
| 95 |
+
return len(self._jobs)
|
| 96 |
+
|
| 97 |
+
|
| 98 |
+
# Singleton used throughout the application
|
| 99 |
+
job_store = JobStore()
|
main.py
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
main.py — FastAPI application entry point.
|
| 3 |
+
|
| 4 |
+
Startup sequence
|
| 5 |
+
────────────────
|
| 6 |
+
1. Worker thread is started (daemon thread — auto-stops with the process).
|
| 7 |
+
2. If AUTO_LOAD_MODEL=true, the HuggingFace pipeline is loaded in the
|
| 8 |
+
background so the first job doesn't include cold-start download time.
|
| 9 |
+
3. The HTTP server starts accepting requests.
|
| 10 |
+
|
| 11 |
+
Run with:
|
| 12 |
+
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
| 13 |
+
"""
|
| 14 |
+
from __future__ import annotations
|
| 15 |
+
|
| 16 |
+
import logging
|
| 17 |
+
import os
|
| 18 |
+
import threading
|
| 19 |
+
from contextlib import asynccontextmanager
|
| 20 |
+
|
| 21 |
+
import uvicorn
|
| 22 |
+
from fastapi import FastAPI, Request
|
| 23 |
+
from fastapi.middleware.cors import CORSMiddleware
|
| 24 |
+
from fastapi.responses import JSONResponse
|
| 25 |
+
|
| 26 |
+
from config import settings
|
| 27 |
+
from routes import generate, health, jobs
|
| 28 |
+
from worker import start_worker
|
| 29 |
+
|
| 30 |
+
# ── Logging ───────────────────────────────────────────────────────────────────
|
| 31 |
+
logging.basicConfig(
|
| 32 |
+
level=logging.DEBUG if settings.debug else logging.INFO,
|
| 33 |
+
format="%(asctime)s %(levelname)-8s %(name)s %(message)s",
|
| 34 |
+
datefmt="%H:%M:%S",
|
| 35 |
+
)
|
| 36 |
+
logger = logging.getLogger("main")
|
| 37 |
+
|
| 38 |
+
|
| 39 |
+
# ── Lifespan (startup / shutdown) ─────────────────────────────────────────────
|
| 40 |
+
|
| 41 |
+
@asynccontextmanager
|
| 42 |
+
async def lifespan(app: FastAPI):
|
| 43 |
+
logger.info("═" * 60)
|
| 44 |
+
logger.info(" HF Image Generation API — starting up")
|
| 45 |
+
logger.info(" Model ID : %s", settings.model_id)
|
| 46 |
+
logger.info(" Outputs dir: %s", settings.outputs_dir)
|
| 47 |
+
logger.info(" CPU threads: %s", settings.cpu_threads or os.cpu_count())
|
| 48 |
+
logger.info("═" * 60)
|
| 49 |
+
|
| 50 |
+
# 1. Start background worker thread
|
| 51 |
+
start_worker()
|
| 52 |
+
logger.info("Background worker started.")
|
| 53 |
+
|
| 54 |
+
# 2. Optionally pre-load the pipeline
|
| 55 |
+
if settings.auto_load_model:
|
| 56 |
+
def _preload():
|
| 57 |
+
from pipeline_manager import pipeline_mgr
|
| 58 |
+
try:
|
| 59 |
+
pipeline_mgr.load()
|
| 60 |
+
except Exception as exc:
|
| 61 |
+
logger.exception("Pre-load failed: %s", exc)
|
| 62 |
+
|
| 63 |
+
t = threading.Thread(target=_preload, name="preload", daemon=True)
|
| 64 |
+
t.start()
|
| 65 |
+
logger.info("Pipeline pre-load started in background (AUTO_LOAD_MODEL=true).")
|
| 66 |
+
else:
|
| 67 |
+
logger.info("AUTO_LOAD_MODEL=false — pipeline will load on first job.")
|
| 68 |
+
|
| 69 |
+
yield # ← application runs here
|
| 70 |
+
|
| 71 |
+
logger.info("Shutting down.")
|
| 72 |
+
|
| 73 |
+
|
| 74 |
+
# ── App ───────────────────────────────────────────────────────────────────────
|
| 75 |
+
|
| 76 |
+
app = FastAPI(
|
| 77 |
+
title="HF CPU Image Generation API",
|
| 78 |
+
description=(
|
| 79 |
+
"Job-based REST API for Stable Diffusion image generation on CPU "
|
| 80 |
+
"using Hugging Face Diffusers. "
|
| 81 |
+
"Submit a job → poll status → download image → optionally delete."
|
| 82 |
+
),
|
| 83 |
+
version="1.0.0",
|
| 84 |
+
lifespan=lifespan,
|
| 85 |
+
docs_url="/docs",
|
| 86 |
+
redoc_url="/redoc",
|
| 87 |
+
)
|
| 88 |
+
|
| 89 |
+
# CORS — allow everything by default (restrict in production)
|
| 90 |
+
app.add_middleware(
|
| 91 |
+
CORSMiddleware,
|
| 92 |
+
allow_origins=["*"],
|
| 93 |
+
allow_credentials=True,
|
| 94 |
+
allow_methods=["*"],
|
| 95 |
+
allow_headers=["*"],
|
| 96 |
+
)
|
| 97 |
+
|
| 98 |
+
# ── Global exception handler ───────────────────────────────────────────────────
|
| 99 |
+
|
| 100 |
+
@app.exception_handler(Exception)
|
| 101 |
+
async def global_exception_handler(request: Request, exc: Exception):
|
| 102 |
+
logger.exception("Unhandled error on %s %s: %s", request.method, request.url.path, exc)
|
| 103 |
+
return JSONResponse(
|
| 104 |
+
status_code=500,
|
| 105 |
+
content={"detail": "An internal server error occurred.", "error": str(exc)},
|
| 106 |
+
)
|
| 107 |
+
|
| 108 |
+
# ── Root redirect to docs ──────────────────────────────────────────────────────
|
| 109 |
+
|
| 110 |
+
@app.get("/", include_in_schema=False)
|
| 111 |
+
async def root():
|
| 112 |
+
from fastapi.responses import RedirectResponse
|
| 113 |
+
return RedirectResponse(url="/docs")
|
| 114 |
+
|
| 115 |
+
# ── Mount routers ──────────────────────────────────────────────────────────────
|
| 116 |
+
|
| 117 |
+
app.include_router(health.router)
|
| 118 |
+
app.include_router(generate.router)
|
| 119 |
+
app.include_router(jobs.router)
|
| 120 |
+
|
| 121 |
+
|
| 122 |
+
# ── Dev entrypoint ─────────────────────────────────────────────────────────────
|
| 123 |
+
|
| 124 |
+
if __name__ == "__main__":
|
| 125 |
+
uvicorn.run(
|
| 126 |
+
"main:app",
|
| 127 |
+
host=settings.host,
|
| 128 |
+
port=settings.port,
|
| 129 |
+
reload=settings.debug,
|
| 130 |
+
log_level="debug" if settings.debug else "info",
|
| 131 |
+
)
|
pipeline_manager.py
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
pipeline_manager.py — Singleton that owns the Diffusers pipeline.
|
| 3 |
+
|
| 4 |
+
CPU optimisations applied:
|
| 5 |
+
• torch.float32 (float16 is GPU-only and causes NaN on CPU)
|
| 6 |
+
• enable_attention_slicing() — lower peak RAM usage
|
| 7 |
+
• DPMSolverMultistepScheduler — fast convergence in 15-20 steps
|
| 8 |
+
• torch.set_num_threads() — saturate all logical cores
|
| 9 |
+
• low_cpu_mem_usage=True — stream weights into RAM, don't double-buffer
|
| 10 |
+
• safety_checker=None — skip the NSFW binary classifier (saves ~300 MB RAM)
|
| 11 |
+
|
| 12 |
+
Loading is thread-safe; only one thread can load at a time.
|
| 13 |
+
"""
|
| 14 |
+
from __future__ import annotations
|
| 15 |
+
|
| 16 |
+
import logging
|
| 17 |
+
import os
|
| 18 |
+
import threading
|
| 19 |
+
from typing import Callable, Optional, Tuple
|
| 20 |
+
|
| 21 |
+
logger = logging.getLogger("pipeline_manager")
|
| 22 |
+
|
| 23 |
+
|
| 24 |
+
class PipelineManager:
|
| 25 |
+
|
| 26 |
+
def __init__(self) -> None:
|
| 27 |
+
self._pipe = None
|
| 28 |
+
self._model_id: Optional[str] = None
|
| 29 |
+
self._loading = False
|
| 30 |
+
self._lock = threading.Lock()
|
| 31 |
+
|
| 32 |
+
# ── Public API ─────────────────────────────────────────────────────────────
|
| 33 |
+
|
| 34 |
+
@property
|
| 35 |
+
def is_loaded(self) -> bool:
|
| 36 |
+
return self._pipe is not None
|
| 37 |
+
|
| 38 |
+
@property
|
| 39 |
+
def is_loading(self) -> bool:
|
| 40 |
+
return self._loading
|
| 41 |
+
|
| 42 |
+
@property
|
| 43 |
+
def current_model_id(self) -> Optional[str]:
|
| 44 |
+
return self._model_id
|
| 45 |
+
|
| 46 |
+
def load(self, model_id: Optional[str] = None) -> None:
|
| 47 |
+
"""Load (or hot-swap) the pipeline. Blocks the calling thread until done."""
|
| 48 |
+
from config import settings
|
| 49 |
+
import torch
|
| 50 |
+
from diffusers import (
|
| 51 |
+
StableDiffusionPipeline,
|
| 52 |
+
DPMSolverMultistepScheduler,
|
| 53 |
+
)
|
| 54 |
+
|
| 55 |
+
target_model = model_id or settings.model_id
|
| 56 |
+
|
| 57 |
+
with self._lock:
|
| 58 |
+
if self._loading:
|
| 59 |
+
logger.warning("Pipeline is already loading — skipping duplicate load request.")
|
| 60 |
+
return
|
| 61 |
+
self._loading = True
|
| 62 |
+
|
| 63 |
+
try:
|
| 64 |
+
logger.info("Loading pipeline: %s", target_model)
|
| 65 |
+
|
| 66 |
+
# ── CPU thread tuning ──────────────────────────────────────────────
|
| 67 |
+
n_threads = settings.cpu_threads or os.cpu_count() or 4
|
| 68 |
+
torch.set_num_threads(n_threads)
|
| 69 |
+
logger.info("PyTorch CPU threads set to %d", n_threads)
|
| 70 |
+
|
| 71 |
+
# ── Load the pipeline ──────────────────────────────────────────────
|
| 72 |
+
pipe = StableDiffusionPipeline.from_pretrained(
|
| 73 |
+
target_model,
|
| 74 |
+
torch_dtype=torch.float32, # mandatory for CPU
|
| 75 |
+
low_cpu_mem_usage=True, # stream tensors, avoid double RAM
|
| 76 |
+
safety_checker=None, # skip NSFW checker (~300 MB RAM saved)
|
| 77 |
+
requires_safety_checker=False,
|
| 78 |
+
cache_dir=settings.model_cache_dir,
|
| 79 |
+
)
|
| 80 |
+
|
| 81 |
+
# ── Move to CPU explicitly ─────────────────────────────────────────
|
| 82 |
+
pipe = pipe.to("cpu")
|
| 83 |
+
|
| 84 |
+
# ── Swap scheduler: DPM++ 2M — best quality/speed on CPU ──────────
|
| 85 |
+
pipe.scheduler = DPMSolverMultistepScheduler.from_config(
|
| 86 |
+
pipe.scheduler.config,
|
| 87 |
+
use_karras_sigmas=True, # smoother sampling curve
|
| 88 |
+
)
|
| 89 |
+
|
| 90 |
+
# ── Memory optimisations ───────────────────────────────────────────
|
| 91 |
+
if settings.enable_attention_slicing:
|
| 92 |
+
pipe.enable_attention_slicing(slice_size=1)
|
| 93 |
+
|
| 94 |
+
# ── Optional: torch.compile (PyTorch ≥ 2.0 only) ─────────────────
|
| 95 |
+
# Disabled by default: first-run compilation takes minutes on CPU
|
| 96 |
+
# and saves ~5-10 % on subsequent calls. Enable manually if needed:
|
| 97 |
+
# pipe.unet = torch.compile(pipe.unet, backend="inductor")
|
| 98 |
+
|
| 99 |
+
with self._lock:
|
| 100 |
+
self._pipe = pipe
|
| 101 |
+
self._model_id = target_model
|
| 102 |
+
self._loading = False
|
| 103 |
+
|
| 104 |
+
logger.info("Pipeline ready: %s", target_model)
|
| 105 |
+
|
| 106 |
+
except Exception as exc:
|
| 107 |
+
with self._lock:
|
| 108 |
+
self._loading = False
|
| 109 |
+
logger.exception("Failed to load pipeline: %s", exc)
|
| 110 |
+
raise
|
| 111 |
+
|
| 112 |
+
def generate(
|
| 113 |
+
self,
|
| 114 |
+
prompt: str,
|
| 115 |
+
negative_prompt: str,
|
| 116 |
+
width: int,
|
| 117 |
+
height: int,
|
| 118 |
+
num_inference_steps: int,
|
| 119 |
+
guidance_scale: float,
|
| 120 |
+
seed: int,
|
| 121 |
+
scheduler_name: str,
|
| 122 |
+
step_callback: Optional[Callable] = None,
|
| 123 |
+
) -> Tuple["PIL.Image.Image", int]:
|
| 124 |
+
"""
|
| 125 |
+
Run inference and return (PIL image, seed_used).
|
| 126 |
+
Blocks the calling thread — always call from the worker thread.
|
| 127 |
+
"""
|
| 128 |
+
import torch
|
| 129 |
+
from diffusers import (
|
| 130 |
+
DPMSolverMultistepScheduler,
|
| 131 |
+
EulerAncestralDiscreteScheduler,
|
| 132 |
+
EulerDiscreteScheduler,
|
| 133 |
+
PNDMScheduler,
|
| 134 |
+
)
|
| 135 |
+
|
| 136 |
+
if not self._pipe:
|
| 137 |
+
raise RuntimeError("Pipeline is not loaded. Call load() first.")
|
| 138 |
+
|
| 139 |
+
pipe = self._pipe
|
| 140 |
+
|
| 141 |
+
# ── Swap scheduler if requested ────────────────────────────────────────
|
| 142 |
+
scheduler_map = {
|
| 143 |
+
"dpm++": DPMSolverMultistepScheduler,
|
| 144 |
+
"euler_a": EulerAncestralDiscreteScheduler,
|
| 145 |
+
"euler": EulerDiscreteScheduler,
|
| 146 |
+
"pndm": PNDMScheduler,
|
| 147 |
+
}
|
| 148 |
+
SchedulerClass = scheduler_map.get(scheduler_name, DPMSolverMultistepScheduler)
|
| 149 |
+
pipe.scheduler = SchedulerClass.from_config(pipe.scheduler.config)
|
| 150 |
+
|
| 151 |
+
# ── Seed handling ──────────────────────────────────────────────────────
|
| 152 |
+
import random
|
| 153 |
+
used_seed = seed if seed != -1 else random.randint(0, 2**32 - 1)
|
| 154 |
+
generator = torch.Generator(device="cpu").manual_seed(used_seed)
|
| 155 |
+
|
| 156 |
+
# ── Step progress callback ─────────────────────────────────────────────
|
| 157 |
+
# Build a callback compatible with both old and new diffusers APIs
|
| 158 |
+
total_steps = num_inference_steps
|
| 159 |
+
|
| 160 |
+
def _legacy_callback(step: int, timestep, latents):
|
| 161 |
+
if step_callback:
|
| 162 |
+
step_callback(step + 1, total_steps)
|
| 163 |
+
|
| 164 |
+
def _new_callback(pipeline, step: int, timestep, callback_kwargs: dict):
|
| 165 |
+
if step_callback:
|
| 166 |
+
step_callback(step + 1, total_steps)
|
| 167 |
+
return callback_kwargs
|
| 168 |
+
|
| 169 |
+
import diffusers
|
| 170 |
+
diffusers_version = tuple(int(x) for x in diffusers.__version__.split(".")[:2])
|
| 171 |
+
|
| 172 |
+
call_kwargs = dict(
|
| 173 |
+
prompt=prompt,
|
| 174 |
+
negative_prompt=negative_prompt,
|
| 175 |
+
width=width,
|
| 176 |
+
height=height,
|
| 177 |
+
num_inference_steps=num_inference_steps,
|
| 178 |
+
guidance_scale=guidance_scale,
|
| 179 |
+
generator=generator,
|
| 180 |
+
)
|
| 181 |
+
|
| 182 |
+
if diffusers_version >= (0, 25):
|
| 183 |
+
# New API: callback_on_step_end
|
| 184 |
+
call_kwargs["callback_on_step_end"] = _new_callback
|
| 185 |
+
else:
|
| 186 |
+
# Legacy API
|
| 187 |
+
call_kwargs["callback"] = _legacy_callback
|
| 188 |
+
call_kwargs["callback_steps"] = 1
|
| 189 |
+
|
| 190 |
+
# ── Run inference ──────────────────────────────────────────────────────
|
| 191 |
+
with torch.inference_mode():
|
| 192 |
+
result = pipe(**call_kwargs)
|
| 193 |
+
|
| 194 |
+
image = result.images[0]
|
| 195 |
+
return image, used_seed
|
| 196 |
+
|
| 197 |
+
|
| 198 |
+
# Singleton used throughout the application
|
| 199 |
+
pipeline_mgr = PipelineManager()
|
requirements.txt
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Core API
|
| 2 |
+
fastapi>=0.111.0
|
| 3 |
+
uvicorn[standard]>=0.29.0
|
| 4 |
+
python-multipart>=0.0.9
|
| 5 |
+
|
| 6 |
+
# Hugging Face / Diffusers (CPU-optimised)
|
| 7 |
+
diffusers>=0.27.0
|
| 8 |
+
transformers>=4.40.0
|
| 9 |
+
accelerate>=0.30.0
|
| 10 |
+
safetensors>=0.4.3
|
| 11 |
+
|
| 12 |
+
# PyTorch CPU-only (install via pip before running this file — see README)
|
| 13 |
+
# pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
|
| 14 |
+
|
| 15 |
+
# Utilities
|
| 16 |
+
Pillow>=10.3.0
|
| 17 |
+
python-dotenv>=1.0.1
|
| 18 |
+
pydantic>=2.7.0
|
| 19 |
+
pydantic-settings>=2.2.1
|
| 20 |
+
aiofiles>=23.2.1
|
routes/__init__.py
ADDED
|
File without changes
|
routes/generate.py
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
routes/generate.py — Image generation job submission.
|
| 3 |
+
|
| 4 |
+
POST /generate
|
| 5 |
+
→ Validates the request, creates a queued job, enqueues it for the
|
| 6 |
+
background worker, and immediately returns the job_id.
|
| 7 |
+
The caller then polls GET /jobs/{job_id} for progress/status.
|
| 8 |
+
"""
|
| 9 |
+
from __future__ import annotations
|
| 10 |
+
|
| 11 |
+
import logging
|
| 12 |
+
|
| 13 |
+
from fastapi import APIRouter, HTTPException
|
| 14 |
+
|
| 15 |
+
from config import settings
|
| 16 |
+
from job_store import job_store
|
| 17 |
+
from pipeline_manager import pipeline_mgr
|
| 18 |
+
from schemas import GenerateRequest, JobSubmittedResponse, JobStatus
|
| 19 |
+
from worker import enqueue, queue_position, queue_size
|
| 20 |
+
|
| 21 |
+
logger = logging.getLogger("routes.generate")
|
| 22 |
+
router = APIRouter(tags=["Generation"])
|
| 23 |
+
|
| 24 |
+
|
| 25 |
+
@router.post(
|
| 26 |
+
"/generate",
|
| 27 |
+
response_model=JobSubmittedResponse,
|
| 28 |
+
status_code=202, # 202 Accepted — work is deferred
|
| 29 |
+
summary="Submit an image generation job",
|
| 30 |
+
description=(
|
| 31 |
+
"Validates the prompt and parameters, creates a queued job, "
|
| 32 |
+
"and returns a `job_id` immediately. "
|
| 33 |
+
"Poll `GET /jobs/{job_id}` to track progress. "
|
| 34 |
+
"Download the result with `GET /jobs/{job_id}/download` once `status == 'completed'`."
|
| 35 |
+
),
|
| 36 |
+
)
|
| 37 |
+
async def submit_generate(body: GenerateRequest) -> JobSubmittedResponse:
|
| 38 |
+
# Guard: pipeline must exist (or be auto-loaded at startup)
|
| 39 |
+
if not pipeline_mgr.is_loaded and not pipeline_mgr.is_loading:
|
| 40 |
+
# Try to trigger a load if the operator hasn't done so
|
| 41 |
+
logger.warning(
|
| 42 |
+
"Pipeline not loaded — prompting load of default model '%s'.",
|
| 43 |
+
settings.model_id,
|
| 44 |
+
)
|
| 45 |
+
# We don't block here; the worker will call load() itself before processing
|
| 46 |
+
# But we warn the user so they know latency is higher for the first job.
|
| 47 |
+
|
| 48 |
+
params = {
|
| 49 |
+
"width": body.width,
|
| 50 |
+
"height": body.height,
|
| 51 |
+
"num_inference_steps": body.num_inference_steps,
|
| 52 |
+
"guidance_scale": body.guidance_scale,
|
| 53 |
+
"seed": body.seed,
|
| 54 |
+
"scheduler": body.scheduler.value,
|
| 55 |
+
}
|
| 56 |
+
|
| 57 |
+
# Create and enqueue
|
| 58 |
+
job = job_store.create(
|
| 59 |
+
prompt=body.prompt,
|
| 60 |
+
negative_prompt=body.negative_prompt,
|
| 61 |
+
params=params,
|
| 62 |
+
model_id=pipeline_mgr.current_model_id or settings.model_id,
|
| 63 |
+
)
|
| 64 |
+
enqueue(job.job_id)
|
| 65 |
+
|
| 66 |
+
position = queue_position(job.job_id)
|
| 67 |
+
msg = (
|
| 68 |
+
f"Job queued at position {position}."
|
| 69 |
+
if position > 1
|
| 70 |
+
else "Job is next in queue and will start immediately."
|
| 71 |
+
)
|
| 72 |
+
if not pipeline_mgr.is_loaded:
|
| 73 |
+
msg += " Note: the model pipeline is not yet loaded — first job will include model load time."
|
| 74 |
+
|
| 75 |
+
return JobSubmittedResponse(
|
| 76 |
+
job_id=job.job_id,
|
| 77 |
+
status=JobStatus.QUEUED,
|
| 78 |
+
created_at=job.created_at,
|
| 79 |
+
queue_position=position,
|
| 80 |
+
message=msg,
|
| 81 |
+
)
|
routes/health.py
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
routes/health.py — Health check and model management endpoints.
|
| 3 |
+
|
| 4 |
+
GET /health → system status and pipeline info
|
| 5 |
+
GET /models → list of well-known CPU-friendly model IDs
|
| 6 |
+
POST /models/load → hot-swap the loaded pipeline
|
| 7 |
+
"""
|
| 8 |
+
from __future__ import annotations
|
| 9 |
+
|
| 10 |
+
import logging
|
| 11 |
+
import threading
|
| 12 |
+
|
| 13 |
+
from fastapi import APIRouter, BackgroundTasks, HTTPException
|
| 14 |
+
|
| 15 |
+
from config import settings
|
| 16 |
+
from job_store import job_store
|
| 17 |
+
from pipeline_manager import pipeline_mgr
|
| 18 |
+
from schemas import HealthResponse, LoadModelRequest, LoadModelResponse
|
| 19 |
+
from worker import queue_size
|
| 20 |
+
|
| 21 |
+
logger = logging.getLogger("routes.health")
|
| 22 |
+
router = APIRouter(tags=["System"])
|
| 23 |
+
|
| 24 |
+
|
| 25 |
+
# ── Health ────────────────────────────────────────────────────────────────────
|
| 26 |
+
|
| 27 |
+
@router.get(
|
| 28 |
+
"/health",
|
| 29 |
+
response_model=HealthResponse,
|
| 30 |
+
summary="Service health and pipeline status",
|
| 31 |
+
)
|
| 32 |
+
async def health() -> HealthResponse:
|
| 33 |
+
counts = job_store.counts_by_status()
|
| 34 |
+
return HealthResponse(
|
| 35 |
+
status="ok" if pipeline_mgr.is_loaded else ("loading" if pipeline_mgr.is_loading else "idle"),
|
| 36 |
+
model_id=pipeline_mgr.current_model_id,
|
| 37 |
+
pipeline_loaded=pipeline_mgr.is_loaded,
|
| 38 |
+
loading=pipeline_mgr.is_loading,
|
| 39 |
+
queue_size=queue_size(),
|
| 40 |
+
jobs_total=job_store.total,
|
| 41 |
+
jobs_by_status=counts,
|
| 42 |
+
cpu_threads=settings.cpu_threads or (__import__("os").cpu_count() or 4),
|
| 43 |
+
outputs_dir=settings.outputs_dir,
|
| 44 |
+
)
|
| 45 |
+
|
| 46 |
+
|
| 47 |
+
# ── Model catalogue ────────────────────────────────────────────────────────────
|
| 48 |
+
|
| 49 |
+
_KNOWN_MODELS = [
|
| 50 |
+
{
|
| 51 |
+
"model_id": "nota-ai/bk-sdm-small",
|
| 52 |
+
"label": "BK-SDM Small (recommended for CPU)",
|
| 53 |
+
"size_gb": 0.5,
|
| 54 |
+
"notes": "Very fast on CPU. ~60-120s per 512×512 image at 20 steps.",
|
| 55 |
+
},
|
| 56 |
+
{
|
| 57 |
+
"model_id": "runwayml/stable-diffusion-v1-5",
|
| 58 |
+
"label": "Stable Diffusion v1.5",
|
| 59 |
+
"size_gb": 4.0,
|
| 60 |
+
"notes": "Standard quality. ~150-300s per 512×512 on CPU.",
|
| 61 |
+
},
|
| 62 |
+
{
|
| 63 |
+
"model_id": "stabilityai/stable-diffusion-2-1-base",
|
| 64 |
+
"label": "Stable Diffusion 2.1 Base",
|
| 65 |
+
"size_gb": 5.2,
|
| 66 |
+
"notes": "Higher quality. ~200-400s per 512×512 on CPU.",
|
| 67 |
+
},
|
| 68 |
+
{
|
| 69 |
+
"model_id": "CompVis/stable-diffusion-v1-4",
|
| 70 |
+
"label": "Stable Diffusion v1.4 (original)",
|
| 71 |
+
"size_gb": 4.0,
|
| 72 |
+
"notes": "Historical baseline. SD v1.5 is preferred.",
|
| 73 |
+
},
|
| 74 |
+
]
|
| 75 |
+
|
| 76 |
+
|
| 77 |
+
@router.get(
|
| 78 |
+
"/models",
|
| 79 |
+
summary="List supported CPU-friendly model IDs",
|
| 80 |
+
)
|
| 81 |
+
async def list_models() -> dict:
|
| 82 |
+
return {
|
| 83 |
+
"current_model": pipeline_mgr.current_model_id,
|
| 84 |
+
"models": _KNOWN_MODELS,
|
| 85 |
+
}
|
| 86 |
+
|
| 87 |
+
|
| 88 |
+
# ── Hot-swap model ─────────────────────────────────────────────────────────────
|
| 89 |
+
|
| 90 |
+
@router.post(
|
| 91 |
+
"/models/load",
|
| 92 |
+
response_model=LoadModelResponse,
|
| 93 |
+
summary="Load (or hot-swap) a Hugging Face model",
|
| 94 |
+
)
|
| 95 |
+
async def load_model(body: LoadModelRequest, background_tasks: BackgroundTasks) -> LoadModelResponse:
|
| 96 |
+
if pipeline_mgr.is_loading:
|
| 97 |
+
raise HTTPException(status_code=409, detail="A model is already loading. Try again shortly.")
|
| 98 |
+
|
| 99 |
+
def _load():
|
| 100 |
+
try:
|
| 101 |
+
pipeline_mgr.load(body.model_id)
|
| 102 |
+
except Exception as exc:
|
| 103 |
+
logger.exception("Background model load failed: %s", exc)
|
| 104 |
+
|
| 105 |
+
background_tasks.add_task(_load)
|
| 106 |
+
|
| 107 |
+
return LoadModelResponse(
|
| 108 |
+
ok=True,
|
| 109 |
+
model_id=body.model_id,
|
| 110 |
+
message=f"Loading '{body.model_id}' in the background. Poll GET /health to check status.",
|
| 111 |
+
)
|
routes/jobs.py
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
routes/jobs.py — Job lifecycle management.
|
| 3 |
+
|
| 4 |
+
GET /jobs → list all jobs (filterable)
|
| 5 |
+
GET /jobs/{job_id} → single job status / progress
|
| 6 |
+
GET /jobs/{job_id}/download → download the generated PNG
|
| 7 |
+
DELETE /jobs/{job_id} → cancel or delete a job and its image
|
| 8 |
+
"""
|
| 9 |
+
from __future__ import annotations
|
| 10 |
+
|
| 11 |
+
import logging
|
| 12 |
+
import mimetypes
|
| 13 |
+
import os
|
| 14 |
+
from typing import Optional
|
| 15 |
+
|
| 16 |
+
from fastapi import APIRouter, HTTPException, Query
|
| 17 |
+
from fastapi.responses import FileResponse
|
| 18 |
+
|
| 19 |
+
from config import settings
|
| 20 |
+
from job_store import job_store
|
| 21 |
+
from schemas import DeleteJobResponse, Job, JobListResponse, JobStatus
|
| 22 |
+
|
| 23 |
+
logger = logging.getLogger("routes.jobs")
|
| 24 |
+
router = APIRouter(prefix="/jobs", tags=["Jobs"])
|
| 25 |
+
|
| 26 |
+
|
| 27 |
+
# ── List jobs ─────────────────────────────────────────────────────────────────
|
| 28 |
+
|
| 29 |
+
@router.get(
|
| 30 |
+
"",
|
| 31 |
+
response_model=JobListResponse,
|
| 32 |
+
summary="List all jobs",
|
| 33 |
+
)
|
| 34 |
+
async def list_jobs(
|
| 35 |
+
status: Optional[JobStatus] = Query(None, description="Filter by job status."),
|
| 36 |
+
limit: int = Query(50, ge=1, le=200),
|
| 37 |
+
offset: int = Query(0, ge=0),
|
| 38 |
+
) -> JobListResponse:
|
| 39 |
+
jobs = job_store.list_all(status_filter=status, limit=limit, offset=offset)
|
| 40 |
+
counts = job_store.counts_by_status()
|
| 41 |
+
return JobListResponse(
|
| 42 |
+
jobs=jobs,
|
| 43 |
+
total=job_store.total,
|
| 44 |
+
queued=counts.get("queued", 0),
|
| 45 |
+
processing=counts.get("processing", 0),
|
| 46 |
+
completed=counts.get("completed", 0),
|
| 47 |
+
failed=counts.get("failed", 0),
|
| 48 |
+
)
|
| 49 |
+
|
| 50 |
+
|
| 51 |
+
# ── Single job status ─────────────────────────────────────────────────────────
|
| 52 |
+
|
| 53 |
+
@router.get(
|
| 54 |
+
"/{job_id}",
|
| 55 |
+
response_model=Job,
|
| 56 |
+
summary="Get job status and progress",
|
| 57 |
+
description=(
|
| 58 |
+
"Poll this endpoint to track a generation job. "
|
| 59 |
+
"When `status == 'completed'` the `download_url` field is populated."
|
| 60 |
+
),
|
| 61 |
+
)
|
| 62 |
+
async def get_job(job_id: str) -> Job:
|
| 63 |
+
job = job_store.get(job_id)
|
| 64 |
+
if not job:
|
| 65 |
+
raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found.")
|
| 66 |
+
return job
|
| 67 |
+
|
| 68 |
+
|
| 69 |
+
# ── Download generated image ──────────────────────────────────────────────────
|
| 70 |
+
|
| 71 |
+
@router.get(
|
| 72 |
+
"/{job_id}/download",
|
| 73 |
+
summary="Download the generated image",
|
| 74 |
+
description=(
|
| 75 |
+
"Returns the PNG image as a file attachment. "
|
| 76 |
+
"Only available when `status == 'completed'`."
|
| 77 |
+
),
|
| 78 |
+
responses={
|
| 79 |
+
200: {"content": {"image/png": {}}},
|
| 80 |
+
202: {"description": "Job is still processing."},
|
| 81 |
+
404: {"description": "Job not found or image missing."},
|
| 82 |
+
},
|
| 83 |
+
)
|
| 84 |
+
async def download_image(job_id: str):
|
| 85 |
+
job = job_store.get(job_id)
|
| 86 |
+
if not job:
|
| 87 |
+
raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found.")
|
| 88 |
+
|
| 89 |
+
if job.status == JobStatus.QUEUED:
|
| 90 |
+
raise HTTPException(status_code=202, detail="Job is queued and has not started yet.")
|
| 91 |
+
|
| 92 |
+
if job.status == JobStatus.PROCESSING:
|
| 93 |
+
raise HTTPException(
|
| 94 |
+
status_code=202,
|
| 95 |
+
detail=f"Job is still processing ({job.progress}% complete).",
|
| 96 |
+
)
|
| 97 |
+
|
| 98 |
+
if job.status == JobStatus.FAILED:
|
| 99 |
+
raise HTTPException(status_code=422, detail=f"Job failed: {job.error}")
|
| 100 |
+
|
| 101 |
+
if not job.image_filename:
|
| 102 |
+
raise HTTPException(status_code=500, detail="Job completed but image filename is missing.")
|
| 103 |
+
|
| 104 |
+
image_path = os.path.join(settings.outputs_dir, job.image_filename)
|
| 105 |
+
if not os.path.isfile(image_path):
|
| 106 |
+
raise HTTPException(
|
| 107 |
+
status_code=404,
|
| 108 |
+
detail=f"Image file '{job.image_filename}' not found on disk. It may have been deleted.",
|
| 109 |
+
)
|
| 110 |
+
|
| 111 |
+
return FileResponse(
|
| 112 |
+
path=image_path,
|
| 113 |
+
media_type="image/png",
|
| 114 |
+
filename=job.image_filename,
|
| 115 |
+
headers={"Content-Disposition": f'attachment; filename="{job.image_filename}"'},
|
| 116 |
+
)
|
| 117 |
+
|
| 118 |
+
|
| 119 |
+
# ── Delete job ─────────────────────────────────────────────────────────────────
|
| 120 |
+
|
| 121 |
+
@router.delete(
|
| 122 |
+
"/{job_id}",
|
| 123 |
+
response_model=DeleteJobResponse,
|
| 124 |
+
summary="Delete a job and its generated image",
|
| 125 |
+
description=(
|
| 126 |
+
"Removes the job record from memory and deletes the PNG from disk "
|
| 127 |
+
"(if it exists). Queued or processing jobs are also removed — "
|
| 128 |
+
"the worker will skip orphaned job IDs gracefully."
|
| 129 |
+
),
|
| 130 |
+
)
|
| 131 |
+
async def delete_job(job_id: str) -> DeleteJobResponse:
|
| 132 |
+
job = job_store.get(job_id)
|
| 133 |
+
if not job:
|
| 134 |
+
raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found.")
|
| 135 |
+
|
| 136 |
+
# Delete image file from disk
|
| 137 |
+
image_deleted = False
|
| 138 |
+
if job.image_filename:
|
| 139 |
+
image_path = os.path.join(settings.outputs_dir, job.image_filename)
|
| 140 |
+
if os.path.isfile(image_path):
|
| 141 |
+
try:
|
| 142 |
+
os.remove(image_path)
|
| 143 |
+
image_deleted = True
|
| 144 |
+
logger.info("Deleted image: %s", image_path)
|
| 145 |
+
except OSError as exc:
|
| 146 |
+
logger.warning("Could not delete image %s: %s", image_path, exc)
|
| 147 |
+
|
| 148 |
+
# Remove job record
|
| 149 |
+
job_store.delete(job_id)
|
| 150 |
+
logger.info("Deleted job record: %s", job_id)
|
| 151 |
+
|
| 152 |
+
return DeleteJobResponse(
|
| 153 |
+
ok=True,
|
| 154 |
+
job_id=job_id,
|
| 155 |
+
image_deleted=image_deleted,
|
| 156 |
+
message=(
|
| 157 |
+
f"Job {job_id} deleted."
|
| 158 |
+
+ (" Image file removed from disk." if image_deleted else "")
|
| 159 |
+
),
|
| 160 |
+
)
|
schemas.py
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
schemas.py — All Pydantic models for request bodies and API responses.
|
| 3 |
+
"""
|
| 4 |
+
from __future__ import annotations
|
| 5 |
+
from enum import Enum
|
| 6 |
+
from typing import Any, Dict, Optional
|
| 7 |
+
from datetime import datetime
|
| 8 |
+
from pydantic import BaseModel, Field, model_validator
|
| 9 |
+
|
| 10 |
+
|
| 11 |
+
# ── Enums ─────────────────────────────────────────────────────────────────────
|
| 12 |
+
|
| 13 |
+
class JobStatus(str, Enum):
|
| 14 |
+
QUEUED = "queued"
|
| 15 |
+
PROCESSING = "processing"
|
| 16 |
+
COMPLETED = "completed"
|
| 17 |
+
FAILED = "failed"
|
| 18 |
+
|
| 19 |
+
|
| 20 |
+
class Scheduler(str, Enum):
|
| 21 |
+
DPM_PLUS_PLUS = "dpm++" # DPMSolverMultistepScheduler — best for CPU (fast convergence)
|
| 22 |
+
EULER_A = "euler_a" # EulerAncestralDiscreteScheduler
|
| 23 |
+
EULER = "euler" # EulerDiscreteScheduler
|
| 24 |
+
PNDM = "pndm" # PNDMScheduler
|
| 25 |
+
|
| 26 |
+
|
| 27 |
+
# ── Request bodies ─────────────────────────────────────────────────────────────
|
| 28 |
+
|
| 29 |
+
class GenerateRequest(BaseModel):
|
| 30 |
+
prompt: str = Field(
|
| 31 |
+
...,
|
| 32 |
+
min_length=1,
|
| 33 |
+
max_length=1500,
|
| 34 |
+
description="Text prompt describing the image to generate.",
|
| 35 |
+
examples=["a photorealistic cat sitting on a wooden table, soft light"],
|
| 36 |
+
)
|
| 37 |
+
negative_prompt: str = Field(
|
| 38 |
+
"blurry, ugly, low quality, distorted, watermark, text, nsfw",
|
| 39 |
+
max_length=1000,
|
| 40 |
+
description="Things to exclude from the image.",
|
| 41 |
+
)
|
| 42 |
+
width: int = Field(512, ge=256, le=768, multiple_of=8, description="Image width (pixels, multiple of 8).")
|
| 43 |
+
height: int = Field(512, ge=256, le=768, multiple_of=8, description="Image height (pixels, multiple of 8).")
|
| 44 |
+
num_inference_steps: int = Field(20, ge=1, le=50, description="Denoising steps. 15–20 is optimal on CPU.")
|
| 45 |
+
guidance_scale: float = Field(7.5, ge=1.0, le=20.0, description="Classifier-free guidance scale.")
|
| 46 |
+
seed: int = Field(-1, ge=-1, description="RNG seed. -1 = random each time.")
|
| 47 |
+
scheduler: Scheduler = Field(Scheduler.DPM_PLUS_PLUS, description="Noise scheduler algorithm.")
|
| 48 |
+
|
| 49 |
+
@model_validator(mode="after")
|
| 50 |
+
def clamp_to_config(self) -> "GenerateRequest":
|
| 51 |
+
from config import settings
|
| 52 |
+
self.width = min(self.width, settings.max_width)
|
| 53 |
+
self.height = min(self.height, settings.max_height)
|
| 54 |
+
self.num_inference_steps = min(self.num_inference_steps, settings.max_steps)
|
| 55 |
+
return self
|
| 56 |
+
|
| 57 |
+
|
| 58 |
+
class LoadModelRequest(BaseModel):
|
| 59 |
+
model_id: str = Field(
|
| 60 |
+
...,
|
| 61 |
+
description="Hugging Face model repo ID, e.g. 'runwayml/stable-diffusion-v1-5'.",
|
| 62 |
+
)
|
| 63 |
+
|
| 64 |
+
|
| 65 |
+
# ── Job model ─────────────────────────────────────────────────────────────────
|
| 66 |
+
|
| 67 |
+
class Job(BaseModel):
|
| 68 |
+
job_id: str
|
| 69 |
+
status: JobStatus
|
| 70 |
+
prompt: str
|
| 71 |
+
negative_prompt: str
|
| 72 |
+
params: Dict[str, Any]
|
| 73 |
+
|
| 74 |
+
created_at: datetime
|
| 75 |
+
started_at: Optional[datetime] = None
|
| 76 |
+
completed_at: Optional[datetime] = None
|
| 77 |
+
|
| 78 |
+
progress: int = 0 # 0–100
|
| 79 |
+
current_step: int = 0
|
| 80 |
+
total_steps: int = 0
|
| 81 |
+
|
| 82 |
+
image_filename: Optional[str] = None # filename inside outputs/
|
| 83 |
+
download_url: Optional[str] = None # relative URL
|
| 84 |
+
duration_seconds: Optional[float] = None
|
| 85 |
+
|
| 86 |
+
error: Optional[str] = None
|
| 87 |
+
|
| 88 |
+
model_id: Optional[str] = None # model used for this job
|
| 89 |
+
|
| 90 |
+
|
| 91 |
+
# ── Response wrappers ─────────────────────────────────────────────────────────
|
| 92 |
+
|
| 93 |
+
class JobSubmittedResponse(BaseModel):
|
| 94 |
+
job_id: str
|
| 95 |
+
status: JobStatus
|
| 96 |
+
created_at: datetime
|
| 97 |
+
queue_position: int
|
| 98 |
+
message: str
|
| 99 |
+
|
| 100 |
+
|
| 101 |
+
class JobListResponse(BaseModel):
|
| 102 |
+
jobs: list[Job]
|
| 103 |
+
total: int
|
| 104 |
+
queued: int
|
| 105 |
+
processing: int
|
| 106 |
+
completed: int
|
| 107 |
+
failed: int
|
| 108 |
+
|
| 109 |
+
|
| 110 |
+
class DeleteJobResponse(BaseModel):
|
| 111 |
+
ok: bool
|
| 112 |
+
job_id: str
|
| 113 |
+
image_deleted: bool
|
| 114 |
+
message: str
|
| 115 |
+
|
| 116 |
+
|
| 117 |
+
class HealthResponse(BaseModel):
|
| 118 |
+
status: str
|
| 119 |
+
model_id: Optional[str]
|
| 120 |
+
pipeline_loaded: bool
|
| 121 |
+
loading: bool
|
| 122 |
+
queue_size: int
|
| 123 |
+
jobs_total: int
|
| 124 |
+
jobs_by_status: Dict[str, int]
|
| 125 |
+
cpu_threads: int
|
| 126 |
+
outputs_dir: str
|
| 127 |
+
|
| 128 |
+
|
| 129 |
+
class LoadModelResponse(BaseModel):
|
| 130 |
+
ok: bool
|
| 131 |
+
model_id: str
|
| 132 |
+
message: str
|
start.sh
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
#!/usr/bin/env bash
|
| 2 |
+
# start.sh — Quick-start script for the HF CPU Image Generation API
|
| 3 |
+
set -e
|
| 4 |
+
|
| 5 |
+
VENV_DIR=".venv"
|
| 6 |
+
|
| 7 |
+
echo ""
|
| 8 |
+
echo "═══════════════════════════════════════════════════════════════"
|
| 9 |
+
echo " HF CPU Image Generation API — Setup & Start"
|
| 10 |
+
echo "═══════════════════════════════════════════════════════════════"
|
| 11 |
+
echo ""
|
| 12 |
+
|
| 13 |
+
# ── 1. Create virtualenv if needed ────────────────────────────────────────────
|
| 14 |
+
if [ ! -d "$VENV_DIR" ]; then
|
| 15 |
+
echo "→ Creating Python virtualenv in $VENV_DIR ..."
|
| 16 |
+
python3 -m venv "$VENV_DIR"
|
| 17 |
+
fi
|
| 18 |
+
|
| 19 |
+
source "$VENV_DIR/bin/activate"
|
| 20 |
+
|
| 21 |
+
# ── 2. Install PyTorch (CPU-only wheel) ───────────────────────────────────────
|
| 22 |
+
if ! python -c "import torch" 2>/dev/null; then
|
| 23 |
+
echo "→ Installing PyTorch (CPU-only) ..."
|
| 24 |
+
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu -q
|
| 25 |
+
fi
|
| 26 |
+
|
| 27 |
+
# ── 3. Install other dependencies ─────────────────────────────────────────────
|
| 28 |
+
echo "→ Installing dependencies from requirements.txt ..."
|
| 29 |
+
pip install -r requirements.txt -q
|
| 30 |
+
|
| 31 |
+
# ── 4. Copy .env if not present ───────────────────────────────────────────────
|
| 32 |
+
if [ ! -f ".env" ]; then
|
| 33 |
+
echo "→ Creating .env from .env.example ..."
|
| 34 |
+
cp .env.example .env
|
| 35 |
+
fi
|
| 36 |
+
|
| 37 |
+
# ── 5. Start the API ──────────────────────────────────────────────────────────
|
| 38 |
+
echo ""
|
| 39 |
+
echo "→ Starting API on http://0.0.0.0:8000"
|
| 40 |
+
echo " Swagger UI: http://localhost:8000/docs"
|
| 41 |
+
echo " API health: http://localhost:8000/health"
|
| 42 |
+
echo ""
|
| 43 |
+
|
| 44 |
+
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
|
worker.py
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
worker.py — Single background thread that processes generation jobs one at a time.
|
| 3 |
+
|
| 4 |
+
Architecture:
|
| 5 |
+
┌────────────────────┐ queue.put(job_id) ┌──────────────────────┐
|
| 6 |
+
│ FastAPI endpoint │ ────────────────────────────► │ _job_queue (Queue) │
|
| 7 |
+
│ POST /generate │ └──────────┬───────────┘
|
| 8 |
+
└────────────────────┘ │ .get()
|
| 9 |
+
▼
|
| 10 |
+
┌──────────────────────┐
|
| 11 |
+
│ worker_loop() │
|
| 12 |
+
│ (daemon thread) │
|
| 13 |
+
│ runs _process_job() │
|
| 14 |
+
└──────────────────────┘
|
| 15 |
+
|
| 16 |
+
Only one job runs at a time — CPU inference is single-threaded anyway.
|
| 17 |
+
"""
|
| 18 |
+
from __future__ import annotations
|
| 19 |
+
|
| 20 |
+
import logging
|
| 21 |
+
import os
|
| 22 |
+
import queue
|
| 23 |
+
import threading
|
| 24 |
+
from datetime import datetime, timezone
|
| 25 |
+
from typing import List
|
| 26 |
+
|
| 27 |
+
logger = logging.getLogger("worker")
|
| 28 |
+
|
| 29 |
+
# Internal FIFO queue — contains job_ids as strings
|
| 30 |
+
_job_queue: queue.Queue[str] = queue.Queue()
|
| 31 |
+
|
| 32 |
+
# Lock used to inspect queue contents safely
|
| 33 |
+
_queue_lock = threading.Lock()
|
| 34 |
+
|
| 35 |
+
# Ordered list of pending job IDs (mirrors the queue for position lookups)
|
| 36 |
+
_pending: List[str] = []
|
| 37 |
+
_pending_lock = threading.Lock()
|
| 38 |
+
|
| 39 |
+
|
| 40 |
+
# ── Public helpers (called from FastAPI routes) ────────────────────────────────
|
| 41 |
+
|
| 42 |
+
def enqueue(job_id: str) -> None:
|
| 43 |
+
"""Add a job to the processing queue."""
|
| 44 |
+
with _pending_lock:
|
| 45 |
+
_pending.append(job_id)
|
| 46 |
+
_job_queue.put(job_id)
|
| 47 |
+
logger.info("Enqueued job %s (queue size: %d)", job_id, _job_queue.qsize())
|
| 48 |
+
|
| 49 |
+
|
| 50 |
+
def queue_position(job_id: str) -> int:
|
| 51 |
+
"""Return the 1-based position of job_id in the pending queue (0 if not found)."""
|
| 52 |
+
with _pending_lock:
|
| 53 |
+
try:
|
| 54 |
+
return _pending.index(job_id) + 1
|
| 55 |
+
except ValueError:
|
| 56 |
+
return 0
|
| 57 |
+
|
| 58 |
+
|
| 59 |
+
def queue_size() -> int:
|
| 60 |
+
"""Number of jobs still waiting (does not include the currently running job)."""
|
| 61 |
+
return _job_queue.qsize()
|
| 62 |
+
|
| 63 |
+
|
| 64 |
+
# ── Core processing ────────────────────────────────────────────────────────────
|
| 65 |
+
|
| 66 |
+
def _process_job(job_id: str) -> None:
|
| 67 |
+
"""Generate an image for one job. All state mutations go through job_store."""
|
| 68 |
+
from config import settings
|
| 69 |
+
from job_store import job_store
|
| 70 |
+
from pipeline_manager import pipeline_mgr
|
| 71 |
+
from schemas import JobStatus
|
| 72 |
+
|
| 73 |
+
job = job_store.get(job_id)
|
| 74 |
+
if not job:
|
| 75 |
+
logger.warning("Job %s not found in store — skipping.", job_id)
|
| 76 |
+
return
|
| 77 |
+
|
| 78 |
+
# Mark as processing
|
| 79 |
+
job_store.update(
|
| 80 |
+
job_id,
|
| 81 |
+
status=JobStatus.PROCESSING,
|
| 82 |
+
started_at=datetime.now(timezone.utc),
|
| 83 |
+
progress=0,
|
| 84 |
+
)
|
| 85 |
+
logger.info("Processing job %s prompt=%r", job_id, job.prompt[:60])
|
| 86 |
+
|
| 87 |
+
try:
|
| 88 |
+
# ── Ensure pipeline is loaded ──────────────────────────────────────────
|
| 89 |
+
if not pipeline_mgr.is_loaded:
|
| 90 |
+
logger.info("Pipeline not loaded — loading now (job %s will wait).", job_id)
|
| 91 |
+
pipeline_mgr.load()
|
| 92 |
+
|
| 93 |
+
p = job.params
|
| 94 |
+
|
| 95 |
+
# ── Step-progress callback ─────────────────────────────────────────────
|
| 96 |
+
def on_step(step: int, total: int) -> None:
|
| 97 |
+
pct = int(step / total * 95) # reserve last 5 % for save
|
| 98 |
+
job_store.update(job_id, progress=pct, current_step=step, total_steps=total)
|
| 99 |
+
|
| 100 |
+
# ── Inference ─────────────────────────────────────────────────────────
|
| 101 |
+
image, used_seed = pipeline_mgr.generate(
|
| 102 |
+
prompt=job.prompt,
|
| 103 |
+
negative_prompt=job.negative_prompt,
|
| 104 |
+
width=p.get("width", settings.default_width),
|
| 105 |
+
height=p.get("height", settings.default_height),
|
| 106 |
+
num_inference_steps=p.get("num_inference_steps", settings.default_steps),
|
| 107 |
+
guidance_scale=p.get("guidance_scale", settings.default_guidance_scale),
|
| 108 |
+
seed=p.get("seed", -1),
|
| 109 |
+
scheduler_name=p.get("scheduler", "dpm++"),
|
| 110 |
+
step_callback=on_step,
|
| 111 |
+
)
|
| 112 |
+
|
| 113 |
+
# ── Save image ────────────────────────────────────────────────────────
|
| 114 |
+
job_store.update(job_id, progress=97)
|
| 115 |
+
|
| 116 |
+
timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
|
| 117 |
+
filename = f"{timestamp}_{job_id[:8]}_{used_seed}.png"
|
| 118 |
+
abs_path = os.path.join(settings.outputs_dir, filename)
|
| 119 |
+
image.save(abs_path, format="PNG", optimize=False)
|
| 120 |
+
|
| 121 |
+
# ── Compute duration ───────────────────────────────────────────────────
|
| 122 |
+
now = datetime.now(timezone.utc)
|
| 123 |
+
started = job_store.get(job_id).started_at
|
| 124 |
+
duration = (now - started).total_seconds() if started else None
|
| 125 |
+
|
| 126 |
+
job_store.update(
|
| 127 |
+
job_id,
|
| 128 |
+
status=JobStatus.COMPLETED,
|
| 129 |
+
completed_at=now,
|
| 130 |
+
progress=100,
|
| 131 |
+
image_filename=filename,
|
| 132 |
+
download_url=f"/jobs/{job_id}/download",
|
| 133 |
+
duration_seconds=round(duration, 2) if duration else None,
|
| 134 |
+
)
|
| 135 |
+
|
| 136 |
+
logger.info(
|
| 137 |
+
"Job %s completed in %.1f s → %s",
|
| 138 |
+
job_id,
|
| 139 |
+
duration or 0,
|
| 140 |
+
filename,
|
| 141 |
+
)
|
| 142 |
+
|
| 143 |
+
except Exception as exc:
|
| 144 |
+
logger.exception("Job %s failed: %s", job_id, exc)
|
| 145 |
+
job_store.update(
|
| 146 |
+
job_id,
|
| 147 |
+
status=JobStatus.FAILED,
|
| 148 |
+
completed_at=datetime.now(timezone.utc),
|
| 149 |
+
error=str(exc),
|
| 150 |
+
progress=0,
|
| 151 |
+
)
|
| 152 |
+
|
| 153 |
+
|
| 154 |
+
# ── Worker loop (runs in its own daemon thread) ────────────────────────────────
|
| 155 |
+
|
| 156 |
+
def worker_loop() -> None:
|
| 157 |
+
"""Infinite loop: pull job IDs from the queue and process them."""
|
| 158 |
+
logger.info("Worker thread started.")
|
| 159 |
+
while True:
|
| 160 |
+
job_id = _job_queue.get() # blocks until a job arrives
|
| 161 |
+
with _pending_lock:
|
| 162 |
+
try:
|
| 163 |
+
_pending.remove(job_id)
|
| 164 |
+
except ValueError:
|
| 165 |
+
pass
|
| 166 |
+
try:
|
| 167 |
+
_process_job(job_id)
|
| 168 |
+
except Exception as exc:
|
| 169 |
+
# Catch-all safety net — the loop must never crash
|
| 170 |
+
logger.exception("Unhandled error in worker for job %s: %s", job_id, exc)
|
| 171 |
+
finally:
|
| 172 |
+
_job_queue.task_done()
|
| 173 |
+
|
| 174 |
+
|
| 175 |
+
def start_worker() -> threading.Thread:
|
| 176 |
+
"""Spawn and return the daemon worker thread. Call once at application startup."""
|
| 177 |
+
t = threading.Thread(target=worker_loop, name="image-worker", daemon=True)
|
| 178 |
+
t.start()
|
| 179 |
+
return t
|