設定環境

使用 Vertex AI Agent Engine 前，請先確認環境已設定完成。您必須擁有 Google Cloud 已啟用付款功能的專案、具備必要權限、設定 Cloud Storage 值區，以及安裝 Python 適用的 Vertex AI SDK。請參閱下列主題，確保您已準備好開始使用 Vertex AI Agent Engine。

如要參考 Terraform 範例，瞭解如何簡化 Vertex AI Agent Engine 環境的設定和部署作業，不妨查看 agent-starter-pack。

設定您的 Google Cloud 專案

每項專案都有專案編號或專案 ID 這兩項識別資訊。PROJECT_NUMBER 是系統在您建立專案時自動產生的，而 PROJECT_ID 則是由您或專案建立者所建立。如要設定專案，請按照下列步驟操作：

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

    8.

    取得必要角色

    如要取得使用 Vertex AI Agent Engine 所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

    如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

    您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

    設定服務代理權限

    您在 Vertex AI Agent Engine 上部署的代理會使用 AI Platform Reasoning Engine 服務代理服務帳戶執行。這個帳戶具有 Vertex AI 推理引擎服務代理人角色，可授予部署代理程式所需的預設權限。您可以在 IAM 說明文件中查看預設權限的完整清單。

    如果需要其他權限，您可以執行下列步驟，為這個服務代理授予其他角色：

    1. 前往「IAM」頁面，勾選「包含 Google 提供的角色授予項目」核取方塊。

      前往「IAM」頁面

    2. 找出與 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 相符的主體。

    3. 按一下「編輯」按鈕，然後點選「儲存」按鈕，將必要角色新增至主體。

    手動產生服務代理

    雖然 Reasoning Engine Service Agent 會在 Vertex AI Agent Engine 部署期間自動佈建，但在某些情況下，您可能需要事先手動產生這個代理程式。當您需要向服務代理人授予特定角色，以確保部署程序具備必要權限，並避免潛在的部署失敗問題時，這點就特別重要。

    以下是手動產生 Reasoning Engine Service Agent 的步驟：

    1. 使用 Google Cloud CLI 產生 Reasoning Engine 服務代理。

      gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

    2. 前往「IAM」頁面，然後點選「授予存取權」。

      前往「IAM」頁面

    3. 在「新增主體」部分的「新增主體」欄位中輸入 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com。

    4. 在「指派角色」部分中，找出並選取所需角色。

    5. 按一下「儲存」按鈕。

    建立 Cloud Storage 值區

    Vertex AI Agent Engine 會在部署程序中，將已部署的代理程式暫存於 Cloud Storage 值區。請確認已驗證可使用 Vertex AI 的主體 (您或服務帳戶) 具備 Storage Admin 對這個值區的存取權。這是必要步驟，因為 Vertex AI SDK for Python 會將程式碼寫入這個儲存桶。

    如果您已設定桶，可以略過這個步驟。否則，您可以按照標準操作說明建立值區。

    Google Cloud 控制台

    1. In the Google Cloud console, go to the Cloud Storage Buckets page.

      Go to Buckets

    2. Click Create.
    3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
      1. In the Get started section, do the following:
        • Enter a globally unique name that meets the bucket naming requirements.
        • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
      2. In the Choose where to store your data section, do the following:
        1. Select a Location type.
        2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
        3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

          Set up cross-bucket replication

          1. In the Bucket menu, select a bucket.

          2. In the Replication settings section, click Configure to configure settings for the replication job.

            The Configure cross-bucket replication pane appears.

            • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
            • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
            • Click Done.
      3. In the Choose how to store your data section, do the following:
        1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
        2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
      4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
      5. In the Choose how to protect object data section, do the following:
        • Select any of the options under Data protection that you want to set for your bucket.
          • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
          • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
          • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
            • To enable Object Retention Lock, click the Enable object retention checkbox.
            • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
        • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.
    4. Click Create.

    指令列

      Create a Cloud Storage bucket and configure it as follows:
      • 將 STORAGE_CLASS 替換成您偏好的儲存空間級別。
      • 將 LOCATION 替換成您偏好的地點 (ASIA、EU 或 US)
      • 將 BUCKET_NAME 替換成 符合值區命名規定的值區名稱。 
        • gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

    安裝及初始化 Vertex AI SDK for Python

    本節假設您已設定 Python 開發環境，或是使用 Colab (或任何其他適合的執行階段，已為您設定好環境)。

    (選用) 設定虛擬環境

    我們也建議您設定虛擬環境，以便隔離依附元件。

    安裝

    為盡量減少您必須安裝的依附元件組合，我們將依附元件分為以下類別：

    • agent_engines：部署至 Vertex AI Agent Engine 所需的套件組合。
    • adk：相容的代理開發套件組合。
    • langchain：相容的 LangChain 和 LangGraph 套件組合。
    • ag2：相容的 AG2 套件組合。
    • llama_index：相容的 LlamaIndex 套件組合。

    安裝 Vertex AI SDK for Python 時，您可以指定所需的依附元件 (以半形逗號分隔)。如要安裝所有更新，請按照下列步驟操作：

    pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.88.0

    驗證

    Colab

    請執行下列程式碼：

    from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

    Cloud Shell

    您無需採取任何動作。

    本機殼層

    執行下列指令：

    gcloud auth application-default login

    匯入並初始化 SDK

    執行下列程式碼，匯入並初始化 Vertex AI Agent Engine 的 SDK：

    import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

    其中

    後續步驟