使用 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 會直接在執行個體的磁碟上變更筆記本檔案。因此，您無法使用筆記本編輯器的「復原」按鈕或 Ctrl+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.

    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.

    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 執行個體的服務帳戶具備必要權限，可讓 Gemini CLI 在 Agent Platform Workbench 執行個體中執行，請要求管理員將專案的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」(開啟 JupyterLab)。

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

  3. 在 JupyterLab 中，依序點選「File」>「New launcher」。

  4. 在「啟動器」分頁的「其他」部分中，按一下「Gemini CLI」圖塊。

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

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

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

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

提示範例

如需 Gemini CLI 的使用點子，請參閱下列範例提示：

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

  • 「Summarize the notebook named 'test-file', and propose next steps for the project.」(總結名為「test-file」的筆記本，並建議專案的後續步驟。)

  • 「I want to get a quick overview of the notebooks in this directory.針對每個 .ipynb 檔案，顯示檔案的前 5 行。」

  • 「Create a script using the contents of the 'test-file' notebook.」(使用「test-file」筆記本的內容建立指令碼。)

  • 「Show me how to access data from BigQuery tables from within Agent Platform Workbench.」(請說明如何從 Agent Platform Workbench 存取 BigQuery 資料表中的資料)。

  • 「Query the bigquery-public-data.ml_datasets.census_adult_income table to find the number of people with an income bracket of > 50K.」

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

  • 建立 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 中，但 CLI 不會回應提示。

  • 如果未授予 aiplatform.endpoints.predict 權限，管理員可以禁止部分身分使用 Gemini 端點進行推論。

使用 Gemini CLI Magic 指令

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

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

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

疑難排解

如果使用 Gemini CLI 時遇到 Agent Platform Workbench 執行個體相關問題，請參閱排解 Agent Platform Workbench 問題，瞭解如何解決常見問題。

後續步驟