Skip to content

README.md

Latest commit

 

History

History
178 lines (131 loc) · 3.73 KB

README.md

File metadata and controls

178 lines (131 loc) · 3.73 KB

Forge Master GPU Service

High-quality 3D model generation using Imagen 4 and InstantMesh.

Features

  • Text-to-Image: Imagen 4 for high-quality reference images
  • Image-to-3D: InstantMesh for production-ready 3D meshes
  • Multi-format Export: GLB, OBJ, STL
  • Cloud Storage: Automatic upload to GCS
  • GPU-Accelerated: NVIDIA L4 GPU support

Architecture

Text Prompt → Imagen 4 → Reference Image
              ↓
           InstantMesh
              ↓
    Multi-view Generation (6 views)
              ↓
       3D Reconstruction
              ↓
      Post-processing
              ↓
    Export (GLB, OBJ, STL)
              ↓
     Cloud Storage Upload

Local Development

Requirements

  • Python 3.11+
  • CUDA 12.1+ (for GPU)
  • Docker (optional)

Setup

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GOOGLE_API_KEY=your-api-key
export PROJECT_ID=your-project-id
export BUCKET_NAME=your-bucket-name

# Run service
python main.py

Test Endpoints

# Health check
curl http://localhost:8080/health

# Test Imagen only
curl -X POST http://localhost:8080/test/imagen

# Full generation
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"image_generation_prompt": "A medieval sword"}'

Security

This service is protected by Cloud Run IAM authentication.

  • Public access is disabled (--no-allow-unauthenticated)
  • Only the agent-service can invoke this service
  • Requires valid service account identity token in Authorization header
  • Direct API calls will return 403 Forbidden

This prevents unauthorized access to expensive GPU operations (~$0.50 per generation).

Deployment

Deploy with GPU (Production)

# Set environment variables
export GOOGLE_API_KEY=your-api-key
export PROJECT_ID=your-project-id
export BUCKET_NAME=your-bucket-name

# Deploy
./deploy.sh

# After deployment, remove public access (if not already done)
gcloud run services remove-iam-policy-binding forge-master-gpu \
  --region=europe-west1 \
  --member="allUsers" \
  --role="roles/run.invoker"

# Grant agent-service permission to invoke
gcloud run services add-iam-policy-binding forge-master-gpu \
  --region=europe-west1 \
  --member="serviceAccount:YOUR-SERVICE-ACCOUNT@developer.gserviceaccount.com" \
  --role="roles/run.invoker"

Deploy without GPU (Testing)

# For quick testing without GPU costs
./deploy-test.sh

API Reference

POST /generate

Generate 3D model from text prompt.

Request:

{
  "image_generation_prompt": "A medieval steel sword",
  "num_inference_steps": 75,
  "guidance_scale": 4.0
}

Response:

{
  "id": "uuid",
  "status": "success",
  "urls": {
    "glb": "https://storage.googleapis.com/...",
    "obj": "https://storage.googleapis.com/...",
    "stl": "https://storage.googleapis.com/..."
  },
  "stats": {
    "vertices": 50000,
    "faces": 100000,
    "is_watertight": true
  },
  "created_at": "2025-01-01T00:00:00"
}

Configuration

Environment variables:

  • GOOGLE_API_KEY: Google AI API key (required)
  • PROJECT_ID: GCP project ID (required)
  • BUCKET_NAME: GCS bucket name (required)
  • REGION: GCP region (default: europe-west1)
  • CUDA_AVAILABLE: Enable GPU (default: true)

Performance

  • Text-to-Image: ~3-5 seconds (Imagen 4)
  • Multi-view Generation: ~15-20 seconds (InstantMesh)
  • 3D Reconstruction: ~5-10 seconds
  • Total: ~25-35 seconds per model

Troubleshooting

Out of Memory

Reduce batch size or image resolution in config.

Slow Generation

Check GPU is enabled: curl http://your-service/health

Model Download Issues

Models are cached on first use. First generation may take 2-3 minutes.