No Vertex AI Studio, é possível criar e iterar comandos e comparar resultados de diferentes configurações e modelos. Depois de concluir a engenharia do comando, você pode implantá-lo como um aplicativo da Web para compartilhar com seus colaboradores ou usuários-alvo para que eles testem o aplicativo da Web. O aplicativo da Web é hospedado no Cloud Run e está disponível fora do console Google Cloud .
Neste guia de início rápido, você vai:
- Criar um comando com variáveis de comando
- Implantar seu comando como um aplicativo da Web
- Monitorar o progresso da implantação e testar o aplicativo implantado
- Atualizar e reimplantar o comando
- Testar o envio de comandos com suporte multimodal
Antes de começar
Se você nunca usou o Vertex AI Studio, siga outro guia de início rápido ou faça o curso do Google Cloud Skills Boost para aprender os conceitos básicos do Vertex AI Studio. Neste guia, você precisa ter o seguinte:
- Ter um projeto do Google Cloud criado com o faturamento ativado
- API Vertex AI ativada
Outras permissões são necessárias
Além das permissões atuais para usar o Vertex AI Studio, para implantar seu comando, você precisa ter as seguintes permissões:
| Ação | Permissões necessárias | Finalidade |
|---|---|---|
| Ativar APIs adicionais | serviceusage.services.enable |
Ative as APIs a seguir:
|
| Conceder permissões para contas de serviço | resourcemanager.projects.setIamPolicy |
Conceda à
conta de serviço padrão do Compute Engine os seguintes papéis:
|
| Implantar permissões específicas |
|
Durante a implantação, um conjunto de códigos-fonte será enviado por upload para o Cloud Storage e implantado no Cloud Run com um novo serviço criado. O artifactregistry.repositories.create
é necessário para criar um repositório para a imagem do contêiner.
O run.services.setIamPolicy é necessário para tornar o
serviço acessível publicamente.
|
Se você for o proprietário do projeto, não precisará realizar outras ações. Basta seguir os guias no Vertex AI Studio. Se você não for o
proprietário do projeto, peça ao administrador para realizar as duas primeiras
ações e conceder a você os papéis de
Editor (roles/editor) e
Administrador do Cloud Run
(roles/run.admin).
Criar um comando com variáveis de comando
Acesse a página de criação de comandos do Vertex AI Studio e clique em Adicionar variável na caixa de entrada de comandos.
Na caixa de diálogo Gerenciar variáveis de comando, insira um nome e um valor para a variável. Em seguida, clique em Aplicar.
Na caixa de entrada de comando, crie o comando usando a variável e ajuste outros parâmetros. Por exemplo, você pode ativar a Fundamentação com a Pesquisa Google e definir "Sempre receber a previsão do tempo atual da Web" como instruções do sistema.
Implantar seu comando como um aplicativo da Web
Para implantar seu comando como um aplicativo da Web, clique no botão Criar com código no canto superior direito. Em seguida, clique em Implantar como app.
Salve o comando
A caixa de diálogo de solicitação de salvamento vai aparecer, já que é necessário salvar antes de implantar um comando. A caixa de diálogo de implantação será aberta automaticamente depois que o comando for salvo.
Ativar APIs para a primeira implantação e conceder permissões
- Depois que o comando for salvo, o processo de implantação vai continuar. Se esta for sua primeira implantação, uma caixa de diálogo vai aparecer para ativar as APIs necessárias. Clique em Ativar APIs necessárias.
-
Depois que as APIs forem ativadas, a caixa de diálogo Criar um app da Web vai aparecer. Você pode escolher Autenticação obrigatória (via Identity-Aware Proxy) ou Permitir acesso público.
- Se a autenticação obrigatória for escolhida, siga o guia para conceder acesso (inclua você mesmo).
- Quando o acesso público é escolhido, significa que qualquer pessoa pode acessar o app. Portanto, não inclua informações sensíveis ou de identificação pessoal (PII) no comando. Marque a caixa de seleção Entendo que esse app será implantado publicamente para confirmar.
- Clique em Criar app para iniciar a implantação.
- Se esta for sua primeira implantação, outra caixa de diálogo vai aparecer pedindo que você conceda os papéis necessários à conta de serviço. Clique em Conceder tudo para continuar.
Se esta for sua primeira implantação, outra caixa de diálogo vai aparecer pedindo que você conceda os papéis necessários à conta de serviço. Clique em Conceder tudo para continuar.
Início da implantação
O Vertex AI Studio vai criar um arquivo ZIP com o código-fonte do aplicativo da Web e fazer upload dele para um bucket do Cloud Storage. Depois que a implantação for iniciada, a caixa de diálogo Gerenciar app da Web vai aparecer com informações sobre a implantação, como o nome do aplicativo, a data da última implantação, o status da implantação e muito mais.
Monitorar o status da implantação
A implantação leva de dois a três minutos para ser concluída, e o status dela é mostrado na coluna Status da caixa de diálogo Gerenciar app da Web. Se você fechar a caixa de diálogo Gerenciar app da Web, poderá reabri-la no menu abaixo do botão Criar com código.
Quando a implantação for concluída, a coluna de status vai mudar para Pronto, e o botão Abrir vai aparecer ao lado do nome do aplicativo.
Controle de acesso e chave secreta
Seu aplicativo da Web é implantado com o controle de acesso Permitir não autenticado ativado por padrão. Para desativar, clique no botão com o ícone de lápis . Consulte a seção sobre como desativar o acesso público para mais informações.
Para oferecer proteção básica, o aplicativo da Web exige que uma chave secreta seja anexada ao URL para enviar o comando. Ela está na coluna Chave secreta. Se você abrir o aplicativo da Web no Vertex AI Studio, a chave será anexada ao URL para você.
Abra o aplicativo da Web e envie o comando
Clique em Abrir na caixa de diálogo Gerenciar app da Web para acessar o aplicativo
implantado. O aplicativo deve ser aberto com a chave secreta anexada ao URL no formato ?key=SECRET_KEY.
Insira um valor para a variável e clique em Enviar. Os resultados vão aparecer à direita.
Abra o aplicativo da Web no menu do botão "Criar com código".
Se o aplicativo da Web estiver pronto, você também poderá abri-lo no menu do botão Criar com código.
O Cloud Run é um serviço sem servidor, o que significa que o contêiner do aplicativo será desligado se não estiver sendo usado ativamente. Por isso, o aplicativo da Web pode levar alguns segundos para carregar, ou um envio não vai funcionar se você deixar o aplicativo da Web inativo por muito tempo. Atualizar a página deve resolver esse problema.
Monitorar o status no ícone de notificação
Você também pode monitorar o status no menu Notificações clicando no ícone de sino. O ícone de sino vai parar a animação de carregamento e mostrar um círculo verde se a implantação for concluída com sucesso.
Se você clicar na notificação, ela vai redirecionar você para a página do Cloud Run. O URL na página do Cloud Run não tem a chave secreta anexada. Você vai precisar anexar manualmente no formato ?key=SECRET_KEY.
Atualizar e reimplantar o comando
Você pode editar ainda mais seu comando no Vertex AI Studio e transformá-lo em uma conversa. Em seguida, clique no botão Criar com código e em Gerenciar app para abrir a caixa de diálogo Gerenciar app da Web. Clique em Atualizar app para reimplantar seu aplicativo da Web com o comando atualizado.
Uma caixa de confirmação é exibida. Ele informa que, se você reimplantar, vai perder todas as mudanças feitas no aplicativo Web implantado fora do Vertex AI Studio (como no editor de código-fonte do Cloud Run). Clique em Confirmar para continuar.
A caixa de diálogo Gerenciar app da Web vai aparecer de novo. O processo é semelhante à implantação inicial. É possível monitorar o progresso da mesma forma que a primeira implantação.
Depois que a atualização for concluída, abra o aplicativo da Web novamente. A UI de conversa vai aparecer com a variável de comando. Preencha o valor e digite qualquer conteúdo não vazio para continuar a conversa.
Inserir conteúdo multimodal
Você pode inserir entradas como imagens, vídeos, áudios e documentos na UI de conversa. As entradas aceitas dependem do modelo selecionado para o comando. Consulte a documentação sobre suporte multimodal para cada modelo.
Para inserir um arquivo, clique no botão de ícone de clipe na caixa de entrada da conversa.
Você poderá interagir com o modelo usando as informações fornecidas.
Tópicos avançados
Depois de se familiarizar com o processo de implantação, considere as seguintes ações.
Editar código-fonte no Cloud Run
Se quiser personalizar o aplicativo da Web, faça mudanças no
código-fonte no Cloud Run. Abra a página do código-fonte do Cloud Run na caixa de diálogo Gerenciar app da Web clicando no botão de ícone mais no final da linha.
Outra opção é acessar a página de segurança no aplicativo da Web clicando no link Editor de código-fonte.
Na página do código-fonte do Cloud Run, clique em Editar fonte para iniciar o modo de edição. Quando terminar, clique em Salvar e reimplantar.
Depois que a nova implantação for concluída, abra o aplicativo no Vertex AI Studio. Você pode acessar a página do Vertex AI Studio pelo link no selo Implantado pela Vertex AI.
Conceder acesso
Para conceder acesso ao app a usuários ou grupos, siga estas etapas:
- Abra a caixa de diálogo Gerenciar app da Web.
- Clique no ícone de lápis na coluna Controle de acesso. A página de segurança do Cloud Run é aberta em uma nova guia.
- Na página de segurança do Cloud Run, encontre a caixa de seleção do Identity-Aware Proxy (IAP). Verifique se ela está marcada e clique em Editar política.
-
Uma subtarefa vai aparecer para você editar o acesso. Insira os e-mails de usuários ou grupos no campo Principal.
Se você for um usuário em uma organização, só poderá adicionar usuários da mesma organização.
- Deixe o campo "Níveis de acesso" em branco.
- Clique em Salvar.
-
Depois que a subtarefa for concluída, clique em Salvar novamente na página do Cloud Run.
Desativar o acesso público
Quando não for necessário que o aplicativo da Web esteja acessível publicamente, é possível desativá-lo no Cloud Run. Abra a caixa de diálogo Gerenciar app da Web e clique no ícone de lápis na coluna Controle de acesso. A página de segurança do Cloud Run será aberta em uma nova guia.
Você também pode acessar a página de segurança no aplicativo da Web clicando no link Configurações de segurança.
Na página "Segurança" do serviço do Cloud Run correspondente ao seu aplicativo da Web, marque a caixa Usar o Cloud IAM para autenticar as solicitações recebidas e escolha Exigir autenticação. Clique em Salvar.
Isso fará com que o aplicativo da Web não fique mais acessível pelo URL. Se você tentar acessar, vai aparecer uma página Erro: proibido.
Ative o acesso público novamente
Se você quiser reativar o acesso público, desmarque a caixa de seleção Usar o Cloud IAM para autenticar as solicitações recebidas e salve. Se você escolher a opção Permitir invocações não autenticadas, ela não vai funcionar se o projeto estiver em uma organização. Consulte autenticação no Cloud Run para mais detalhes.
Configurar o acesso local para desenvolvimento
No Acesso antecipado, o controle de acesso ainda não está disponível. Portanto, depois de desativar o acesso público, a única maneira de acessar o aplicativo da Web é configurando um proxy local. É possível fazer isso usando comandos gcloud. Primeiro, abra o Cloud Shell clicando no botão do ícone do terminal no canto superior direito do console do Google Cloud . Ele vai pedir que você autorize o Cloud Shell. Clique em Autorizar para continuar.
Quando terminar, abra a caixa de diálogo Gerenciar app da Web e clique no botão de ícone
mais no final da linha para ver mais ações. Clique em Configurar o acesso local pelo Cloud Shell.
Um comando será adicionado ao Cloud Shell. Pressione Enter e aguarde a conclusão da impressão. Clique no link na linha que começa com Click on the
link to preview. Você poderá conferir sua inscrição. Esse link
só funciona quando o comando gcloud está em execução.
Problemas comuns
Erro de autenticação: nenhuma chave secreta
Se você receber o seguinte erro, significa que nenhuma chave secreta foi anexada ao
URL. Siga as instruções para abrir o aplicativo da Web no Vertex AI Studio ou copie a chave secreta da caixa de diálogo Gerenciar app e anexe-a ao URL no formato ?key=SECRET_KEY.
Erro de autenticação: chave secreta inválida
O erro a seguir significa que a chave anexada ao URL é inválida. A chave secreta é exclusiva para cada comando. Se você tiver uma chave secreta de outro comando, ela não vai funcionar. Siga as instruções para abrir o aplicativo da Web corretamente.
400 Argumento inválido: entrada vazia
O seguinte erro ocorre quando você tem entradas na variável de comando, mas o chat está vazio. Uma mensagem de erro 400 vai aparecer. Para corrigir isso, digite algo que não esteja vazio e reenvie.
400 Argumento inválido: mimeType não é compatível
Se você escolher um tipo de arquivo que o modelo não aceita, ele vai retornar um erro 400. Isso é esperado, e você terá que usar outros tipos de arquivos compatíveis com o modelo. Consulte a documentação sobre o suporte multimodal de cada modelo.
Próximas etapas
Confira mais recursos do Vertex AI Studio na documentação ou no curso Introdução ao Vertex AI Studio Google Cloud Ensina.
Confira os preços do Cloud Run.
Confira autenticação no Cloud Run.