README.md

metadata

title: FaceMatch Azure Dev
emoji: 🐨
colorFrom: red
colorTo: green
sdk: docker
pinned: false

FaceMatch FastAPI

A face matching and recommendation system built with FastAPI, InsightFace, and Azure Blob Storage. This application provides personalized face recommendations based on user preferences and similarity matching.

Features

• Face Detection & Embedding: Uses InsightFace for robust face detection and embedding extraction
• Similarity Matching: Finds similar faces using cosine similarity on face embeddings
• Personalized Recommendations: Learns from user likes/dislikes to provide personalized matches
• Gender Filtering: Filter recommendations by gender (male, female, or all)
• Azure Integration: Stores images and embeddings in Azure Blob Storage
• FastAPI: Modern, fast web framework with automatic API documentation

API Endpoints

Core Endpoints

• GET / - Health check and welcome message
• POST /api/init_user - Initialize a new user session
• GET /api/get_training_images - Get training images for user preference learning
• POST /api/record_preference - Record user like/dislike preferences
• POST /api/get_matches - Get personalized matches based on user preferences
• POST /api/get_recommendations - Get recommendations based on query images
• POST /api/extract_embeddings - Extract embeddings from all images (admin)

API Documentation

Visit /docs for interactive Swagger UI documentation when running locally.

Local Setup

Prerequisites

• Python 3.8+
• Azure Blob Storage account
• Azure credentials

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd Facematch_Dev
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure Azure credentials

   Set your Azure credentials as environment variables:

   export AZURE_STORAGE_CONNECTION_STRING="your_connection_string"
   export AZURE_CONTAINER_NAME="your_container_name"
   

   Or create a config.py file with your credentials.

4. Run the application

   python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
   

5. Access the API

   • API: http://localhost:8000
   • Documentation: http://localhost:8000/docs

Usage Examples

Get Recommendations

Direct Format:

curl -X POST "http://localhost:8000/api/get_recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "query_images": [
      "https://your-azure-url/image1.jpg",
      "https://your-azure-url/image2.jpg"
    ],
    "gender": "female",
    "top_n": 5
  }'

Hugging Face Format:

curl -X POST "http://localhost:8000/api/get_recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query_images": [
        "https://your-azure-url/image1.jpg",
        "https://your-azure-url/image2.jpg"
      ],
      "gender": "female",
      "top_n": 5
    }
  }'

Initialize User Session

curl -X POST "http://localhost:8000/api/init_user"

Record Preferences

curl -X POST "http://localhost:8000/api/record_preference" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "your_user_id",
    "image_url": "https://your-azure-url/image.jpg",
    "preference": "like"
  }'

Hugging Face Spaces Deployment

1. Create a Hugging Face Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Choose "FastAPI" as the SDK
4. Set visibility (public or private)
5. Create the space

2. Configure Secrets

In your Hugging Face Space settings, add these secrets:

• AZURE_STORAGE_CONNECTION_STRING: Your Azure connection string
• AZURE_CONTAINER_NAME: Your Azure container name

3. Upload Files

Upload these files to your Hugging Face Space:

• main.py - FastAPI application
• handler.py - Face matching logic
• requirements.txt - Dependencies
• config.py - Configuration (if using file-based config)

4. Deploy

The space will automatically build and deploy your FastAPI application.

5. Access Your API

Your API will be available at:

https://your-username-your-space-name.hf.space

Azure Setup

Required Azure Resources

1. Storage Account: For storing images and embeddings
2. Blob Container: Organized with folders:
   • ai-images/men/ - Training images for men
   • ai-images/women/ - Training images for women
   • profile-media/ - Images to search for matches

Configuration

The application expects these Azure settings:

# In config.py or environment variables
AZURE_STORAGE_CONNECTION_STRING = "your_connection_string"
AZURE_CONTAINER_NAME = "your_container_name"

File Structure

Facematch_Dev/
├── main.py                 # FastAPI application
├── handler.py              # Face matching logic
├── config.py               # Configuration
├── requirements.txt        # Dependencies
├── README.md              # This file
├── templates/             # HTML templates (if needed)
└── user_preferences.json  # User preferences storage

Performance Notes

• Local Development: Runs on CPU, suitable for testing
• Hugging Face Spaces: Runs on GPU, much faster for production
• Embedding Extraction: Run /api/extract_embeddings after uploading new images
• Caching: Embeddings are cached in Azure for faster subsequent queries

Troubleshooting

Common Issues

1. Face Detection Fails: Some images may not contain detectable faces
2. Azure Connection: Ensure credentials are correctly set
3. Memory Issues: Large image collections may require more memory on Hugging Face

Debug Mode

Enable debug logging by setting environment variable:

export DEBUG=1

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

[Add your license information here]

Support

For issues and questions:

• Create an issue on GitHub
• Check the API documentation at /docs
• Review the debug logs for detailed error information