Usar a CLI do Gemini

Nesta página, descrevemos como usar a interface de linha de comando (CLI) do Gemini com uma instância do Gemini Enterprise Agent Platform Workbench.

Este documento é destinado a analistas de dados, cientistas de dados e desenvolvedores de dados que trabalham com o Workbench da plataforma do agente. Este documento pressupõe que você saiba como escrever código em um ambiente de notebook.

Visão geral

A CLI do Gemini é um agente de IA de código aberto que dá acesso ao Gemini diretamente em um terminal. Para mais informações, acesse geminicli.com.

A CLI do Gemini está disponível nas instâncias do Workbench da Agent Platform. Você pode usar a CLI do Gemini para:

  • Crie um notebook.
  • Executar células do notebook.
  • Escrever e editar o código e as células de texto de um notebook.
  • Explicar códigos e conceitos técnicos.
  • Interagir com o sistema de arquivos local de uma instância do Workbench da Plataforma de Agentes, incluindo a execução de operações de arquivo complexas que abrangem vários arquivos com base em uma única instrução de alto nível.
  • Executar comandos básicos do shell.
  • Executar comandos para interagir com outros serviços do Google Cloud , como a Gemini Enterprise Agent Platform e o BigQuery.

Limitações

Considere as seguintes limitações ao usar a CLI do Gemini com o Agent Platform Workbench:

  • A CLI do Gemini é apenas uma CLI. Uma interface gráfica de chat e ferramentas avançadas no editor não estão incluídas.

  • Quando você pede para a CLI do Gemini modificar um notebook, ela muda o arquivo do notebook diretamente no disco da instância. Por isso, não é possível desfazer as edições feitas pela CLI do Gemini usando o botão Desfazer do editor de notebooks ou Control+Z (Command+Z no macOS). No entanto, você pode pedir à CLI do Gemini para desfazer uma mudança usando um comando de linguagem natural, como Undo your last change.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.
  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

Funções exigidas

Para usar a CLI do Gemini no Agent Platform Workbench, é necessário conceder permissões ao usuário da instância do Agent Platform Workbench e à conta de serviço da instância.

Conceder permissões ao usuário da instância

Para receber as permissões necessárias para usar a CLI do Gemini em uma instância do Workbench da Agent Platform, peça ao administrador para conceder a você o papel do IAM de usuário da Agent Platform (roles/aiplatform.user) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder uma permissão à conta de serviço da instância

Para garantir que a conta de serviço da instância do Agent Platform Workbench tenha a permissão necessária para permitir que a CLI do Gemini seja executada em uma instância do Agent Platform Workbench, peça ao administrador para conceder o papel do IAM de Usuário do Agent Platform (roles/aiplatform.user) à conta de serviço da instância do Agent Platform Workbench no projeto.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão aiplatform.endpoints.predict, que é necessária para permitir que a CLI do Gemini seja executada em uma instância do Workbench da plataforma de agentes.

O administrador também pode conceder essa permissão à conta de serviço da instância do Agent Platform Workbench com papéis personalizados ou outros papéis predefinidos.

Usar a CLI do Gemini

  1. No console do Google Cloud , acesse a página Instâncias.

    Acesse "Instâncias"

  2. Ao lado do nome de uma instância do Agent Platform Workbench, clique em Abrir JupyterLab.

    A instância do Agent Platform Workbench abre o JupyterLab.

  3. No JupyterLab, clique em Arquivo > Nova tela de início.

  4. Na guia Acesso rápido, na seção Outros, clique no bloco CLI do Gemini.

  5. Se esta for a primeira vez que você abre um terminal da CLI do Gemini, digite Y para aceitar os Termos e Condições.

    A instância do Agent Platform Workbench instala a CLI do Gemini.

  6. No terminal da CLI do Gemini, insira um comando.

    Por exemplo, digite Create a new notebook named 'test-notebook'. Para ver exemplos de comandos que podem ser úteis, consulte Exemplos de comandos.

Comandos de amostra

Para ter ideias de como usar a CLI do Gemini, confira os seguintes exemplos de comandos:

  • "Crie um notebook que treine um modelo para prever 'faixa de renda' de bigquery-public-data.ml_datasets.census_adult_income, usando o BigQuery e o Python."

  • "Resuma o notebook chamado 'test-file' e proponha as próximas etapas para o projeto."

  • "Quero uma visão geral rápida dos notebooks neste diretório. Para cada arquivo .ipynb, mostre as primeiras cinco linhas."

  • "Crie um script usando o conteúdo do notebook 'test-file'."

  • "Mostre como acessar dados de tabelas do BigQuery no Agent Platform Workbench."

  • "Consulte a tabela bigquery-public-data.ml_datasets.census_adult_income para encontrar o número de pessoas com uma faixa de renda > 50 mil."

  • "Defina meu projeto padrão do Google Cloud como my-project."

  • "Crie um bucket do Cloud Storage e faça upload de todos os arquivos CSV do meu diretório atual para ele."

  • "Criar uma instância do Compute Engine com uma imagem do Debian 11 e um tipo de máquina n1-standard-4."

  • "Crie um arquivo de notebook que execute o código em 'test-script'. Adicione células de texto que expliquem o código."

Controlar o acesso à CLI do Gemini

É possível controlar o acesso à CLI do Gemini no Agent Platform Workbench usando os seguintes métodos:

  • Um administrador pode configurar uma política da organização para restringir o uso de modelos específicos do Gemini no nível da organização, da pasta ou do projeto. Consulte Controlar o acesso aos modelos do Model Garden. A CLI do Gemini continua aparecendo no JupyterLab, mas não responde aos comandos.

  • Ao não conceder a permissão aiplatform.endpoints.predict, um administrador pode impedir que algumas identidades usem endpoints do Gemini para inferência.

Usar o comando mágico da CLI do Gemini

Para usar a CLI do Gemini diretamente em uma célula no arquivo do notebook, faça o seguinte:

  1. Verifique se a CLI do Gemini está ativada e se o usuário ou criador concordou com os Termos e Condições.
  2. Na primeira linha de uma nova célula, digite %%geminicli_magic.
  3. Na mesma célula, insira o comando na linha seguinte.
  4. Execute a célula.

A CLI do Gemini adiciona uma nova célula abaixo com a resposta.

Resolver problemas

Se você tiver problemas ao usar a CLI do Gemini com instâncias do Agent Platform Workbench, consulte Solução de problemas do Agent Platform Workbench para receber ajuda com problemas comuns.

A seguir