mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-18 19:21:23 +02:00
f4c49fe8f2
Move queue name constants to separate file (queue-names.ts) to avoid circular dependency between queue.module.ts and processor files. The @Processor decorator evaluates at module load time, and importing constants from queue.module.ts created a circular dependency that resulted in undefined queue names. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
192 lines
4.4 KiB
Markdown
192 lines
4.4 KiB
Markdown
# CLAUDE.md - Mana Image Generation Service
|
|
|
|
## Service Overview
|
|
|
|
AI image generation microservice using FLUX.2 klein 4B model via flux2.c:
|
|
|
|
- **Port**: 3025
|
|
- **Framework**: Python + FastAPI
|
|
- **Model**: FLUX.2 klein 4B (Black Forest Labs)
|
|
- **Backend**: flux2.c (Pure C, MPS accelerated)
|
|
|
|
## Features
|
|
|
|
- **Sub-second generation** on Apple Silicon (M4)
|
|
- **Memory efficient**: ~4-5 GB RAM usage (memory-mapped weights)
|
|
- **Apache 2.0 license**: Commercially usable
|
|
- **4 sampling steps**: Optimized for speed
|
|
- **1024x1024 default resolution**
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Setup (installs flux2.c + downloads model)
|
|
./setup.sh
|
|
|
|
# Development
|
|
source .venv/bin/activate
|
|
FLUX_BINARY=/opt/flux2/flux FLUX_MODEL_DIR=/opt/flux2/model \
|
|
uvicorn app.main:app --host 0.0.0.0 --port 3025 --reload
|
|
|
|
# Production
|
|
../../scripts/mac-mini/setup-image-gen.sh
|
|
|
|
# Test
|
|
curl http://localhost:3025/health
|
|
curl -X POST http://localhost:3025/generate \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"prompt": "A cat in space"}' | jq
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
services/mana-image-gen/
|
|
├── app/
|
|
│ ├── __init__.py
|
|
│ ├── main.py # FastAPI endpoints
|
|
│ └── flux_service.py # flux2.c subprocess wrapper
|
|
├── setup.sh # Setup script
|
|
├── requirements.txt
|
|
├── CLAUDE.md
|
|
└── README.md
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
| Endpoint | Method | Purpose |
|
|
|----------|--------|---------|
|
|
| `/health` | GET | Health check |
|
|
| `/models` | GET | Model info |
|
|
| `/generate` | POST | Generate image |
|
|
| `/images/{filename}` | GET | Serve generated image |
|
|
| `/images/{filename}` | DELETE | Delete image |
|
|
| `/cleanup` | POST | Clean old images |
|
|
|
|
## Generate Request
|
|
|
|
```json
|
|
{
|
|
"prompt": "A beautiful sunset over mountains",
|
|
"width": 1024,
|
|
"height": 1024,
|
|
"steps": 4,
|
|
"seed": -1,
|
|
"output_format": "png"
|
|
}
|
|
```
|
|
|
|
## Generate Response
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"image_url": "/images/abc123.png",
|
|
"prompt": "A beautiful sunset over mountains",
|
|
"width": 1024,
|
|
"height": 1024,
|
|
"steps": 4,
|
|
"seed": 42,
|
|
"generation_time": 0.85
|
|
}
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PORT` | `3025` | Service port |
|
|
| `FLUX_BINARY` | `/opt/flux2/flux` | Path to flux2.c binary |
|
|
| `FLUX_MODEL_DIR` | `/opt/flux2/model` | Path to model weights |
|
|
| `DEFAULT_STEPS` | `4` | Default sampling steps |
|
|
| `DEFAULT_WIDTH` | `1024` | Default image width |
|
|
| `DEFAULT_HEIGHT` | `1024` | Default image height |
|
|
| `GENERATION_TIMEOUT` | `120` | Timeout in seconds |
|
|
| `MAX_PROMPT_LENGTH` | `2000` | Max prompt chars |
|
|
| `CORS_ORIGINS` | (production URLs) | CORS config |
|
|
|
|
## Model Details
|
|
|
|
### FLUX.2 klein 4B
|
|
|
|
- **Parameters**: 4 billion
|
|
- **License**: Apache 2.0 (commercial use allowed)
|
|
- **Download size**: ~16 GB
|
|
- **RAM usage**: ~4-5 GB (memory-mapped)
|
|
- **Optimal steps**: 4 (distilled model)
|
|
- **Release**: January 2026
|
|
|
|
## Integration with Other Apps
|
|
|
|
The service is designed to be used by:
|
|
|
|
- **Picture App** (`apps/picture/`) - AI image generation platform
|
|
- **Chat App** (`apps/chat/`) - Inline image generation
|
|
- **Matrix Bots** - Image generation via chat commands
|
|
- **API Gateway** - Public API access
|
|
|
|
### Example Integration (TypeScript)
|
|
|
|
```typescript
|
|
const response = await fetch('http://localhost:3025/generate', {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({
|
|
prompt: 'A futuristic city at night',
|
|
width: 1024,
|
|
height: 1024,
|
|
}),
|
|
});
|
|
|
|
const result = await response.json();
|
|
const imageUrl = `http://localhost:3025${result.image_url}`;
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- `fastapi` - Web framework
|
|
- `uvicorn` - ASGI server
|
|
- `pillow` - Image processing
|
|
- `flux2.c` - Native binary (installed separately)
|
|
|
|
## Performance
|
|
|
|
On Mac Mini M4 (16 GB):
|
|
|
|
| Resolution | Steps | Time |
|
|
|------------|-------|------|
|
|
| 512x512 | 4 | ~0.3s |
|
|
| 1024x1024 | 4 | ~0.8s |
|
|
| 1024x1024 | 8 | ~1.5s |
|
|
|
|
## Troubleshooting
|
|
|
|
### flux2.c not found
|
|
```bash
|
|
# Verify installation
|
|
ls -la /opt/flux2/flux
|
|
|
|
# Reinstall
|
|
sudo rm -rf /opt/flux2
|
|
./setup.sh
|
|
```
|
|
|
|
### Model not found
|
|
```bash
|
|
# Check model directory
|
|
ls -la /opt/flux2/model/
|
|
|
|
# Re-download
|
|
cd /opt/flux2/src
|
|
./download-model.sh /opt/flux2/model
|
|
```
|
|
|
|
### Out of memory
|
|
- Reduce resolution to 512x512
|
|
- Close other applications
|
|
- The 16 GB Mac Mini should handle 1024x1024 fine
|
|
|
|
### Slow generation
|
|
- Ensure MPS build was used: `make mps`
|
|
- Check Metal GPU is being used
|
|
- Reduce steps (4 is optimal for klein)
|