Initial Real-ESRGAN API project setup
This commit is contained in:
Developer
254
QUICKSTART.md
Normal file
254
QUICKSTART.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Quick Start Guide
|
||||
|
||||
## 1. Local Development (CPU, ~2 minutes)
|
||||
|
||||
```bash
|
||||
# Clone or navigate to project
|
||||
cd /home/valknar/projects/realesrgan-api
|
||||
|
||||
# Build Docker image
|
||||
docker compose build
|
||||
|
||||
# Start API service
|
||||
docker compose up -d
|
||||
|
||||
# Verify running
|
||||
curl http://localhost:8000/api/v1/health
|
||||
# Response: {"status":"ok","version":"1.0.0","uptime_seconds":...}
|
||||
```
|
||||
|
||||
## 2. Download Models (2-5 minutes)
|
||||
|
||||
```bash
|
||||
# List available models
|
||||
curl http://localhost:8000/api/v1/models
|
||||
|
||||
# Download default 4x model (required first)
|
||||
curl -X POST http://localhost:8000/api/v1/models/download \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"models": ["RealESRGAN_x4plus"]}'
|
||||
|
||||
# Optional: Download anime model
|
||||
curl -X POST http://localhost:8000/api/v1/models/download \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"models": ["RealESRGAN_x4plus_anime_6B"]}'
|
||||
|
||||
# Verify models downloaded
|
||||
curl http://localhost:8000/api/v1/models-info
|
||||
```
|
||||
|
||||
## 3. Upscale Your First Image
|
||||
|
||||
### Option A: Synchronous (returns immediately)
|
||||
|
||||
```bash
|
||||
# Get a test image or use your own
|
||||
# For demo, create a small test image:
|
||||
python3 << 'EOF'
|
||||
from PIL import Image
|
||||
import random
|
||||
img = Image.new('RGB', (256, 256), color=(random.randint(0, 255), random.randint(0, 255), random.randint(0, 255)))
|
||||
img.save('test-image.jpg')
|
||||
EOF
|
||||
|
||||
# Upscale synchronously (returns output.jpg)
|
||||
curl -X POST http://localhost:8000/api/v1/upscale \
|
||||
-F 'image=@test-image.jpg' \
|
||||
-F 'model=RealESRGAN_x4plus' \
|
||||
-o output.jpg
|
||||
|
||||
echo "Done! Check output.jpg"
|
||||
```
|
||||
|
||||
### Option B: Asynchronous Job (for large images or batches)
|
||||
|
||||
```bash
|
||||
# Create upscaling job
|
||||
JOB_ID=$(curl -s -X POST http://localhost:8000/api/v1/jobs \
|
||||
-F 'image=@test-image.jpg' \
|
||||
-F 'model=RealESRGAN_x4plus' | jq -r '.job_id')
|
||||
|
||||
echo "Job ID: $JOB_ID"
|
||||
|
||||
# Check job status (poll every second)
|
||||
while true; do
|
||||
STATUS=$(curl -s http://localhost:8000/api/v1/jobs/$JOB_ID | jq -r '.status')
|
||||
echo "Status: $STATUS"
|
||||
if [ "$STATUS" != "queued" ] && [ "$STATUS" != "processing" ]; then
|
||||
break
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
|
||||
# Download result when complete
|
||||
curl http://localhost:8000/api/v1/jobs/$JOB_ID/result -o output_async.jpg
|
||||
echo "Done! Check output_async.jpg"
|
||||
```
|
||||
|
||||
## 4. API Documentation
|
||||
|
||||
Interactive documentation available at:
|
||||
|
||||
- **Swagger UI**: http://localhost:8000/docs
|
||||
- **ReDoc**: http://localhost:8000/redoc
|
||||
|
||||
Try endpoints directly in Swagger UI!
|
||||
|
||||
## 5. System Monitoring
|
||||
|
||||
```bash
|
||||
# Check system health
|
||||
curl http://localhost:8000/api/v1/health
|
||||
|
||||
# Get detailed system info (CPU, memory, GPU, etc.)
|
||||
curl http://localhost:8000/api/v1/system
|
||||
|
||||
# Get API statistics
|
||||
curl http://localhost:8000/api/v1/stats
|
||||
|
||||
# List all jobs
|
||||
curl http://localhost:8000/api/v1/jobs
|
||||
```
|
||||
|
||||
## 6. GPU Setup (Optional, requires NVIDIA)
|
||||
|
||||
```bash
|
||||
# Build with GPU support
|
||||
docker compose -f docker-compose.gpu.yml build
|
||||
|
||||
# Run with GPU
|
||||
docker compose -f docker-compose.gpu.yml up -d
|
||||
|
||||
# Verify GPU is accessible
|
||||
docker compose -f docker-compose.gpu.yml exec api nvidia-smi
|
||||
|
||||
# Download models again on GPU
|
||||
curl -X POST http://localhost:8000/api/v1/models/download \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"models": ["RealESRGAN_x4plus"]}'
|
||||
```
|
||||
|
||||
## 7. Production Deployment
|
||||
|
||||
```bash
|
||||
# Update docker-compose.prod.yml with your registry/domain
|
||||
# Edit:
|
||||
# - Image URL: your-registry.com/realesrgan-api:latest
|
||||
# - Add domain/reverse proxy config as needed
|
||||
|
||||
# Deploy with production compose
|
||||
docker compose -f docker-compose.prod.yml up -d
|
||||
|
||||
# Verify health
|
||||
curl https://your-domain.com/api/v1/health
|
||||
```
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Batch Upscale Multiple Images
|
||||
|
||||
```bash
|
||||
# Create a batch of images to upscale
|
||||
for i in {1..5}; do
|
||||
python3 << EOF
|
||||
from PIL import Image
|
||||
import random
|
||||
img = Image.new('RGB', (256, 256), color=(random.randint(0, 255), random.randint(0, 255), random.randint(0, 255)))
|
||||
img.save(f'test_{i}.jpg')
|
||||
EOF
|
||||
done
|
||||
|
||||
# Submit batch job
|
||||
curl -X POST http://localhost:8000/api/v1/upscale-batch \
|
||||
-F 'images=@test_1.jpg' \
|
||||
-F 'images=@test_2.jpg' \
|
||||
-F 'images=@test_3.jpg' \
|
||||
-F 'images=@test_4.jpg' \
|
||||
-F 'images=@test_5.jpg' \
|
||||
-F 'model=RealESRGAN_x4plus' | jq '.job_ids[]'
|
||||
```
|
||||
|
||||
### Check Processing Time
|
||||
|
||||
```bash
|
||||
# Upscale and capture timing header
|
||||
curl -i -X POST http://localhost:8000/api/v1/upscale \
|
||||
-F 'image=@test-image.jpg' \
|
||||
-F 'model=RealESRGAN_x4plus' \
|
||||
-o output.jpg 2>&1 | grep X-Processing-Time
|
||||
```
|
||||
|
||||
### List Active Jobs
|
||||
|
||||
```bash
|
||||
# Get all jobs
|
||||
curl http://localhost:8000/api/v1/jobs | jq '.jobs[] | select(.status == "processing")'
|
||||
|
||||
# Get only failed jobs
|
||||
curl http://localhost:8000/api/v1/jobs?status=failed | jq '.'
|
||||
|
||||
# Get completed jobs (limited to 10)
|
||||
curl 'http://localhost:8000/api/v1/jobs?limit=10' | jq '.jobs[] | select(.status == "completed")'
|
||||
```
|
||||
|
||||
### Clean Up Old Jobs
|
||||
|
||||
```bash
|
||||
# Remove jobs older than 48 hours
|
||||
curl -X POST http://localhost:8000/api/v1/cleanup?hours=48
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Models failing to load?
|
||||
|
||||
```bash
|
||||
# Verify models directory
|
||||
curl http://localhost:8000/api/v1/models-info
|
||||
|
||||
# Check container logs
|
||||
docker compose logs -f api
|
||||
|
||||
# Try downloading again
|
||||
curl -X POST http://localhost:8000/api/v1/models/download \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"models": ["RealESRGAN_x4plus"]}'
|
||||
```
|
||||
|
||||
### Image upload fails?
|
||||
|
||||
```bash
|
||||
# Check max upload size config (default 500MB)
|
||||
curl http://localhost:8000/api/v1/system
|
||||
|
||||
# Ensure image file is readable
|
||||
ls -lh test-image.jpg
|
||||
```
|
||||
|
||||
### Job stuck in "processing"?
|
||||
|
||||
```bash
|
||||
# Check API logs
|
||||
docker compose logs api | tail -20
|
||||
|
||||
# Get job details
|
||||
curl http://localhost:8000/api/v1/jobs/{job_id}
|
||||
|
||||
# System may be slow, check resources
|
||||
curl http://localhost:8000/api/v1/system
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✓ API is running and responding
|
||||
2. ✓ Models are downloaded
|
||||
3. ✓ First image upscaled successfully
|
||||
4. → Explore API documentation at `/docs`
|
||||
5. → Configure for your use case
|
||||
6. → Deploy to production
|
||||
|
||||
## Support
|
||||
|
||||
- 📖 [Full README](./README.md)
|
||||
- 🏗️ [Architecture Guide](./CLAUDE.md)
|
||||
- 🔧 [API Documentation](http://localhost:8000/docs)
|
||||
Reference in New Issue
Block a user