Vertex AI

Edit this page

Google Cloud Vertex AI is a machine learning platform that provides access to Google's Gemini models and other AI services. The Symfony AI Platform component provides a bridge to interact with Vertex AI models.

For comprehensive information about Vertex AI, see the Vertex AI documentation and Vertex AI API reference.

Installation

To use Vertex AI with Symfony AI Platform, you need to install the platform component and set up Google Cloud authentication:

1
$ composer require symfony/ai-platform

Setup

Authentication

Vertex AI supports the following authentication methods:

1. Application Default Credentials (ADC)

Follow the Google cloud authentication guide to set up your credentials.

For ADC, install the Google Cloud SDK and authenticate:

1
$ gcloud auth application-default login

For detailed authentication setup, see Setting up authentication for Vertex AI.

Configure your Google Cloud project and location:

1
2
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

Basic usage example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
use Symfony\AI\Platform\Bridge\VertexAi\Factory;
use Symfony\AI\Platform\Message\Message;
use Symfony\AI\Platform\Message\MessageBag;

$platform = Factory::createPlatform(
    $_ENV['GOOGLE_CLOUD_LOCATION'],
    $_ENV['GOOGLE_CLOUD_PROJECT'],
    httpClient: $httpClient
);

$messages = new MessageBag(
    Message::ofUser('Hello, how are you?')
);

$result = $platform->invoke('gemini-2.5-flash', $messages);
echo $result->asText();

2. Service Account Key

Similar to the first approach, but instead of authenticating with the `gcloud` command, you provide the service account key directly using an environment variable:

1
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

3. API Key (Project-Scoped Endpoint)

You can provide an API key together with a location and project ID. This still uses the project-scoped endpoint but authenticates with the API key instead of ADC:

1
2
3
4
5
$platform = Factory::createPlatform(
    $_ENV['GOOGLE_CLOUD_LOCATION'],
    $_ENV['GOOGLE_CLOUD_PROJECT'],
    apiKey: $_ENV['GOOGLE_CLOUD_VERTEX_API_KEY'],
);

To get an API key, visit: Vertex AI Studio (API keys).

4. API Key (Global Endpoint)

If you only provide an API key without a location or project ID, the platform uses the VertexAI global endpoint (https://aiplatform.googleapis.com/v1/publishers/google/models/...). This is the simplest setup and does not require the google/auth package:

1
2
3
$platform = Factory::createPlatform(
    apiKey: $_ENV['GOOGLE_CLOUD_VERTEX_API_KEY'],
);

Caution

API keys only identify the calling project for billing purposes. They do not provide identity-based access control. For production workloads that require IAM, audit logging, or data residency, use the project-scoped endpoint with ADC or a service account.

Model Availability by Location

Note

Model availability varies by Google Cloud location. Not all models are available in all regions.

Common model availability:

  • us-central1: Most comprehensive model availability, recommended for development
  • us-east1: Good model availability
  • europe-west1: Good model availability
  • global: Limited model availability, some newer models may not be available

Troubleshooting Model Availability

If you encounter an error like:

1
Publisher Model `projects/your-project/locations/global/publishers/google/models/gemini-2.0-flash-lite` not found

This typically means:

  1. The model is not available in your specified location
  2. Try switching to a different location like us-central1
  3. Use an alternative model that's available in your location
  4. Check the Google Cloud Console for Vertex AI for model availability in your region
Checking Model Availability

You can check which models are available in your location using the Google Cloud Console or gcloud CLI:

1
gcloud ai models list --region=us-central1

Location Configuration

Configure your location in your environment file:

1
2
3
4
5
# Recommended: Use a region with comprehensive model support
GOOGLE_CLOUD_LOCATION=us-central1

# Avoid: Global location has limited model availability
# GOOGLE_CLOUD_LOCATION=global

Regional and Data-Residency Endpoints

The API host is derived from the location passed to the factory:

  • null or global uses the global endpoint aiplatform.googleapis.com.
  • A region such as europe-west1 uses the matching regional endpoint europe-west1-aiplatform.googleapis.com.
  • The multi-region data-residency (jurisdictional) values eu and us use aiplatform.eu.rep.googleapis.com and aiplatform.us.rep.googleapis.com respectively.

See Vertex AI locations and Vertex AI data residency for the list of supported values.

The location is case-insensitive, and a value that is neither global, eu/us, nor a region is rejected with an InvalidArgumentException.

Note

The location is only part of the project-scoped URL, so it only takes effect together with a project ID. The API-key-only setup always uses the global endpoint.

Token Usage Tracking

Token usage is automatically tracked and available in the result metadata:

1
2
3
4
5
6
7
8
9
10
11
12
13
use Symfony\AI\Agent\Agent;
use Symfony\AI\Platform\TokenUsage\TokenUsage;

$agent = new Agent($platform, $model);
$result = $agent->call($messages);

$tokenUsage = $result->getMetadata()->get('token_usage');

assert($tokenUsage instanceof TokenUsage);

echo 'Prompt Tokens: ' . $tokenUsage->getPromptTokens() . PHP_EOL;
echo 'Completion Tokens: ' . $tokenUsage->getCompletionTokens() . PHP_EOL;
echo 'Total Tokens: ' . $tokenUsage->getTotalTokens() . PHP_EOL;

Server Tools

Vertex AI provides built-in server tools. See Vertex AI Server Tools for detailed information about:

  • URL Context
  • Grounding with Google Search
  • Code Execution

Examples

See the examples/vertexai/ directory for complete working examples:

  • token-metadata.php - Token usage tracking
  • toolcall.php - Using server tools
  • server-tools.php - Advanced server tool usage
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version