Re_Backend/docs/VERTEX_AI_INTEGRATION.md

Vertex AI Gemini Integration

Overview

The AI service has been migrated from multi-provider support (Claude, OpenAI, Gemini API) to Google Cloud Vertex AI Gemini using service account authentication. This provides better enterprise-grade security and uses the same credentials as Google Cloud Storage.

Changes Made

1. Package Dependencies

Removed:

• @anthropic-ai/sdk (Claude SDK)
• @google/generative-ai (Gemini API SDK)
• openai (OpenAI SDK)

Added:

• @google-cloud/vertexai (Vertex AI SDK)

2. Service Account Authentication

The AI service now uses the same service account JSON file as GCS:

• Location: credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
• Project ID: re-platform-workflow-dealer
• Default Region: us-central1

3. Configuration

Environment Variables:

# Required (already configured for GCS)
GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json

# Optional (defaults provided)
VERTEX_AI_MODEL=gemini-2.5-flash
VERTEX_AI_LOCATION=asia-south1
AI_ENABLED=true

Admin Panel Configuration:

• AI_ENABLED - Enable/disable AI features
• VERTEX_AI_MODEL - Model name (default: gemini-2.5-flash)
• AI_MAX_REMARK_LENGTH - Maximum characters for conclusion remarks (default: 2000)

4. Available Models

Model Name	Description	Use Case
gemini-2.5-flash	Latest fast model (default)	General purpose, quick responses
gemini-1.5-flash	Previous fast model	General purpose
gemini-1.5-pro	Advanced model	Complex tasks, better quality
gemini-1.5-pro-latest	Latest Pro version	Best quality, complex reasoning

5. Supported Regions

Region Code	Location	Availability
us-central1	Iowa, USA	✅ Default
us-east1	South Carolina, USA	✅
us-west1	Oregon, USA	✅
europe-west1	Belgium	✅
asia-south1	Mumbai, India	✅

Setup Instructions

Step 1: Install Dependencies

cd Re_Backend
npm install

This will install @google-cloud/vertexai and remove old AI SDKs.

Step 2: Verify Service Account Permissions

Ensure your service account (re-bridge-workflow@re-platform-workflow-dealer.iam.gserviceaccount.com) has:

• Vertex AI User role (roles/aiplatform.user)

Step 3: Enable Vertex AI API

1. Go to Google Cloud Console
2. Navigate to APIs & Services > Library
3. Search for "Vertex AI API"
4. Click Enable

Step 4: Verify Configuration

Check that your .env file has:

GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
VERTEX_AI_MODEL=gemini-2.5-flash
VERTEX_AI_LOCATION=us-central1

Step 5: Test the Integration

Start the backend and check logs for:

[AI Service] ✅ Vertex AI provider initialized successfully with model: gemini-2.5-flash

API Interface (Unchanged)

The public API remains the same - no changes needed in controllers or routes:

// Check if AI is available
aiService.isAvailable(): boolean

// Get provider name
aiService.getProviderName(): string

// Generate conclusion remark
aiService.generateConclusionRemark(context): Promise<{
  remark: string;
  confidence: number;
  keyPoints: string[];
  provider: string;
}>

// Reinitialize (after config changes)
aiService.reinitialize(): Promise<void>

Troubleshooting

Error: "Module not found: @google-cloud/vertexai"

Solution:

npm install @google-cloud/vertexai

Error: "Service account key file not found"

Solution:

• Verify file exists at: credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
• Check GCP_KEY_FILE path in .env is correct
• Ensure file has read permissions

Error: "Model was not found or your project does not have access"

Solution:

• Verify Vertex AI API is enabled in Google Cloud Console
• Check model name is correct (e.g., gemini-2.5-flash)
• Ensure model is available in your selected region
• Verify service account has roles/aiplatform.user role

Error: "Permission denied"

Solution:

• Verify service account has Vertex AI User role
• Check service account key hasn't been revoked
• Regenerate service account key if needed

Error: "API not enabled"

Solution:

• Enable Vertex AI API in Google Cloud Console
• Wait a few minutes for propagation
• Restart the backend service

Migration Notes

What Changed

• ✅ Removed multi-provider support (Claude, OpenAI, Gemini API)
• ✅ Now uses Vertex AI Gemini exclusively
• ✅ Uses service account authentication (same as GCS)
• ✅ Simplified configuration (no API keys needed)

What Stayed the Same

• ✅ Public API interface (aiService methods)
• ✅ Conclusion generation functionality
• ✅ Admin panel configuration structure
• ✅ Error handling and logging

Backward Compatibility

• ✅ Existing code using aiService will work without changes
• ✅ Conclusion controller unchanged
• ✅ Admin panel can still enable/disable AI features
• ✅ Configuration cache system still works

Verification Checklist

• @google-cloud/vertexai package installed
• Service account key file exists and is valid
• Vertex AI API is enabled in Google Cloud Console
• Service account has Vertex AI User role
• .env file has correct GCP_PROJECT_ID and GCP_KEY_FILE
• Backend logs show successful initialization
• AI conclusion generation works for test requests

Support

For issues or questions:

1. Check backend logs for detailed error messages
2. Verify Google Cloud Console settings
3. Ensure service account permissions are correct
4. Test with a simple request to isolate issues