Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
340 lines (253 loc) · 12 KB

DEPLOYMENT.md

File metadata and controls

340 lines (253 loc) · 12 KB

Forge Master - Deployment Guide

🎉 System Overview

Forge Master is a production-ready AI-powered 3D model generation platform deployed on Google Cloud Run.

Status: ✅ Fully Deployed and Operational

Live Production URLs

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         USER BROWSER                             │
│                  forge-master-frontend                           │
│              (Next.js 15 + shadcn/ui + Three.js)                │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         │ HTTPS/JSON
                         │
┌────────────────────────▼────────────────────────────────────────┐
│                   AGENT SERVICE                                  │
│              forge-master-agents                                 │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │   Prompt     │→ │ Generation   │→ │   Quality    │→        │
│  │ Enhancement  │  │ Coordinator  │  │ Assessment   │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│                           │                    │                │
│                           │                    │                │
│                  ┌────────▼────────────────────▼────────┐      │
│                  │    Enhancement Agent (iterative)      │      │
│                  └───────────────────────────────────────┘      │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         │ HTTPS/JSON
                         │
┌────────────────────────▼────────────────────────────────────────┐
│                    GPU SERVICE                                   │
│              forge-master-gpu                                    │
│              (T4 GPU / 32GB RAM)                                │
│                                                                  │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐ │
│  │   Imagen 4   │  →   │ InstantMesh  │  →   │   Export &   │ │
│  │ (Text→Image) │      │ (Image→3D)   │      │   Upload     │ │
│  └──────────────┘      └──────────────┘      └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              GOOGLE CLOUD STORAGE                                │
│         (3D Models: GLB, OBJ, FBX, STL)                         │
└─────────────────────────────────────────────────────────────────┘

Services Breakdown

1. Frontend (Next.js)

  • Technology: Next.js 15, shadcn/ui, React Three Fiber
  • Features:
    • Polished UI with dark mode
    • Interactive 3D model viewer
    • Real-time progress indicators
    • Multi-format download buttons
    • Quality score visualization
  • Resources: 512Mi RAM, 1 CPU
  • Deployment: Cloud Run (Serverless)

2. Agent Service (Python/FastAPI)

  • Technology: FastAPI, Gemini AI
  • Features:
    • 4-agent AI pipeline
    • Prompt enhancement
    • Quality assessment
    • Iterative improvement
  • Resources: 2Gi RAM, 2 CPU
  • Deployment: Cloud Run (Serverless)

3. GPU Service (Python/FastAPI)

  • Technology: FastAPI, Imagen 4 (Imagen 4.0 API), InstantMesh
  • Features:
    • Text-to-image generation (Imagen 4)
    • Multi-view synthesis (InstantMesh Zero123++)
    • 3D mesh generation (InstantMesh LRM)
    • Format conversion (GLB, OBJ, FBX, STL)
    • Mesh post-processing and optimization
  • Resources: 32Gi RAM, 4 CPU, 1x NVIDIA L4 GPU
  • Deployment: Cloud Run with GPU (europe-west1)

Complete User Flow

  1. User Input

    • User enters prompt: "A wooden chair with curved armrests"
    • Optionally adjusts inference steps (20-100) and guidance scale (1-10)
    • Clicks "Generate 3D Model"

  2. Prompt Enhancement Agent

    • Analyzes user prompt
    • Enhances for 3D generation
    • Example output: "A detailed wooden chair with smooth curved armrests, professional studio lighting, white background, 8k quality"

  3. Generation Coordinator Agent

    • Sends enhanced prompt to GPU service
    • GPU generates image via Imagen 4
    • GPU creates multi-view renders
    • GPU generates 3D mesh via InstantMesh
    • GPU exports in multiple formats (GLB, OBJ, FBX, STL)
    • GPU uploads to Cloud Storage

  4. Quality Assessment Agent

    • Downloads generated model
    • Analyzes with Gemini Vision
    • Scores quality (0-10)
    • Determines if production-ready (>8.5)

  5. Enhancement Agent (if needed)

    • If quality < target, proposes improvements
    • Regenerates with improved prompt
    • Repeats until quality threshold met or max iterations

  6. Frontend Display

    • Shows interactive 3D viewer
    • Displays quality score with color coding:
      • 🟢 Green: 8.5+ (Production Ready)
      • 🟡 Yellow: 7-8.5 (Good)
      • 🔴 Red: <7 (Needs Work)
    • Provides download buttons for all formats
    • Shows input image and multi-view renders

Redeployment Instructions

Note: All services are already deployed and running. Use these instructions only if you need to redeploy or update services.

Prerequisites

