mirror of
https://github.com/symfony/ai.git
synced 2026-03-23 23:42:18 +01:00
17eaefb768
- Fix class names: CachedPlatform→CachePlatform, OllamaApiCatalog→ModelCatalog, Indexer→DocumentIndexer/SourceIndexer, Store\Vector→Platform\Vector\Vector - Fix namespaces: TokenUsage, MemoryInputProcessor, ConfiguredSourceIndexer, SourceIndexer, DocumentIndexer, StructuredOutputSerializer - Fix method calls: asText()→getContent(), private property access→getters - Fix API signatures: StoreInterface::query() now requires QueryInterface, ChromaDb\Store constructor updated, Ollama PlatformFactory simplified - Remove unused imports: Gpt, Embeddings, VertexAi Model - Fix incorrect file reference: _model-listing.php→_model.php - Fix incorrect link target: Crawler Tool→firecrawl-crawl.php - Fix MessageBagInterface→MessageBag (interface doesn't exist)
197 lines
6.1 KiB
ReStructuredText
197 lines
6.1 KiB
ReStructuredText
Vertex AI
|
|
=========
|
|
|
|
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:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: terminal
|
|
|
|
$ gcloud auth application-default login
|
|
|
|
For detailed authentication setup, see `Setting up authentication for Vertex AI`_.
|
|
|
|
Configure your Google Cloud project and location:
|
|
|
|
.. code-block:: bash
|
|
|
|
GOOGLE_CLOUD_PROJECT=your-project-id
|
|
GOOGLE_CLOUD_LOCATION=us-central1
|
|
|
|
|
|
Basic usage example::
|
|
|
|
use Symfony\AI\Platform\Bridge\VertexAi\PlatformFactory;
|
|
use Symfony\AI\Platform\Message\Message;
|
|
use Symfony\AI\Platform\Message\MessageBag;
|
|
|
|
$platform = PlatformFactory::create(
|
|
$_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->getContent();
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
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::
|
|
|
|
$platform = PlatformFactory::create(
|
|
$_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::
|
|
|
|
$platform = PlatformFactory::create(
|
|
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::
|
|
|
|
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::
|
|
|
|
gcloud ai models list --region=us-central1
|
|
|
|
Location Configuration
|
|
----------------------
|
|
|
|
Configure your location in your environment file:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Recommended: Use a region with comprehensive model support
|
|
GOOGLE_CLOUD_LOCATION=us-central1
|
|
|
|
# Avoid: Global location has limited model availability
|
|
# GOOGLE_CLOUD_LOCATION=global
|
|
|
|
Token Usage Tracking
|
|
--------------------
|
|
|
|
Token usage is automatically tracked and available in the result metadata::
|
|
|
|
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 :doc:`vertexai-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
|
|
|
|
.. _Vertex AI documentation: https://cloud.google.com/vertex-ai/docs
|
|
.. _Vertex AI API reference: https://cloud.google.com/vertex-ai/docs/reference
|
|
.. _Google cloud authentication guide: https://cloud.google.com/docs/authentication
|
|
.. _Setting up authentication for Vertex AI: https://cloud.google.com/vertex-ai/docs/authentication
|
|
.. _Google Cloud Console for Vertex AI: https://console.cloud.google.com/vertex-ai
|
|
.. _Vertex AI Studio (API keys): https://console.cloud.google.com/vertex-ai/studio/settings/api-keys
|