README.md

ChatGPT Oasis Model Inference API - Hugging Face Spaces (Docker)

A FastAPI-based inference server for vision models (Oasis 500M and ViT-L-20) deployed on Hugging Face Spaces using Docker SDK with local model files.

🚀 Live Demo

This API is deployed on Hugging Face Spaces and can be accessed at:

https://your-username-chatgpt-oasis.hf.space

📋 API Endpoints

Base URL

https://your-username-chatgpt-oasis.hf.space

Available Endpoints

1. API Information

• GET /
• Returns API information and usage instructions

2. Health Check

• GET /health
• Returns server health status, model loading status, and model file presence

3. List Models

• GET /models
• Returns information about available models and their file status

4. Inference (Base64)

• POST /inference
• Accepts base64 encoded images
• Request body:

  {
    "image": "base64_encoded_image_string",
    "model_name": "oasis500m"  // or "vit-l-20"
  }
  

5. Inference (File Upload)

• POST /upload_inference
• Accepts image file uploads
• Form data:
  • file: Image file
  • model_name: Model to use (optional, defaults to "oasis500m")

6. Simple Prediction (Gradio Compatible)

• POST /predict
• Simple file upload endpoint for easy integration

🔧 Usage Examples

Using Python Requests

import requests
import base64
from PIL import Image
import io

# Your Hugging Face Spaces URL
SPACE_URL = "https://your-username-chatgpt-oasis.hf.space"

# Method 1: File Upload
def predict_with_file_upload(image_path, model_name="oasis500m"):
    with open(image_path, 'rb') as f:
        files = {'file': f}
        data = {'model_name': model_name}
        
        response = requests.post(
            f"{SPACE_URL}/upload_inference",
            files=files,
            data=data,
            timeout=120
        )
        return response.json()

# Method 2: Base64 Encoding
def predict_with_base64(image_path, model_name="oasis500m"):
    # Load and encode image
    image = Image.open(image_path)
    buffer = io.BytesIO()
    image.save(buffer, format="JPEG")
    image_base64 = base64.b64encode(buffer.getvalue()).decode()
    
    # Make request
    response = requests.post(
        f"{SPACE_URL}/inference",
        json={
            "image": image_base64,
            "model_name": model_name
        },
        timeout=120
    )
    return response.json()

# Example usage
result = predict_with_file_upload("your_image.jpg", "oasis500m")
print(result)

Using cURL

# File upload inference
curl -X POST "https://your-username-chatgpt-oasis.hf.space/upload_inference" \
  -H "accept: application/json" \
  -F "file=@your_image.jpg" \
  -F "model_name=oasis500m"

# Health check
curl "https://your-username-chatgpt-oasis.hf.space/health"

# API documentation
curl "https://your-username-chatgpt-oasis.hf.space/docs"

Using JavaScript/Fetch

// File upload inference
async function predictImage(file, modelName = 'oasis500m') {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('model_name', modelName);
    
    const response = await fetch('https://your-username-chatgpt-oasis.hf.space/upload_inference', {
        method: 'POST',
        body: formData
    });
    
    return await response.json();
}

// Base64 inference
async function predictImageBase64(imageBase64, modelName = 'oasis500m') {
    const response = await fetch('https://your-username-chatgpt-oasis.hf.space/inference', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            image: imageBase64,
            model_name: modelName
        })
    });
    
    return await response.json();
}

📊 Response Format

All inference endpoints return the same response format:

{
  "predictions": [
    {
      "label": "predicted_class_name",
      "confidence": 0.95
    },
    {
      "label": "second_predicted_class",
      "confidence": 0.03
    }
  ],
  "model_used": "oasis500m",
  "confidence_scores": [0.95, 0.03, 0.01, 0.005, 0.005]
}

🤖 Available Models

Oasis 500M

• Type: Vision Transformer
• Size: ~500M parameters
• File: oasis500m.safetensors
• Use Case: General image classification
• Performance: High accuracy on ImageNet

ViT-L-20

• Type: Vision Transformer Large
• Size: ~300M parameters
• File: vit-l-20.safetensors
• Use Case: High-performance image classification
• Performance: State-of-the-art on many benchmarks

🔍 API Documentation

Once deployed, you can access:

• Interactive API Docs: https://your-username-chatgpt-oasis.hf.space/docs
• Alternative API Docs: https://your-username-chatgpt-oasis.hf.space/redoc

🚀 Deployment on Hugging Face Spaces (Docker SDK)

Prerequisites

1. Hugging Face account
2. Local model files (.safetensors)
3. Git repository with your code

Steps to Deploy

1. Create a new Space on Hugging Face

   • Go to Hugging Face Spaces
   • Click "Create new Space"
   • Choose "Docker" as the SDK
   • Set visibility (public/private)

2. Prepare your files

   • Dockerfile - Container configuration
   • app.py - Main FastAPI application
   • requirements.txt - Python dependencies
   • README.md - This documentation
   • oasis500m.safetensors - Oasis model weights
   • vit-l-20.safetensors - ViT model weights

3. Upload files to your Space

   • Upload all files to the Space repository
   • The Dockerfile will copy the model files into the container

4. Configure the Space

   • Set appropriate hardware requirements (CPU/GPU)
   • Ensure sufficient memory for model loading

5. Deploy

   • Push your code to the Space repository
   • Hugging Face will automatically build the Docker image and deploy

Space Configuration

Your Space will need:

• Hardware: CPU (or GPU for faster inference)
• Memory: At least 8GB RAM (for both models)
• Storage: Sufficient space for model files (~3GB)

📁 File Structure

your-space/
├── Dockerfile              # Container configuration
├── app.py                  # FastAPI application
├── requirements.txt        # Python dependencies
├── README.md              # Documentation
├── .dockerignore          # Docker ignore file
├── oasis500m.safetensors  # Oasis model weights
└── vit-l-20.safetensors   # ViT model weights

⚡ Performance Tips

• Model Loading: Models are loaded once when the container starts
• Local Files: Using local .safetensors files avoids download time
• Caching: Consider implementing response caching for repeated requests
• Batch Processing: For multiple images, send them sequentially
• Image Size: Optimize image size before sending (models expect specific dimensions)

🔧 Troubleshooting

Common Issues

1. Model Loading Time

   • First request may take longer as models load from local files
   • Check /health endpoint for model status

2. Memory Issues

   • Use smaller images
   • Process one image at a time
   • Consider using only one model at a time

3. Model File Issues

   • Ensure .safetensors files are uploaded to the Space
   • Check /health endpoint for file presence status

4. Timeout Errors

   • Increase timeout settings in your client
   • Check Space logs for errors

Getting Help

• Check the Space logs in Hugging Face dashboard
• Use the /health endpoint to verify model and file status
• Test with the /docs interactive interface

📝 License

This project is for inference purposes. Please respect the licenses of the underlying models (Oasis and ViT).

🤝 Contributing

Feel free to submit issues and enhancement requests!