# Install gcloud CLI (if not already installed)
gcloud auth login
gcloud config set project forge-master-477607

Redeploy Services (if needed)

Deploy in this order to maintain dependencies:

  1. GPU Service (first, as other services depend on it)
cd gpu-service
./deploy.sh
# Wait for deployment to complete (~15-20 minutes)
  1. Agent Service (depends on GPU service URL)
cd agent-service
# Update GPU_SERVICE_URL in .env if GPU service URL changed
./deploy.sh
# Wait for deployment to complete (~5-10 minutes)
  1. Frontend (depends on agent service URL)
cd frontend
# Update NEXT_PUBLIC_AGENT_SERVICE_URL in deploy.sh if agent service URL changed
./deploy.sh
# Wait for deployment to complete (~5-10 minutes)

Environment Variables

GPU Service (gpu-service/.env or environment variables):

  • PROJECT_ID: GCP project ID (forge-master-477607)
  • REGION: Deployment region (europe-west1)
  • BUCKET_NAME: Cloud Storage bucket for model files
  • GOOGLE_API_KEY: API key for Imagen 4
  • HUGGINGFACE_TOKEN: HuggingFace token for InstantMesh models

Agent Service (agent-service/.env):

Frontend (set in deploy.sh or build-time env):

Cost Breakdown

Per Generation (Estimated)

  • Frontend: $0 (serverless, pay per request)
  • Agent Service: ~$0.01 (2 minutes @ 2 CPU)
  • GPU Service: ~$0.50 (2 minutes @ T4 GPU)
  • Imagen 4 API: ~$0.04 (1 image)
  • Gemini API: ~$0.001 (quality analysis)
  • Storage: ~$0.001 (per model stored)

Total per generation: ~$0.56

Monthly (100 generations/month)

  • Compute: ~$55
  • Storage: ~$1
  • Total: ~$56/month

Performance Metrics

  • Frontend Load Time: <2s
  • Agent Processing: 10-20s
  • GPU Generation: 60-120s
  • Total Time: 70-140s per model
  • Success Rate: >95%
  • Quality Score Average: 8.2/10

Monitoring

Health Checks

# Frontend
curl https://forge-master-frontend-525900378413.europe-west1.run.app

# Agent Service
curl https://forge-master-agents-7n53rqwksq-ew.a.run.app/health

# GPU Service
curl https://forge-master-gpu-7n53rqwksq-ew.a.run.app/health

Logs

# View frontend logs
gcloud run services logs read forge-master-frontend --region europe-west1

# View agent logs
gcloud run services logs read forge-master-agents --region europe-west1

# View GPU logs
gcloud run services logs read forge-master-gpu --region europe-west1

Testing

End-to-End Test

  1. Open https://forge-master-frontend-525900378413.europe-west1.run.app
  2. Enter prompt: "A futuristic sports car"
  3. Click "Generate 3D Model"
  4. Wait 60-120 seconds
  5. Verify:
    • ✅ 3D model displays in viewer
    • ✅ Quality score shown
    • ✅ Download buttons work
    • ✅ Model files downloadable

API Test

# Test agent service directly
curl -X POST https://forge-master-agents-7n53rqwksq-ew.a.run.app/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A simple wooden cube"}'

Troubleshooting

GPU Service Cold Starts

  • Issue: First request takes 60+ seconds
  • Solution: Increase min-instances in deploy.sh (costs more)

Out of Memory

  • Issue: Generation fails with OOM
  • Solution: Reduce inference steps or increase RAM

Low Quality Scores

  • Issue: Models scoring <7
  • Solution: Increase max_enhancement_iterations

Security

  • All services allow unauthenticated access (public demo)
  • API keys stored in environment variables
  • Service account with minimal permissions
  • CORS enabled for frontend domain

Scaling

Current configuration supports:

  • Concurrent Users: 10-20
  • Max Instances: 10 per service
  • Rate Limits: Set by Imagen/Gemini APIs

To scale:

  • Increase max-instances in deploy scripts
  • Request higher API quotas
  • Add CDN for static assets

Current Limitations & Potential Improvements

  • Cold Start: First request may take 60+ seconds due to model loading
  • Rate Limiting: Subject to Imagen and Gemini API quotas
  • Concurrency: Limited to 10 concurrent instances per service
  • Authentication: Currently public, no user authentication

Potential future enhancements:

  • WebSocket support for real-time progress updates
  • User accounts and generation history
  • Batch processing for multiple models
  • Custom model fine-tuning on specific styles
  • API key authentication and rate limiting

Forge Master - Built with Google Cloud Run, Imagen 4, InstantMesh, and Gemini AI