Usar a CLI do Gemini

Usar a CLI do Gemini

Prévia — Interface do Private Service Connect

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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

Este documento é destinado a analistas, cientistas e desenvolvedores de dados que trabalham com o Vertex AI Workbench. Este documento pressupõe que você saiba 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, consulte geminicli.com.

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

• Crie um notebook.
• Executar células de 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 Vertex AI Workbench, incluindo a execução de operações complexas em 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 Vertex AI e o BigQuery.

Limitações

Considere as seguintes limitações ao usar a CLI do Gemini com o Vertex AI 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 ao Gemini CLI para modificar um notebook, a CLI do Gemini muda o arquivo diretamente no disco da instância. Por isso, não é possível desfazer 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 para a CLI do Gemini desfazer uma mudança usando um comando em linguagem natural, como Undo your last change.

Antes de começar

Como uma tecnologia em estágio inicial, os produtos do Gemini para Google Cloudpodem gerar uma saída plausível, mas que é factualmente incorreta. Recomendamos que você valide todas as saídas dos produtos do Gemini para Google Cloud antes de usá-las. Para mais informações, consulte Gemini para Google Cloud e IA responsável.

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Funções exigidas

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

Observação: a CLI do Gemini opera estritamente dentro das permissões do ambiente da sua instância do Vertex AI Workbench. Se você (ou a conta de serviço usada pela sua instância) não tiver permissão para acessar um recurso específico, a CLI do Gemini também não terá. Se um comando falhar devido a permissões, peça ao administrador para conceder as permissões necessárias.

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 Vertex AI Workbench, peça ao administrador para conceder a você o papel do IAM de usuário da Vertex AI (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 sua instância

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

Importante:conceda esse papel à conta de serviço da sua instância do Vertex AI Workbench, não à sua conta de usuário. Se o papel não for concedido ao principal correto, poderão ocorrer erros de permissão.

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 Vertex AI Workbench.

O administrador também pode conceder essa permissão à conta de serviço da instância do Vertex AI 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 Vertex AI Workbench, clique em Abrir JupyterLab.

   Sua instância do Vertex AI 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 concordar com os termos e condições.

   Sua instância do Vertex AI Workbench instala a CLI do Gemini.

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

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

Comandos de amostra

Para ajudar você a ter ideias de como usar a CLI do Gemini, confira os exemplos de comandos a seguir:

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

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

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

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

• "Mostre como acessar dados de tabelas do BigQuery no Vertex AI Workbench."

• "Consulte a tabela bigquery-public-data.ml_datasets.census_adult_income para encontrar o número de pessoas com uma faixa de renda superior a 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.

• "Crie 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 Vertex AI 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 do arquivo de 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, insira %%geminicli_magic.
3. Na mesma célula, insira o comando na linha a seguir.
4. Execute a célula.

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

Resolver problemas

Se você encontrar um problema ao usar a CLI do Gemini com instâncias do Vertex AI Workbench, consulte Solução de problemas do Vertex AI Workbench para receber ajuda com problemas comuns.

A seguir

• Saiba mais sobre o Gemini.

• Para saber mais sobre métodos de consulta de dados do BigQuery em notebooks do Vertex AI Workbench, consulte Consultar dados no BigQuery pelo JupyterLab.