google-cloud-aiplatform
Vertex AI API client library
Downloads: 0 (30 days)
Description
Vertex AI SDK for Python
=================================================
|GA| |pypi| |versions| |unit-tests| |system-tests| |sample-tests|
`Vertex AI`_: Google Vertex AI is an integrated suite of machine learning tools and services for building and using ML models with AutoML or custom code. It offers both novices and experts the best workbench for the entire machine learning development lifecycle.
- `Client Library Documentation`_
- `Product Documentation`_
.. |GA| image:: https://img.shields.io/badge/support-ga-gold.svg
:target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-aiplatform.svg
:target: https://pypi.org/project/google-cloud-aiplatform/
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-aiplatform.svg
:target: https://pypi.org/project/google-cloud-aiplatform/
.. |unit-tests| image:: https://storage.googleapis.com/cloud-devrel-public/python-aiplatform/badges/sdk-unit-tests.svg
:target: https://storage.googleapis.com/cloud-devrel-public/python-aiplatform/badges/sdk-unit-tests.html
.. |system-tests| image:: https://storage.googleapis.com/cloud-devrel-public/python-aiplatform/badges/sdk-system-tests.svg
:target: https://storage.googleapis.com/cloud-devrel-public/python-aiplatform/badges/sdk-system-tests.html
.. |sample-tests| image:: https://storage.googleapis.com/cloud-devrel-public/python-aiplatform/badges/sdk-sample-tests.svg
:target: https://storage.googleapis.com/cloud-devrel-public/python-aiplatform/badges/sdk-sample-tests.html
.. _Vertex AI: https://cloud.google.com/vertex-ai/docs
.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/aiplatform/latest
.. _Product Documentation: https://cloud.google.com/vertex-ai/docs
Installation
~~~~~~~~~~~~
.. code-block:: console
pip install google-cloud-aiplatform
With :code:`uv`:
.. code-block:: console
uv pip install google-cloud-aiplatform
Generative AI in the Vertex AI SDK
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use Gen AI features from the Vertex AI SDK, you can instantiate a Vertex SDK client with the following:
.. code-block:: Python
import vertexai
from vertexai import types
# Instantiate GenAI client from Vertex SDK
# Replace with your project ID and location
client = vertexai.Client(project='my-project', location='us-central1')
See the examples below for guidance on how to use specific features supported by the Vertex SDK client.
Gen AI Evaluation
^^^^^^^^^^^^^^^^^
To run evaluation, first generate model responses from a set of prompts.
.. code-block:: Python
import pandas as pd
prompts_df = pd.DataFrame({
"prompt": [
"What is the capital of France?",
"Write a haiku about a cat.",
"Write a Python function to calculate the factorial of a number.",
"Translate 'How are you?' to French.",
],
"reference": [
"Paris",
"Sunbeam on the floor,\nA furry puddle sleeping,\nTwitching tail tells tales.",
"def factorial(n):\n if n < 0:\n return 'Factorial does not exist for negative numbers'\n elif n == 0:\n return 1\n else:\n fact = 1\n i = 1\n while i <= n:\n fact *= i\n i += 1\n return fact",
"Comment ça va ?",
]
})
inference_results = client.evals.run_inference(
model="gemini-2.5-flash-preview-05-20",
src=prompts_df
)
Then run evaluation by providing the inference results and specifying the metric types.
.. code-block:: Python
eval_result = client.evals.evaluate(
dataset=inference_results,
metrics=[
types.Metric(name='exact_match'),
types.Metric(name='rouge_l_sum'),
types.RubricMetric.TEXT_QUALITY,
]
)
Agent Engine with Agent Development Kit (ADK)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First, define a function that looks up the exchange rate:
.. code-block:: Python
def get_exchange_rate(
currency_from: str = "USD",
currency_to: str = "EUR",
currency_date: str = "latest",
):
"""Retrieves the exchange rate between two currencies on a specified date.
Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
exchange rate data.
Returns:
dict: A dictionary containing the exchange rate information.
Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
"rates": {"EUR": 0.95534}}
"""
import requests
response = requests.get(
f"https://api.frankfurter.app/{currency_date}",
params={"from": currency_from, "to": currency_to},
)
return response.json()
Next, define an ADK Agent:
.. code-block:: Python
from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp
app = AdkApp(agent=Agent(
model="gemini-2.0-flash", # Required.
name='currency_exchange_agent', # Required.
tools=[get_exchange_rate], # Optional.
))
Test the agent locally using US dollars and Swedish Krona:
.. code-block:: Python
async for event in app.async_stream_query(
user_id="user-id",
message="What is the exchange rate from US dollars to SEK today?",
):
print(event)
To deploy the agent to Agent Engine:
.. code-block:: Python
remote_app = client.agent_engines.create(
agent=app,
config={
"requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
},
)
You can also run queries against the deployed agent:
.. code-block:: Python
async for event in remote_app.async_stream_query(
user_id="user-id",
message="What is the exchange rate from US dollars to SEK today?",
):
print(event)
Prompt optimization
^^^^^^^^^^^^^^^^^^^
To do a zero-shot prompt optimization, use the `optimize`
method.
.. code-block:: Python
prompt = "Generate system instructions for a question-answering assistant"
response = client.prompts.optimize(prompt=prompt)
print(response.raw_text_response)
if response.parsed_response:
print(response.parsed_response.suggested_prompt)
To call the data-driven prompt optimization, call the `launch_optimization_job` method.
In this case however, we need to provide a VAPO (Vertex AI Prompt Optimizer) config. This config needs to
have either service account or project **number** and the config path.
Please refer to this [tutorial](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/data-driven-optimizer)
for more details on config parameter.
.. code-block:: Python
from vertexai import types
project_number = PROJECT_NUMBER # replace with your project number
service_account = f"{project_number}-compute@developer.gserviceaccount.com"
vapo_config = vertexai.types.PromptOptimizerVAPOConfig(
config_path="gs://your-bucket/config.json",
service_account_project_number=project_number,
wait_for_completion=False
)
# Set up logging to see the progress of the optimization job
logging.basicConfig(encoding='utf-8', level=logging.INFO, force=True)
result = client.prompts.launch_optimization_job(method=types.PromptOptimizerMethod.VAPO, config=vapo_config)
If you want to use the project number instead of the service account, you can
instead use the following config:
.. code-block:: Python
vapo_config = vertexai.types.PromptOptimizerVAPOConfig(
config_path="gs://your-bucket/config.json",
service_account_project_number=project_number,
wait_for_completion=False
)
We can also call the `launch_optimization_job` method asynchronously.
.. code-block:: Python
await client.aio.prompts.launch_optimization_job(method=types.PromptOptimizerMethod.VAPO, config=vapo_config)
Prompt Management
^^^^^^^^^^^^^^^^^
First define your prompt as a dictionary or types.Prompt object. Then call create_prompt.
.. code-block:: Python
prompt = {
"prompt_data": {
"contents": [{"parts": [{"text": "Hello, {name}! How are you?"}]}],
"system_instruction": {"parts": [{"text": "Please answer in a short sentence."}]},
"variables": [
{"name": {"text": "Alice"}},
],
"model": "gemini-2.5-flash",
},
}
prompt_resource = client.prompts.create(
prompt=prompt,
)
Note that you can also use the types.Prompt object to define your prompt. Some of the types used to do this are from the Gen AI SDK.
.. code-block:: Python
import types
from google.genai import types as genai_types
prompt = types.Prompt(
prompt_data=types.PromptData(
contents=[genai_types.Content(parts=[genai_types.Part(text="Hello, {name}! How are you?")])],
system_instruction=genai_types.Content(parts=[genai_types.Part(text="Please answer in a short sentence.")]),
variables=[
{"name": genai_types.Part(text="Alice")},
],
model="gemini-2.5-flash",
),
)
Retrieve a prompt by calling get() with the prompt_id.
.. code-block:: Python
retrieved_prompt = client.prompts.get(
prompt_id=prompt_resource.prompt_id,
)
After creating or retrieving a prompt, you can call `generate_content()` with that prompt using the Gen AI SDK.
The following uses a utility function available on Prompt objects to transform a Prompt object into a list of Content objects for use with `generate_content`. To run this you need to have the Gen AI SDK installed, which you can do via `pip install google-genai`.
.. code-block:: Python
from google import genai
from google.genai import types as genai_types
# Creat