Vertex AI Python SDK

|GA| |pypi| |versions| |unit-tests| |system-tests| |sample-tests|

Vertex AI_: Google Vertex AI 是一套集成的机器学习工具和服务，用于通过 AutoML 或自定义代码构建和使用机器学习模型。它为初学者和专家提供了覆盖整个机器学习开发生命周期的最佳工作台。

• 客户端库文档_
• 产品文档_

.. |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

安装

.. code-block:: console

    pip install google-cloud-aiplatform


使用 :code:`uv`:

.. code-block:: console

    uv pip install google-cloud-aiplatform

Vertex AI SDK 中的生成式 AI

要使用 Vertex AI SDK 中的生成式 AI 功能，您可以按如下方式实例化一个 Vertex SDK 客户端：

.. code-block:: Python

import vertexai
from vertexai import types

# 从 Vertex SDK 实例化生成式 AI 客户端
# 替换为您自己的项目 ID 和位置
client = vertexai.Client(project='my-project', location='us-central1')

请参阅下面的示例，了解如何使用 Vertex SDK 客户端支持的特定功能。

生成式 AI 评估 ^^^^^^^^^^^^^^^^^

要运行评估，首先需要根据一组提示生成模型响应。

.. code-block:: Python

import pandas as pd

prompts_df = pd.DataFrame({
    "prompt": [
        "法国的首都是什么？",
        "写一首关于猫的俳句。",
        "编写一个计算阶乘的 Python 函数。",
        "将‘你好吗？’翻译成法语。",
    ],

    "reference": [
        "巴黎",
        "阳光洒在地板上，\n毛茸茸的一团沉睡着，\n尾巴微微抽动，仿佛在诉说故事。",
        "def factorial(n):\n    if n < 0:\n        return '负数没有阶乘'\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
)

然后，提供推理结果并指定指标类型来运行评估。

.. 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 开发套件 (ADK) 的 Agent Engine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

首先，定义一个查询汇率的函数：

.. code-block:: Python

def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """获取指定日期两种货币之间的汇率。

    使用 Frankfurter API (https://api.frankfurter.app/) 获取汇率数据。

    返回：
        dict: 包含汇率信息的字典。
            示例：{"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()

接下来，定义一个 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",        # 必需。
    name='currency_exchange_agent',  # 必需。
    tools=[get_exchange_rate],       # 可选。
))

使用美元和瑞典克朗在本地测试该代理：

.. code-block:: Python

async for event in app.async_stream_query(
    user_id="user-id",
    message="今天美元兑瑞典克朗的汇率是多少？",
):
    print(event)

要将代理部署到 Agent Engine：

.. code-block:: Python

remote_app = client.agent_engines.create(
    agent=app,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

您还可以对已部署的代理进行查询：

.. code-block:: Python

async for event in remote_app.async_stream_query(
    user_id="user-id",
    message="今天美元兑瑞典克朗的汇率是多少？",
):
    print(event)

提示优化 ^^^^^^^^^^^^^^^^^^^

要进行零样本提示优化，可以使用 optimize 方法。

.. code-block:: Python

prompt = "为问答助手生成系统指令"
response = client.prompts.optimize(prompt=prompt)
print(response.raw_text_response)
if response.parsed_response:
  print(response.parsed_response.suggested_prompt)

要调用数据驱动的提示优化，可以调用 launch_optimization_job 方法。不过，在这种情况下，我们需要提供一个 VAPO（Vertex AI 提示优化器）配置文件。该配置文件需要包含服务账号或项目 编号 以及配置文件路径。有关配置参数的更多详细信息，请参阅此 教程。

.. code-block:: Python

from vertexai import types

project_number = 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
)

# 设置日志记录，以便查看优化作业的进度
logging.basicConfig(encoding='utf-8', level=logging.INFO, force=True)

result = client.prompts.launch_optimization_job(method=types.PromptOptimizerMethod.VAPO, config=vapo_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
)

我们也可以异步调用 launch_optimization_job 方法。

.. code-block:: Python

await client.aio.prompts.launch_optimization_job(method=types.PromptOptimizerMethod.VAPO, config=vapo_config)

提示管理 ^^^^^^^^^^^^^

首先将您的提示定义为字典或 types.Prompt 对象。然后调用 create_prompt。

.. code-block:: Python

prompt = {
    "prompt_data": {
        "contents": [{"parts": [{"text": "你好，{name}！你好吗？"}]}],
        "system_instruction": {"parts": [{"text": "请用一句话简短回答。"}]},
        "variables": [
            {"name": {"text": "Alice"}},
        ],
        "model": "gemini-2.5-flash",
    },
}

prompt_resource = client.prompts.create(
    prompt=prompt,
)

请注意，您也可以使用 types.Prompt 对象来定义您的提示。用于此目的的一些类型来自 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="你好，{name}！你好吗？")])],
      system_instruction=genai_types.Content(parts=[genai_types.Part(text="请用一句话简短回答。")]),
      variables=[
        {"name": genai_types.Part(text="Alice")},
      ],
      model="gemini-2.5-flash",
    ),
)

通过调用 get() 并传入 prompt_id 来检索提示。

.. code-block:: Python

retrieved_prompt = client.prompts.get(
    prompt_id=prompt_resource.prompt_id,
)

创建或检索提示后，您可以使用 Gen AI SDK 调用 generate_content() 方法并传入该提示。

以下代码使用 Prompt 对象上可用的实用函数，将 Prompt 对象转换为 Content 对象列表，以便与 generate_content 一起使用。要运行此代码，您需要安装 Gen AI SDK，可以通过 pip install google-genai 安装。

.. code-block:: Python

from google import genai
from google.genai import types as genai_types

# 在 Gen AI SDK 中创建客户端
genai_client = genai.Client(vertexai=True, project="your-project", location="your-location")

# 使用提示调用 generate_content()
response = genai_client.models.generate_content(
    model=retrieved_prompt.prompt_data.model,
    contents=retrieved_prompt.assemble_contents(),
)

---

.. note::

Vertex AI SDK 中的以下生成式 AI 模块自 2025 年 6 月 24 日起已被弃用，并将于 2026 年 6 月 24 日移除： vertexai.generative_models、vertexai.language_models、vertexai.vision_models、vertexai.tuning、vertexai.caching。请使用 Google Gen AI SDK 访问这些功能。有关详细信息，请参阅 迁移指南。 您可以继续使用其他所有 Vertex AI SDK 模块，因为它们是使用 API 的推荐方式。

快速入门

为了使用本库，您首先需要完成以下步骤：

1. 选择或创建一个 Cloud Platform 项目。_
2. 为您的项目启用结算功能。_
3. 启用 Vertex AI API。_
4. 设置身份验证。_

.. _选择或创建一个 Cloud Platform 项目.: https://console.cloud.google.com/project .. _为您的项目启用结算功能.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project .. _启用 Vertex AI API.: https://cloud.google.com/vertex-ai/docs/start/use-vertex-ai-python-sdk .. _设置身份验证.: https://googleapis.dev/python/google-api-core/latest/auth.html

支持的 Python 版本 ^^^^^^^^^^^^^^^^^^^^^^^^^ Python >= 3.9

已弃用的 Python 版本 ^^^^^^^^^^^^^^^^^^^^^^^^^^ Python <= 3.8。

与 Python 3.8 兼容的本库最后一个版本是 google-cloud-aiplatform==1.90.0。

与 Python 3.7 兼容的本库最后一个版本是 google-cloud-aiplatform==1.31.1。

与 Python 3.6 兼容的本库最后一个版本是 google-cloud-aiplatform==1.12.1。

概述

本节提供 Python 版 Vertex AI SDK 的简要概述。您还可以参考 `vertex-ai-samples`_ 中的笔记本以获取示例。

.. _vertex-ai-samples: https://github.com/GoogleCloudPlatform/vertex-ai-samples/tree/main/notebooks/community/sdk

所有公开可用的 SDK 功能都可以在 :code:`google/cloud/aiplatform` 目录中找到。
在底层，Vertex SDK 基于 GAPIC 构建，GAPIC 是 Google API CodeGen 的缩写。
GAPIC 库代码位于 :code:`google/cloud/aiplatform_v1` 和 :code:`google/cloud/aiplatform_v1beta1`，
它是根据 Google 的服务 proto 文件自动生成的。

对于大多数开发人员的编程需求，他们可以按照以下步骤来确定要导入哪些库：

1. 首先查看 :code:`google/cloud/aiplatform` —— 与 GAPIC 相比，Vertex SDK 的 API 几乎总是更易于使用且更简洁。
2. 如果您寻找的功能在那里找不到，则查看 :code:`aiplatform_v1` 以确定是否在 GAPIC 中可用。
3. 如果功能仍处于测试阶段，则会在 :code:`aiplatform_v1beta1` 中提供。

如果以上情况都无法帮助您找到适合任务的工具，请随时在 GitHub 上提交问题并向我们提出功能请求。

导入
^^^^^^^^^
可以通过导入以下命名空间来使用 Vertex AI SDK 的基于资源的功能：

.. code-block:: Python

    from google.cloud import aiplatform

初始化
^^^^^^^^^^^^^^
初始化 SDK 以存储您在使用 SDK 时常用的配置。

.. code-block:: Python

    aiplatform.init(
        # 您的 Google Cloud 项目 ID 或编号
        # 默认环境未设置
        project='my-project',

# 您将使用的 Vertex AI 区域
        # 默认为 us-central1
        location='us-central1',

        # 与 location 同区域的 Google Cloud Storage 存储桶
        # 用于暂存工件
        staging_bucket='gs://my_staging_bucket',

        # 自定义 google.auth.credentials.Credentials
        # 如果未设置，则使用环境默认凭据
        credentials=my_credentials,

        # 客户管理的加密密钥资源名称
        # 如果设置，将应用于所有 Vertex AI 资源
        encryption_spec_key_name=my_encryption_key_name,

        # 用于跟踪记录指标和参数的实验名称
        experiment='my-experiment',

        # 上述实验的描述
        experiment_description='my experiment description'
    )

数据集
^^^^^^^^
Vertex AI 提供托管的表格、文本、图像和视频数据集。在 SDK 中，数据集可用于下游的模型训练。

要创建一个表格数据集：

.. code-block:: Python

    my_dataset = aiplatform.TabularDataset.create(
        display_name="my-dataset", gcs_source=['gs://path/to/my/dataset.csv'])

您也可以分步骤创建和导入数据集：

.. code-block:: Python

    from google.cloud import aiplatform

    my_dataset = aiplatform.TextDataset.create(
        display_name="my-dataset")

    my_dataset.import_data(
        gcs_source=['gs://path/to/my/dataset.csv'],
        import_schema_uri=aiplatform.schema.dataset.ioformat.text.multi_label_classification
    )

要获取先前创建的数据集：

.. code-block:: Python

  dataset = aiplatform.ImageDataset('projects/my-project/location/us-central1/datasets/{DATASET_ID}')

Vertex AI 支持多种数据集模式。这些模式的引用可在 :code:`aiplatform.schema.dataset` 命名空间下找到。有关支持的数据集模式的更多信息，请参阅 `准备数据文档`_。

.. _准备数据文档: https://cloud.google.com/ai-platform-unified/docs/datasets/prepare

训练
^^^^^^^^
Vertex AI 的 Python SDK 允许您训练自定义模型和 AutoML 模型。

您可以使用自定义 Python 脚本、自定义 Python 包或容器来训练自定义模型。

**准备您的自定义代码**

Vertex AI 自定义训练使您能够在 Vertex AI 数据集上进行训练，并生成 Vertex AI 模型。为此，您的脚本必须遵守以下约定：

它必须从训练服务填充的环境变量中读取数据集：

.. code-block:: Python

  os.environ['AIP_DATA_FORMAT']  # 提供数据格式
  os.environ['AIP_TRAINING_DATA_URI']  # 训练集的 URI
  os.environ['AIP_VALIDATION_DATA_URI']  # 验证集的 URI
  os.environ['AIP_TEST_DATA_URI']  # 测试集的 URI

请访问 `在自定义训练应用中使用托管数据集`_ 以获取详细概述。

.. _在自定义训练应用中使用托管数据集: https://cloud.google.com/vertex-ai/docs/training/using-managed-datasets

它必须将模型工件写入由训练服务填充的环境变量中：

.. code-block:: Python

  os.environ['AIP_MODEL_DIR']

**运行训练**

.. code-block:: Python

  job = aiplatform.CustomTrainingJob(
      display_name="my-training-job",
      script_path="training_script.py",
      container_uri="us-docker.pkg.dev/vertex-ai/training/tf-cpu.2-2:latest",
      requirements=["gcsfs==0.7.1"],
      model_serving_container_image_uri="us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-2:latest",
  )

  model = job.run(my_dataset,
                  replica_count=1,
                  machine_type="n1-standard-4",
                  accelerator_type='NVIDIA_TESLA_K80',
                  accelerator_count=1)

在上面的代码块中，`my_dataset` 是在上述“数据集”部分创建的托管数据集。`model` 变量是一个托管的 Vertex AI 模型，可以部署或导出。


AutoMLs
-------
Vertex AI 的 Python SDK 支持 AutoML 表格、图像、文本、视频和预测模型。

要训练一个 AutoML 表格模型：

.. code-block:: Python

  dataset = aiplatform.TabularDataset('projects/my-project/location/us-central1/datasets/{DATASET_ID}')

  job = aiplatform.AutoMLTabularTrainingJob(
    display_name="train-automl",
    optimization_prediction_type="regression",
    optimization_objective="minimize-rmse",
  )

  model = job.run(
      dataset=dataset,
      target_column="target_column_name",
      training_fraction_split=0.6,
      validation_fraction_split=0.2,
      test_fraction_split=0.2,
      budget_milli_node_hours=1000,
      model_display_name="my-automl-model",
      disable_early_stopping=False,
  )


模型
------
要获取模型：


.. code-block:: Python

  model = aiplatform.Model('/projects/my-project/locations/us-central1/models/{MODEL_ID}')



要上传模型：

.. code-block:: Python

  model = aiplatform.Model.upload(
      display_name='my-model',
      artifact_uri="gs://python/to/my/model/dir",
      serving_container_image_uri="us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-2:latest",
  )



要部署模型：


.. code-block:: Python

  endpoint = model.deploy(machine_type="n1-standard-4",
                          min_replica_count=1,
                          max_replica_count=5
                          machine_type='n1-standard-4',
                          accelerator_type='NVIDIA_TESLA_K80',
                          accelerator_count=1)


请访问 `将模型导入 Vertex AI`_ 以获取详细概述：

.. _将模型导入 Vertex AI: https://cloud.google.com/vertex-ai/docs/general/import-model

模型评估
----------------

Vertex AI 的 Python SDK 目前支持获取所有 AutoML 模型的评估指标。

要列出某个模型的所有评估结果：

.. code-block:: Python

  model = aiplatform.Model('projects/my-project/locations/us-central1/models/{MODEL_ID}')

  evaluations = model.list_model_evaluations()


要获取特定模型的评估资源：

.. code-block:: Python

  model = aiplatform.Model('projects/my-project/locations/us-central1/models/{MODEL_ID}')

  # 不带参数时返回第一个评估，您也可以传入评估 ID
  evaluation = model.get_model_evaluation()

  eval_metrics = evaluation.metrics


您也可以通过直接传入模型评估的资源名称来创建对评估的引用：

.. code-block:: Python

  evaluation = aiplatform.ModelEvaluation(
    evaluation_name='projects/my-project/locations/us-central1/models/{MODEL_ID}/evaluations/{EVALUATION_ID}')

或者，您可以通过传入模型和评估 ID 来创建评估的引用：

.. code-block:: Python

  evaluation = aiplatform.ModelEvaluation(
    evaluation_name={EVALUATION_ID},
    model_id={MODEL_ID})


批量预测
----------------

要创建一个批量预测任务：

.. code-block:: Python

model = aiplatform.Model('/projects/my-project/locations/us-central1/models/{MODEL_ID}')

  batch_prediction_job = model.batch_predict(
    job_display_name='my-batch-prediction-job',
    instances_format='csv',
    machine_type='n1-standard-4',
    gcs_source=['gs://path/to/my/file.csv'],
    gcs_destination_prefix='gs://path/to/my/batch_prediction/results/',
    service_account='my-sa@my-project.iam.gserviceaccount.com'
  )

你也可以通过包含 `sync=False` 参数来异步创建批量预测作业：

.. code-block:: Python

  batch_prediction_job = model.batch_predict(..., sync=False)

  # 等待资源创建完成
  batch_prediction_job.wait_for_resource_creation()

  # 获取状态
  batch_prediction_job.state

  # 阻塞直到作业完成
  batch_prediction_job.wait()


端点
---------

要创建一个端点：

.. code-block:: Python

  endpoint = aiplatform.Endpoint.create(display_name='my-endpoint')

要将模型部署到已创建的端点上：

.. code-block:: Python

  model = aiplatform.Model('/projects/my-project/locations/us-central1/models/{MODEL_ID}')

  endpoint.deploy(model,
                  min_replica_count=1,
                  max_replica_count=5,
                  machine_type='n1-standard-4',
                  accelerator_type='NVIDIA_TESLA_K80',
                  accelerator_count=1)

要从端点获取预测结果：

.. code-block:: Python

  endpoint.predict(instances=[[6.7, 3.1, 4.7, 1.5], [4.6, 3.1, 1.5, 0.2]])

要从端点卸载模型：

.. code-block:: Python

  endpoint.undeploy_all()

要删除一个端点：

.. code-block:: Python

  endpoint.delete()


管道
---------

要创建一个 Vertex AI 管道运行并监控其完成：

.. code-block:: Python

  # 实例化 PipelineJob 对象
  pl = PipelineJob(
      display_name="我的第一个管道",

      # 是否启用缓存
      # True = 始终缓存管道步骤结果
      # False = 永远不缓存管道步骤结果
      # None = 延迟到管道定义中每个组件的缓存选项
      enable_caching=False,

      # 已编译管道定义的本地或 GCS 路径
      template_path="pipeline.json",

      # 包含管道输入参数的字典
      parameter_values=parameter_values,

      # 用作管道根目录的 GCS 路径
      pipeline_root=pipeline_root,
  )

  # 在 Vertex AI 中执行管道并监控其完成
  pl.run(
    # 用于管道运行的服务账户电子邮件地址
    # 必须对该服务账户拥有 iam.serviceAccounts.actAs 权限才能使用
    service_account=service_account,

    # 此函数调用是同步（等待管道运行完成后再终止）还是异步（立即返回）
    sync=True
  )

要创建一个 Vertex AI 管道而不监控其完成，可以使用 `submit` 代替 `run`：

.. code-block:: Python

  # 实例化 PipelineJob 对象
  pl = PipelineJob(
      display_name="我的第一个管道",

      # 是否启用缓存
      # True = 始终缓存管道步骤结果
      # False = 永远不缓存管道步骤结果
      # None = 延迟到管道定义中每个组件的缓存选项
      enable_caching=False,

      # 已编译管道定义的本地或 GCS 路径
      template_path="pipeline.json",

      # 包含管道输入参数的字典
      parameter_values=parameter_values,

      # 用作管道根目录的 GCS 路径
      pipeline_root=pipeline_root,
  )

  # 将管道提交到 Vertex AI
  pl.submit(
    # 用于管道运行的服务账户电子邮件地址
    # 必须对该服务账户拥有 iam.serviceAccounts.actAs 权限才能使用
    service_account=service_account,
  )


可解释 AI：获取元数据
----------------------------

要从 TensorFlow 1 模型中以字典格式获取元数据：

.. code-block:: Python

  from google.cloud.aiplatform.explain.metadata.tf.v1 import saved_model_metadata_builder

  builder = saved_model_metadata_builder.SavedModelMetadataBuilder(
            'gs://python/to/my/model/dir', tags=[tf.saved_model.tag_constants.SERVING]
        )
  generated_md = builder.get_metadata()

要从 TensorFlow 2 模型中以字典格式获取元数据：

.. code-block:: Python

  from google.cloud.aiplatform.explain.metadata.tf.v2 import saved_model_metadata_builder

  builder = saved_model_metadata_builder.SavedModelMetadataBuilder('gs://python/to/my/model/dir')
  generated_md = builder.get_metadata()

要在端点部署和模型上传中使用解释性元数据：

.. code-block:: Python

  explanation_metadata = builder.get_metadata_protobuf()

  # 使用解释性元数据部署模型到端点
  model.deploy(..., explanation_metadata=explanation_metadata)

  # 使用解释性元数据将模型部署到已创建的端点
  endpoint.deploy(..., explanation_metadata=explanation_metadata)

  # 使用解释性元数据上传模型
  aiplatform.Model.upload(..., explanation_metadata=explanation_metadata)


Cloud Profiler
----------------------------

Cloud Profiler 允许你按需对远程 Vertex AI 训练作业进行性能分析，并在 Vertex AI TensorBoard 中可视化结果。

要开始使用 TensorFlow 的性能分析器，需更新你的训练脚本以包含以下内容：

.. code-block:: Python

    from google.cloud.aiplatform.training_utils import cloud_profiler
    ...
    cloud_profiler.init()

接下来，使用 Vertex AI TensorBoard 实例运行作业。有关详细操作，请访问 https://cloud.google.com/vertex-ai/docs/experiments/tensorboard-overview

最后，在 Google Cloud 控制台中打开你的 TensorBoard，导航到“Profile”选项卡，然后点击“Capture Profile”按钮。这将允许用户捕获正在运行的作业的性能分析统计数据。


下一步

• 阅读 Vertex AI API 的 客户端库文档_，以了解客户端提供的其他可用方法。
• 阅读 Vertex AI API 产品文档_，以了解更多关于该产品的信息及操作指南。
• 查看此 README_，以查看我们支持的完整云端 API 列表。

.. _Vertex AI API 产品文档: https://cloud.google.com/vertex-ai/docs .. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst

Vertex AI Python SDK 快速上手指南

本指南帮助中国开发者快速安装并使用 google-cloud-aiplatform（Vertex AI SDK for Python），涵盖环境准备、安装及生成式 AI 核心功能的基本使用。

环境准备

在开始之前，请确保满足以下系统要求和前置条件：

• Python 版本：Python >= 3.9（Python 3.8 及以下版本已不再支持）。
• Google Cloud 项目：
  1. 创建或选择一个 Cloud Platform 项目。
  2. 为项目 启用计费。
  3. 启用 Vertex AI API。
• 身份验证：
  • 本地开发：运行 gcloud auth application-default login 进行认证。
  • 生产环境：确保运行环境配置了具有适当权限的服务账号密钥或元数据服务器访问权限。

安装步骤

推荐使用 pip 或 uv 进行安装。国内开发者若遇到下载速度慢的问题，可指定清华或阿里镜像源加速。

使用 pip 安装

# 官方源
pip install google-cloud-aiplatform

# 国内加速（推荐）
pip install google-cloud-aiplatform -i https://pypi.tuna.tsinghua.edu.cn/simple

使用 uv 安装

uv pip install google-cloud-aiplatform

注意：部分旧版生成式 AI 模块（如 vertexai.generative_models）已于 2025 年 6 月弃用。本指南及最新实践推荐使用新的 vertexai 客户端接口或配合 google-genai SDK 使用。

基本使用

以下示例展示如何初始化客户端并执行核心的生成式 AI 任务（评估、Agent 构建、提示词优化与管理）。

1. 初始化客户端

首先实例化 Vertex AI 客户端，替换为您的项目 ID 和区域。

import vertexai
from vertexai import types

# 实例化 GenAI 客户端
# 请替换为您的项目 ID 和位置 (例如: us-central1)
client = vertexai.Client(project='my-project', location='us-central1')

2. 生成式 AI 评估 (Gen AI Evaluation)

对模型回答进行自动化评估（如精确匹配、ROUGE-L 等）。

import pandas as pd

# 准备测试数据
prompts_df = pd.DataFrame({
    "prompt": [
        "What is the capital of France?",
        "Write a haiku about a cat.",
    ],
    "reference": [
        "Paris",
        "Sunbeam on the floor,\nA furry puddle sleeping,\nTwitching tail tells tales.",
    ]
})

# 运行推理
inference_results = client.evals.run_inference(
    model="gemini-2.5-flash-preview-05-20",
    src=prompts_df
)

# 执行评估
eval_result = client.evals.evaluate(
    dataset=inference_results,
    metrics=[
        types.Metric(name='exact_match'),
        types.Metric(name='rouge_l_sum'),
        types.RubricMetric.TEXT_QUALITY,
    ]
)

3. 构建 Agent (Agent Engine with ADK)

定义工具函数并创建基于 Agent Development Kit (ADK) 的智能体。

from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp
import requests

# 定义工具函数
def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """获取汇率"""
    response = requests.get(
        f"https://api.frankfurter.app/{currency_date}",
        params={"from": currency_from, "to": currency_to},
    )
    return response.json()

# 定义 Agent
app = AdkApp(agent=Agent(
    model="gemini-2.0-flash",
    name='currency_exchange_agent',
    tools=[get_exchange_rate],
))

# 本地测试
# 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)

# 部署到 Agent Engine
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

4. 提示词管理 (Prompt Management)

创建结构化提示词模板并调用模型生成内容。

# 定义提示词对象
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)

# 获取提示词
retrieved_prompt = client.prompts.get(prompt_id=prompt_resource.prompt_id)

# 结合 google-genai SDK 进行内容生成
# 需先安装: pip install google-genai
from google import genai

genai_client = genai.Client(vertexai=True, project="my-project", location="us-central1")

response = genai_client.models.generate_content(
    model=retrieved_prompt.prompt_data.model,
    contents=retrieved_prompt.assemble_contents(),
)