使用 Gemini CLI

本頁面說明如何搭配 Gemini Enterprise Agent Platform Workbench 執行個體，使用 Gemini 指令列介面 (CLI)。

本文件適用於使用 Agent Platform Workbench 的資料分析師、數據資料學家和資料開發人員。本文假設您瞭解如何在筆記本環境中編寫程式碼。

總覽

Gemini CLI 是一項開放原始碼 AI 代理，可讓您直接在終端機使用 Gemini。詳情請參閱 geminicli.com。

Gemini CLI 適用於 Agent Platform Workbench 執行個體。Gemini CLI 可以執行下列操作：

  • 建立新的筆記本。
  • 執行筆記本儲存格。
  • 編寫及編輯筆記本的程式碼和文字儲存格。
  • 說明程式碼和技術概念。
  • 與 Agent Platform Workbench 執行個體的本機檔案系統互動，包括執行複雜的檔案作業，依據單一高階指令處理多個檔案。
  • 執行基本殼層指令。
  • 執行指令，與 Gemini Enterprise Agent Platform 和 BigQuery 等其他 Google Cloud 服務互動。

限制

搭配使用 Gemini CLI 和 Agent Platform Workbench 時，請注意下列限制：

  • Gemini CLI 僅提供 CLI。不含圖形化聊天介面和進階編輯器內工具。

  • 要求 Gemini CLI 修改筆記本時，Gemini CLI 會直接在執行個體的磁碟上變更筆記本檔案。因此，您無法使用筆記本編輯器的「復原」按鈕或 Control+Z 鍵 (macOS 為 Command+Z 鍵)，復原 Gemini CLI 所做的編輯。不過，您可以使用自然語言指令 (例如 Undo your last change)，要求 Gemini CLI 復原變更。

事前準備

  1. 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

必要的角色

如要在 Agent Platform Workbench 使用 Gemini CLI，您必須將權限授予 Agent Platform Workbench 執行個體的使用者和執行個體的服務帳戶。

將權限授予執行個體使用者

如要取得在 Agent Platform Workbench 執行個體中使用 Gemini CLI 所需的權限，請要求管理員授予您專案的Agent Platform 使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

將權限授予執行個體的服務帳戶

為確保 Agent Platform Workbench 執行個體的服務帳戶具備必要權限，可在 Agent Platform Workbench 執行個體中啟用 Gemini CLI，請要求管理員將專案的 Agent Platform 使用者 (roles/aiplatform.user) IAM 角色授予 Agent Platform Workbench 執行個體的服務帳戶。

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

這個預先定義的角色具備 aiplatform.endpoints.predict 權限，可讓 Gemini CLI 在 Agent Platform Workbench 執行個體中執行。

管理員或許還可透過自訂角色或其他預先定義的角色，將這項權限授予 Agent Platform Workbench 執行個體的服務帳戶。

使用 Gemini CLI

  1. 前往 Google Cloud 控制台的「Instances」(執行個體) 頁面。

    前往「Instances」(執行個體) 頁面

  2. 按一下 Agent Platform Workbench 執行個體名稱旁的「Open JupyterLab」。

    Agent Platform Workbench 執行個體會開啟 JupyterLab。

  3. 在 JupyterLab 中，依序點選「File」(檔案) >「New launcher」(新增啟動器)。

  4. 在「Launcher」分頁的「Other」部分，點選「Gemini CLI」圖塊。

  5. 如果這是您第一次開啟 Gemini CLI 終端機，請輸入 Y 同意條款及細則。

    Agent Platform Workbench 執行個體會安裝 Gemini CLI。

  6. 在 Gemini CLI 終端機輸入提示詞。

    例如，您可以輸入 Create a new notebook named 'test-notebook'。如要查看實用的提示範例，請參閱「提示範例」。

提示範例

如要瞭解如何使用 Gemini CLI，請參考下列提示詞範例：

  • 「建立新的筆記本，訓練模型預測 bigquery-public-data.ml_datasets.census_adult_income 的『收入級距』，使用 BigQuery 和 Python。」

  • 「總結名為『test-file』的筆記本，並提出專案的後續步驟。」

  • 「我想快速瞭解這個目錄中的筆記本。針對每個 .ipynb 檔案，顯示檔案的前 5 行。」

  • 「使用『test-file』筆記本的內容建立腳本。」

  • 「請示範如何在 Agent Platform Workbench 存取 BigQuery 資料表的資料。」

  • 「查詢 bigquery-public-data.ml_datasets.census_adult_income 資料表，找出收入級距大於 50K 的人數。」

  • 「將預設 Google Cloud 專案設為 my-project。」

  • 「建立 Cloud Storage bucket，並將目前目錄中的所有 CSV 檔案上傳至該 bucket。」

  • 「建立 Compute Engine 執行個體，並使用 Debian 11 映像檔和 n1-standard-4 機型。」

  • 「建立筆記本檔案，執行『test-script』中的程式碼。新增文字儲存格，說明程式碼。

控管 Gemini CLI 存取權

您可以透過下列方法，控管 Agent Platform Workbench 中 Gemini CLI 的存取權：

  • 管理員可以設定組織政策，在組織、資料夾或專案層級限制特定 Gemini 模型的使用。請參閱「控管 Model Garden 模型的存取權」。Gemini CLI 仍會顯示在 JupyterLab 中，但不會回應提示。

  • 管理員不授予 aiplatform.endpoints.predict 權限，即可禁止某些身分使用 Gemini 端點進行推論。

使用 Gemini CLI 魔術指令

如要直接在筆記本檔案的儲存格中使用 Gemini CLI，請按照下列步驟操作：

  1. 請確認 Gemini CLI 已啟用，且使用者或建立者已同意條款及細則。
  2. 在新儲存格的第一行輸入 %%geminicli_magic。
  3. 在同一個儲存格中，於下一行輸入提示詞。
  4. 執行儲存格。

Gemini CLI 會在下方新增儲存格，並顯示回覆。

疑難排解

如果在使用 Gemini CLI 搭配 Agent Platform Workbench 執行個體時遇到問題，請參閱「排解 Agent Platform Workbench 問題」，瞭解常見問題的解決方法。

後續步驟