使用 Gemini CLI

本頁說明如何搭配使用 Gemini 指令列介面 (CLI) 和 Vertex AI Workbench 執行個體。

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

總覽

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

Gemini CLI 可在 Vertex AI Workbench 執行個體中使用。 Gemini CLI 可以執行下列操作：

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

限制

透過 Vertex AI Workbench 使用 Gemini CLI 時，請注意下列限制：

  • 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 Vertex AI APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 Vertex AI APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    8.

必要的角色

如要在 Vertex AI Workbench 中使用 Gemini CLI，請務必授予 Vertex AI Workbench 執行個體的使用者和執行個體服務帳戶權限。

授予執行個體使用者權限

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

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

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

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

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

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

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

使用 Gemini CLI

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

    前往「Instances」(執行個體)

  2. 按一下 Vertex AI Workbench 執行個體名稱旁的「Open JupyterLab」(開啟 JupyterLab)。

    Vertex AI Workbench 執行個體會開啟 JupyterLab。

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

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

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

    Vertex AI 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」的筆記本，並建議專案的後續步驟。)

  • 「我想快速瞭解這個目錄中的筆記本。 針對每個 .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 Vertex AI Workbench.」(請說明如何從 Vertex AI 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 存取權

您可以使用下列方法，控管 Vertex AI Workbench 中 Gemini CLI 的存取權：

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

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

使用 Gemini CLI Magic 指令

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

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

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

疑難排解

如果使用 Gemini CLI 搭配 Vertex AI Workbench 執行個體時遇到問題，請參閱「排解 Vertex AI Workbench 問題」，瞭解如何解決常見問題。

後續步驟