使用 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 实例的本地文件系统进行交互，包括根据单个高级指令执行跨多个文件的复杂文件操作。
  • 运行基本 Shell 命令。
  • 运行命令以与其他 Google Cloud 服务（例如 Vertex AI 和 BigQuery）进行交互。

限制

将 Gemini CLI 与 Vertex AI 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 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 User (roles/aiplatform.user) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

向实例的服务帐号授予权限

如需确保 Vertex AI Workbench 实例的服务帐号拥有必要的 权限，以便 Gemini CLI 能够在 Vertex AI Workbench 实例中运行， 请让您的管理员为 Vertex AI User (roles/aiplatform.user) IAM 角色授予项目的 Vertex AI Workbench 实例的服务帐号。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含 aiplatform.endpoints.predict 权限， 这是使 Gemini CLI 能够在 Vertex AI Workbench 实例中运行所必需的权限。

您的管理员也可以使用自定义角色或其他预定义角色为 Vertex AI Workbench 实例的服务帐号授予此权限。

使用 Gemini CLI

  1. 在 Google Cloud 控制台中，前往实例页面。

    转到实例

  2. 在 Vertex AI Workbench 实例名称旁边， 点击 打开 JupyterLab。

    您的 Vertex AI Workbench 实例会打开 JupyterLab。

  3. 在 JupyterLab 中，依次点击文件 > 新建启动器。

  4. 在启动器 标签页的其他 部分中， 点击 Gemini CLI 图块。

  5. 如果您是首次打开 Gemini CLI 终端， 请输入 Y 以同意相关条款及条件。

    您的 Vertex AI Workbench 实例会安装 Gemini CLI。

  6. 在 Gemini CLI 终端中，输入提示。

    例如，您可以输入 Create a new notebook named 'test-notebook'。如需查看可能对您有帮助的提示示例，请参阅提示示例。

提示示例

如需帮助您了解如何使用 Gemini CLI，请参阅以下提示示例：

  • “Create a new notebook that trains a model to predict 'income bracket' from bigquery-public-data.ml_datasets.census_adult_income, using BigQuery and Python.”

  • “Summarize the notebook named 'test-file', and propose next steps for the project.”

  • “I want to get a quick overview of the notebooks in this directory. For every .ipynb file, show me the first 5 lines of the file.”

  • “Create a script using the contents of the 'test-file' notebook.”

  • “Show me how to access data from BigQuery tables from within Vertex AI Workbench.”

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

  • “Set my default Google Cloud project to my-project.”

  • 创建一个 Cloud Storage 存储桶，并将当前目录中的所有 CSV 文件上传到其中。

  • 创建具有 Debian 11 映像和 n1-standard-4 机器类型的 Compute Engine 实例。

  • “Create a notebook file that runs through the code in the 'test-script'. Add text cells that explain the code.”

控制对 Gemini CLI 的访问权限

您可以使用以下方法控制对 Vertex AI 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 和 Vertex AI Workbench 实例时遇到问题，请参阅排查 Vertex AI Workbench 问题以获取常见问题的帮助。

后续步骤