miku-discord/FACE_DETECTION_API_MIGRATION.md

Face Detection API Migration

Overview

Migrated Miku bot's profile picture feature from local anime-face-detector library to external API service to resolve Python dependency conflicts.

Changes Made

1. Profile Picture Manager (bot/utils/profile_picture_manager.py)

Removed:

• Local anime-face-detector library initialization
• Direct YOLOv3 model loading in bot process
• self.face_detector instance variable
• OpenCV image conversion for face detection

Added:

• API endpoint constant: FACE_DETECTOR_API = "http://anime-face-detector:6078/detect"
• HTTP client for face detection API calls
• Enhanced detection response parsing with bbox, confidence, and keypoints
• Health check on initialization to verify API availability

Updated Methods:

initialize()

• Now checks API health endpoint instead of loading local model
• Graceful fallback if API unavailable

_detect_face(image_bytes, debug)

• Changed signature from (cv_image: np.ndarray) to (image_bytes: bytes)
• Now sends multipart form-data POST to API
• Returns rich detection dict instead of simple tuple:

{
    'center': (x, y),          # Face center coordinates
    'bbox': [x1, y1, x2, y2],  # Bounding box
    'confidence': 0.98,         # Detection confidence
    'keypoints': [...],         # 27 facial landmarks
    'count': 1                  # Number of faces detected
}

_intelligent_crop(image, image_bytes, target_size, debug)

• Added image_bytes parameter for API call
• Updated to use new detection dict format
• Falls back to saliency detection if API call fails

2. Dependencies (bot/requirements.txt)

Removed:

anime-face-detector

This library had conflicts with the bot's CUDA/PyTorch environment.

3. Docker Networking (anime-face-detector-gpu/docker-compose.yml)

Added:

networks:
  miku-discord_default:
    external: true

Allows the face detector container to communicate with Miku bot container.

Architecture

Before (Monolithic):

┌─────────────────────────────┐
│      Miku Bot Container     │
│  ┌───────────────────────┐  │
│  │   anime-face-detector │  │ ❌ Dependency conflicts
│  │   YOLOv3 Model        │  │
│  └───────────────────────┘  │
│  Discord Bot Logic          │
└─────────────────────────────┘

After (Microservices):

┌─────────────────────────────┐      ┌──────────────────────────────┐
│      Miku Bot Container     │      │ Face Detector API Container  │
│                             │      │                              │
│  HTTP Client ──────────────────────▶  FastAPI Endpoint           │
│  Discord Bot Logic          │      │  YOLOv3 Model (GPU)          │
│  Profile Picture Manager    │      │  anime-face-detector lib     │
└─────────────────────────────┘      └──────────────────────────────┘
         ▲                                       │
         │                                       │
         └───── JSON Response with detections ───┘

API Endpoint

Request:

POST http://anime-face-detector:6078/detect
Content-Type: multipart/form-data

file: <image_bytes>

Response:

{
  "detections": [
    {
      "bbox": [629.5, 408.4, 1533.7, 1522.5],
      "confidence": 0.9857,
      "keypoints": [
        [695.4, 644.5, 0.736],
        [662.7, 894.8, 0.528],
        ...
      ]
    }
  ],
  "count": 1,
  "annotated_image": "/app/api/outputs/image_..._annotated.jpg",
  "json_file": "/app/api/outputs/image_..._results.json"
}

Benefits

✅ Dependency Isolation: Face detection library runs in dedicated container with its own Python environment ✅ GPU Optimization: Detector container uses CUDA-optimized YOLOv3 ✅ Easier Updates: Can update face detection model without touching bot code ✅ Better Debugging: Gradio UI at port 7860 for visual testing ✅ Scalability: Multiple services could use the same face detection API ✅ Graceful Degradation: Bot continues working with saliency fallback if API unavailable

Deployment Steps

1. Start Face Detector API

cd /home/koko210Serve/docker/anime-face-detector-gpu
docker-compose up -d

2. Verify API Health

curl http://localhost:6078/health
# Should return: {"status":"healthy","detector_loaded":true}

3. Rebuild Miku Bot (to remove old dependency)

cd /home/koko210Serve/docker/miku-discord
docker-compose build miku-bot
docker-compose up -d

4. Check Logs

# Bot should show:
docker-compose logs miku-bot | grep "face detector"
# Expected: "✅ Anime face detector API connected"

Testing

Test Face Detection Directly:

curl -X POST http://localhost:6078/detect \
  -F "file=@./images/test_miku.jpg" | jq .

Test Profile Picture Change:

# Via API
curl -X POST "http://localhost:8000/profile-picture/change"

# Or via web UI
# Navigate to http://localhost:8000 → Actions → Profile Picture

Troubleshooting

"Face detector API not available"

• Check if container is running: docker ps | grep anime-face-detector
• Check network: docker network ls | grep miku-discord
• Verify API responds: curl http://localhost:6078/health

"No faces detected"

• Check API logs: docker-compose -f anime-face-detector-gpu/docker-compose.yml logs
• Test with Gradio UI: http://localhost:7860
• Bot will fallback to saliency detection automatically

Network Issues

If containers can't communicate:

# Ensure miku-discord network exists
docker network inspect miku-discord_default

# Reconnect anime-face-detector container
cd anime-face-detector-gpu
docker-compose down
docker-compose up -d

Future Enhancements

Potential improvements now that we have a dedicated API:

1. Batch Processing: Detect faces in multiple images simultaneously
2. Face Recognition: Add character identification (not just detection)
3. Expression Analysis: Determine mood from detected faces
4. Quality Scoring: Rate image quality for better selection
5. Custom Models: Easy to swap YOLOv3 for newer models
6. Caching: Store detection results to avoid reprocessing

Files Modified

• ✏️ /miku-discord/bot/utils/profile_picture_manager.py - API integration
• ✏️ /miku-discord/bot/requirements.txt - Removed anime-face-detector
• ✏️ /anime-face-detector-gpu/docker-compose.yml - Added network config

Documentation

• 📄 Face Detector API docs: /anime-face-detector-gpu/README_API.md
• 📄 Setup guide: /anime-face-detector-gpu/SETUP_COMPLETE.md
• 📄 Profile picture feature: /miku-discord/PROFILE_PICTURE_IMPLEMENTATION.md