Thinh11062005/Carafe_Yolov12

Drill Bit Defect Detection - Hugging Face Spaces Deployment

This project deploys a drill bit defect detection model using YOLOv12 with CARAFE to Hugging Face Spaces with FastAPI backend.

🚀 Deployment Instructions

Prerequisites

• —Hugging Face account with access token (write permissions)
• —Git installed
• —HF CLI (optional, but recommended)

Method 1: Using Git (Recommended)

1. 1.Clone the Space

git clone https://huggingface.co/spaces/Thinh11062005/Carafe_Yolov12
cd Carafe_Yolov12

1. 1.Copy all files

# Copy all files from huggingface_space directory
cp -r /Users/mac/Detect_Drill_Bit/huggingface_space/* ./

1. 1.Commit and push

git add .
git commit -m "Deploy drill bit detection app with FastAPI backend"
git push -u origin main

When prompted for password, use your Hugging Face access token.

Method 2: Using HF CLI

1. 1.Install HF CLI

curl -LsSf https://hf.co/cli/install.sh | bash

1. 1.Download the Space

hf download Thinh11062005/Carafe_Yolov12 --repo-type=space
cd Carafe_Yolov12

1. 1.Copy and deploy

# Copy all files
cp -r /Users/mac/Detect_Drill_Bit/huggingface_space/* ./

# Commit and push
git add .
git commit -m "Deploy drill bit detection app with FastAPI backend"
git push -u origin main

Method 3: Using Web UI

1. 1.Go to your Space: https://huggingface.co/spaces/Thinh11062005/Carafe_Yolov12
2. 2.Click on "Files" tab
3. 3.Upload all files:
4. 4.app.py
5. 5.index.html
6. 6.requirements.txt
7. 7.models/best_carafe.pt
8. 8.Click "Commit changes to main"
9. 9.Add a commit message and click "Commit"

📁 File Structure

Carafe_Yolov12/
├── app.py              # FastAPI backend server
├── index.html          # Frontend web application
├── requirements.txt    # Python dependencies
├── README.md          # This file
└── models/             # Model weights directory
    └── best_carafe.pt  # YOLOv12 + CARAFE model

🎨 Features

The web application includes:

• —FastAPI backend for real-time inference
• —Drag & drop image upload
• —Multiple model selection:
• —YOLOv12n + CARAFE (Recommended)
• —YOLOv12n + DySample
• —YOLOv12n (After/Before Augmentation)
• —YOLOv12n + HQNN Fusion
• —Baseline YOLO models (v8n, v9n, v10n, v11n, v12n, v26n)
• —Real-time defect detection with bounding boxes
• —Confidence scores for each detection
• —Responsive design for mobile and desktop

🔧 Defect Classes

The model can detect 5 types of drill bit defects:

1. 1.Broken - Drill bit is broken or fractured
2. 2.Chipped - Small pieces chipped off the edge
3. 3.Scratched - Surface scratches or marks
4. 4.Severe_Rust - Heavy rust or corrosion
5. 5.Tip_Wear - Wear at the drill bit tip

🔌 API Endpoints

POST /predict

Run inference on uploaded image.

Parameters:

• —file: Image file (JPG, PNG)
• —model: Model selection (carafe, dysample, after_aug, etc.)
• —conf_threshold: Confidence threshold (default: 0.25)

Response:

{
  "success": true,
  "detections": [
    {
      "class": "Scratched",
      "confidence": 0.92,
      "bbox": {"x": 50, "y": 80, "width": 200, "height": 150}
    }
  ],
  "model_used": "carafe",
  "image_size": {"width": 640, "height": 480}
}

GET /health

Health check endpoint.

GET /models

List available models.

🌐 Access the Deployed App

After deployment, your app will be available at:

https://huggingface.co/spaces/Thinh11062005/Carafe_Yolov12

📝 Adding More Models

To add more models:

1. 1.Copy model weights to models/ directory:

cp /path/to/model.pt ./models/best_[model_name].pt

1. 1.Update app.py to map model selection to file path (already configured for common models)

1. 1.Commit and push changes

🔗 Useful Links

• —Hugging Face Spaces Documentation
• —FastAPI Documentation
• —Hugging Face Tokens

🧪 Testing Locally

To test the app locally before deploying:

1. 1.Navigate to the huggingface_space directory

cd /Users/mac/Detect_Drill_Bit/huggingface_space

1. 1.Install dependencies

pip install -r requirements.txt

1. 1.Run the FastAPI server

python app.py

Note: Use python app.py instead of fastapi dev to avoid multiprocessing issues with custom modules (CARAFE, DySample).

1. 1.Open browser The app will be available at: http://localhost:7860

1. 1.Test the API
2. 2.Upload an image
3. 3.Select a model
4. 4.Click "Detect Defects"
5. 5.View bounding boxes and detections

� Deploying to Hugging Face Spaces

Method 1: Using Git (Recommended)

1. 1.Create a new Space on Hugging Face
2. 2.Go to https://huggingface.co/spaces
3. 3.Click "Create new Space"
4. 4.Select "Docker" as SDK
5. 5.Name your space (e.g., drill-bit-detection)
6. 6.Choose "Public" or "Private"

1. 1.Clone the Space

git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

1. 1.Copy all files from huggingface_space directory

cp -r /Users/mac/Detect_Drill_Bit/huggingface_space/* ./

1. 1.Create Dockerfile (if not exists)

cat > Dockerfile << 'EOF'
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libgl1-mesa-glx \
    libglib2.0-0 \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements and install
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY . .

# Expose port
EXPOSE 7860

# Run the application
CMD ["python", "app.py"]
EOF

1. 1.Commit and push

git add .
git commit -m "Deploy drill bit detection with CARAFE"
git push

Method 2: Using Hugging Face CLI

1. 1.Install HF CLI

pip install huggingface_hub

1. 1.Login to Hugging Face

huggingface-cli login

1. 1.Upload files

cd /Users/mac/Detect_Drill_Bit/huggingface_space
huggingface-cli upload YOUR_USERNAME/YOUR_SPACE_NAME . --repo-type=space

Method 3: Using Web UI

1. 1.Go to your Space on Hugging Face
2. 2.Click on "Files" tab
3. 3.Upload all files:
4. 4.app.py
5. 5.index.html
6. 6.requirements.txt
7. 7.custom_modules.py
8. 8.Dockerfile
9. 9.models/best_carafe.pt
10. 10.Click "Commit changes to main"

Important Notes for Hugging Face Deployment

1. 1.Dockerfile is required for custom modules (CARAFE) to work properly
2. 2.Model weights must be uploaded to models/ directory
3. 3.Custom modules (custom_modules.py) must be included
4. 4.Port 7860 is the standard port for Hugging Face Spaces
5. 5.GPU Space is recommended for faster inference (select "GPU" when creating Space)

GPU Space Setup (Recommended)

When creating your Space:

• —Select "GPU" as hardware (T4 or A10G)
• —This will significantly speed up inference
• —GPU Space has a monthly free tier limit

Troubleshooting

If you encounter issues on Hugging Face:

1. 1.Check the "Logs" tab in your Space
2. 2.Ensure custom_modules.py is uploaded
3. 3.Verify model weights are in models/ directory
4. 4.Make sure Dockerfile is present and correct

�� Support

For issues or questions, contact the project maintainer.