Initial Real-ESRGAN API project setup
This commit is contained in:
Developer
244
CLAUDE.md
Normal file
244
CLAUDE.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code when working with this repository.
|
||||
|
||||
## Overview
|
||||
|
||||
This is the Real-ESRGAN API project - a sophisticated, full-featured REST API for image upscaling using Real-ESRGAN. The API supports both synchronous and asynchronous (job-based) processing with Docker containerization for CPU and GPU deployments.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
- **app/main.py**: FastAPI application with lifecycle management
|
||||
- **app/routers/**: API endpoint handlers
|
||||
- `upscale.py`: Synchronous and async upscaling endpoints
|
||||
- `models.py`: Model management endpoints
|
||||
- `health.py`: Health checks and system monitoring
|
||||
- **app/services/**: Business logic
|
||||
- `realesrgan_bridge.py`: Real-ESRGAN model loading and inference
|
||||
- `file_manager.py`: File handling and directory management
|
||||
- `worker.py`: Async job queue with thread pool
|
||||
- `model_manager.py`: Model downloading and metadata
|
||||
- **app/schemas/**: Pydantic request/response models
|
||||
|
||||
### Data Directories
|
||||
|
||||
- `/data/uploads`: User uploaded files
|
||||
- `/data/outputs`: Processed output images
|
||||
- `/data/models`: Real-ESRGAN model weights (.pth files)
|
||||
- `/data/temp`: Temporary processing files
|
||||
- `/data/jobs`: Async job metadata and status
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Local Setup (CPU)
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt -r requirements-cpu.txt
|
||||
|
||||
# Run development server
|
||||
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
|
||||
# Access API
|
||||
# Swagger: http://localhost:8000/docs
|
||||
# ReDoc: http://localhost:8000/redoc
|
||||
```
|
||||
|
||||
### Docker Development
|
||||
|
||||
```bash
|
||||
# Build CPU image
|
||||
docker compose build
|
||||
|
||||
# Run container
|
||||
docker compose up -d
|
||||
|
||||
# View logs
|
||||
docker compose logs -f api
|
||||
|
||||
# Stop container
|
||||
docker compose down
|
||||
```
|
||||
|
||||
### GPU Development
|
||||
|
||||
```bash
|
||||
# Build GPU image
|
||||
docker compose -f docker-compose.gpu.yml build
|
||||
|
||||
# Run with GPU
|
||||
docker compose -f docker-compose.gpu.yml up -d
|
||||
|
||||
# Check GPU usage
|
||||
docker compose -f docker-compose.gpu.yml exec api nvidia-smi
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables (prefix: RSR_)
|
||||
|
||||
All settings from `app/config.py` can be configured via environment:
|
||||
|
||||
```bash
|
||||
RSR_UPLOAD_DIR=/data/uploads
|
||||
RSR_OUTPUT_DIR=/data/outputs
|
||||
RSR_MODELS_DIR=/data/models
|
||||
RSR_EXECUTION_PROVIDERS=["cpu"] # or ["cuda"] for GPU
|
||||
RSR_TILE_SIZE=400 # Tile size for large images
|
||||
RSR_MAX_UPLOAD_SIZE_MB=500
|
||||
RSR_SYNC_TIMEOUT_SECONDS=300
|
||||
```
|
||||
|
||||
### Docker Compose Environment
|
||||
|
||||
Set in `docker-compose.yml` or `docker-compose.gpu.yml` `environment` section.
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Key Endpoints
|
||||
|
||||
- **POST /api/v1/upscale**: Synchronous upscaling (direct response)
|
||||
- **POST /api/v1/jobs**: Create async upscaling job
|
||||
- **GET /api/v1/jobs/{job_id}**: Check job status
|
||||
- **GET /api/v1/jobs/{job_id}/result**: Download result
|
||||
- **GET /api/v1/models**: List available models
|
||||
- **POST /api/v1/models/download**: Download models
|
||||
- **GET /api/v1/health**: Health check
|
||||
- **GET /api/v1/system**: System information
|
||||
|
||||
## Model Management
|
||||
|
||||
### Available Models
|
||||
|
||||
```python
|
||||
'RealESRGAN_x2plus' # 2x upscaling
|
||||
'RealESRGAN_x3plus' # 3x upscaling
|
||||
'RealESRGAN_x4plus' # 4x general purpose (default)
|
||||
'RealESRGAN_x4plus_anime_6B' # 4x anime/art (lighter)
|
||||
```
|
||||
|
||||
### Downloading Models
|
||||
|
||||
```bash
|
||||
# Download specific model
|
||||
curl -X POST http://localhost:8000/api/v1/models/download \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"models": ["RealESRGAN_x4plus"]}'
|
||||
|
||||
# List available models
|
||||
curl http://localhost:8000/api/v1/models
|
||||
```
|
||||
|
||||
## Async Job Processing
|
||||
|
||||
### Workflow
|
||||
|
||||
1. Submit image → POST /api/v1/jobs → returns `job_id`
|
||||
2. Poll status → GET /api/v1/jobs/{job_id}
|
||||
3. When status=completed → GET /api/v1/jobs/{job_id}/result
|
||||
|
||||
### Job States
|
||||
|
||||
- `queued`: Waiting in queue
|
||||
- `processing`: Currently being processed
|
||||
- `completed`: Successfully processed
|
||||
- `failed`: Processing failed
|
||||
|
||||
## Integration with facefusion-api
|
||||
|
||||
This project follows similar patterns to facefusion-api:
|
||||
|
||||
- **File Management**: Same `file_manager.py` utilities
|
||||
- **Worker Queue**: Similar async job processing architecture
|
||||
- **Docker Setup**: Multi-variant CPU/GPU builds
|
||||
- **Configuration**: Environment-based settings with pydantic
|
||||
- **Gitea CI/CD**: Automatic Docker image building
|
||||
- **API Structure**: Organized routers and services
|
||||
|
||||
## Development Tips
|
||||
|
||||
### Adding New Endpoints
|
||||
|
||||
1. Create handler in `app/routers/{domain}.py`
|
||||
2. Define request/response schemas in `app/schemas/{domain}.py`
|
||||
3. Include router in `app/main.py`: `app.include_router(router)`
|
||||
|
||||
### Adding Services
|
||||
|
||||
1. Create service module in `app/services/{service}.py`
|
||||
2. Import and use in routers
|
||||
|
||||
### Testing
|
||||
|
||||
Run a quick test:
|
||||
|
||||
```bash
|
||||
# Check API is running
|
||||
curl http://localhost:8000/
|
||||
|
||||
# Check health
|
||||
curl http://localhost:8000/api/v1/health
|
||||
|
||||
# Check system info
|
||||
curl http://localhost:8000/api/v1/system
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Models Not Loading
|
||||
|
||||
```bash
|
||||
# Check if models directory exists and has permission
|
||||
ls -la /data/models/
|
||||
|
||||
# Download models manually
|
||||
curl -X POST http://localhost:8000/api/v1/models/download \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"models": ["RealESRGAN_x4plus"]}'
|
||||
```
|
||||
|
||||
### GPU Not Detected
|
||||
|
||||
```bash
|
||||
# Check GPU availability
|
||||
docker compose -f docker-compose.gpu.yml exec api python -c "import torch; print(torch.cuda.is_available())"
|
||||
|
||||
# Check system GPU
|
||||
nvidia-smi
|
||||
```
|
||||
|
||||
### Permission Issues with Volumes
|
||||
|
||||
```bash
|
||||
# Fix volume ownership
|
||||
docker compose exec api chown -R 1000:1000 /data/
|
||||
```
|
||||
|
||||
## Git Workflow
|
||||
|
||||
The project uses Gitea as the remote repository:
|
||||
|
||||
```bash
|
||||
# Add remote
|
||||
git remote add gitea <gitea-repo-url>
|
||||
|
||||
# Commit and push
|
||||
git add .
|
||||
git commit -m "Add feature"
|
||||
git push gitea main
|
||||
```
|
||||
|
||||
Gitea workflows automatically:
|
||||
- Build Docker images (CPU and GPU)
|
||||
- Run tests
|
||||
- Publish to Container Registry
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Model Weights**: Downloaded from GitHub releases (~100MB each)
|
||||
- **GPU Support**: Requires NVIDIA Docker runtime
|
||||
- **Async Processing**: Uses thread pool (configurable workers)
|
||||
- **Tile Processing**: Handles large images by splitting into tiles
|
||||
- **Data Persistence**: Volumes recommended for production
|
||||
Reference in New Issue
Block a user