Início rápido: implemente o seu comando do Vertex AI Studio como uma aplicação Web

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

No Vertex AI Studio, pode criar e iterar os seus comandos e comparar os resultados de diferentes configurações e modelos. Depois de terminar a engenharia do comando, pode implementar o comando como uma aplicação Web para partilhar com os seus colaboradores ou utilizadores-alvo para que possam testar a aplicação Web. A aplicação Web está alojada no Cloud Run e está disponível fora da Google Cloud consola.

Neste início rápido, vai:

• Crie um comando com variáveis de comando
• Implemente o seu comando como uma app Web
• Monitorize o progresso da implementação e teste a aplicação implementada
• Atualize e volte a implementar o comando
• Teste o envio de comandos com suporte multimodal

Antes de começar

Se nunca usou o Vertex AI Studio, pode seguir outro guia de início rápido ou fazer o curso do Google Cloud Skills Boost para aprender os básicos do Vertex AI Studio. Neste guia, deve ter o seguinte:

1. Um projeto do Google Cloud com faturação e a API Vertex AI ativada.
2. As funções necessárias para implementar um comando do Vertex AI Studio como uma aplicação Web. Se criou um novo projeto para este guia, já tem as autorizações necessárias.

Opcionalmente, também pode garantir que a conta de serviço predefinida do Compute Engine tem as funções necessárias para a conta de serviço de implementação. Se tiver autorização para atribuir funções, pode atribuir estas funções quando implementar a sua aplicação.

Funções necessárias

Para receber as autorizações de que precisa para implementar um comando do Vertex AI Studio como uma aplicação Web, peça ao seu administrador para lhe conceder as seguintes funções do IAM no seu projeto:

• Utilizador do Vertex AI (roles/aiplatform.user)
• Ative as APIs necessárias: Administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin)
• Conceda as funções necessárias à conta de serviço predefinida do Compute Engine: Administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin)
• Implemente uma aplicação do Cloud Run:
  • Administrador do Cloud Run (roles/run.admin)
  • Programador de origem do Cloud Run (roles/run.sourceDeveloper)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Funções necessárias para a conta de serviço de implementação

Para garantir que a conta de serviço predefinida do Compute Engine tem as autorizações necessárias para executar compilações em seu nome, peça ao seu administrador para conceder à conta de serviço predefinida do Compute Engine as seguintes funções de IAM no seu projeto:

Importante: tem de conceder estas funções à conta de serviço predefinida do Compute Engine e não à sua conta de utilizador. Se não conceder as funções ao principal correto, podem ocorrer erros de autorização.

• Agente de serviço da Vertex AI (roles/aiplatform.serviceAgent)
• Conta de serviço do Cloud Build (roles/cloudbuild.builds.builder)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

O administrador também pode conceder à conta de serviço predefinida do Compute Engine as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Se tiver autorização para conceder funções, pode conceder estas funções quando implementar a sua aplicação.

Crie um comando com variáveis de comando

Navegue para a página de criação de comandos do Vertex AI Studio e, de seguida, clique em Adicionar variável na caixa de entrada de comandos.

Na caixa de diálogo Gerir variáveis de comando, introduza um nome de variável e atribua-lhe um valor. Em seguida, clique em Aplicar.

Na caixa de entrada de comandos, crie o comando com a variável e, em seguida, ajuste outros parâmetros. Por exemplo, pode ativar a Fundamentação com a Pesquisa Google e ter "Obter sempre o tempo atual da Web" como as instruções do sistema.

Implemente o seu comando como uma app Web

Para implementar o seu comando como uma aplicação Web, clique no botão Criar com código no canto superior direito. Em seguida, clique em Implementar como app.

Guarde o comando

A caixa de diálogo de comando de guardar é apresentada, uma vez que é necessário guardar antes de poder implementar um comando. A caixa de diálogo de implementação é aberta automaticamente assim que o comando for guardado.

Nota: a primeira vez que guarda o comando numa região, pode demorar 2 a 3 minutos a concluir. É apresentada uma caixa de aviso após 1 minuto. Espera-se que seja uma operação lenta única. Quaisquer ações de guardar comandos subsequentes quando usar o mesmo projeto e região demoram apenas alguns segundos.

Ative as APIs para a primeira implementação e conceda autorizações

1. Depois de guardar o comando, o processo de implementação continua. Se esta for a sua primeira implementação, é apresentada uma caixa de diálogo para ativar as APIs necessárias. Clique em Ativar APIs necessárias.
2. Depois de as APIs serem ativadas, é apresentada a caixa de diálogo Criar uma app Web. Pode optar por autenticação obrigatória (através do Identity Aware Proxy) ou permitir acesso público.
   • Se escolher a autenticação obrigatória, siga o guia para conceder acesso (inclua-se).
   • Quando a opção Permitir acesso público é escolhida, significa que qualquer pessoa pode aceder à app. Por conseguinte, não inclua informações confidenciais ou de identificação pessoal (IIP) no seu comando. Selecione a caixa de verificação Compreendo que esta app vai ser implementada publicamente para confirmar.
3. Clique em Criar app para iniciar a implementação.
4. Se esta for a sua primeira implementação, é apresentado outro diálogo a pedir-lhe que conceda as funções necessárias à conta de serviço. Clique em Conceder tudo para continuar.

   Nota: se não tiver autorizações para ativar APIs ou conceder acesso, peça ao administrador do projeto para lhe conceder as autorizações necessárias. Consulte as funções necessárias para a conta de serviço de implementação para ver mais detalhes.

Início da implementação

O Vertex AI Studio cria um ficheiro ZIP que contém o código fonte da aplicação Web e carrega o ficheiro ZIP para um contentor do Cloud Storage. Depois de o implemento começar, é apresentado o diálogo Gerir app Web com informações sobre o seu implemento, como o nome da aplicação, a data do último implemento, o respetivo estado de implementação e muito mais.

Monitorizar o estado da implementação

A implementação demora 2 a 3 minutos a ser concluída e o estado da implementação é apresentado na coluna Estado da caixa de diálogo Gerir app Web. Se fechar a caixa de diálogo Gerir app Web, pode reabri-la no menu abaixo do botão Criar com código.

Quando a implementação estiver concluída, a coluna de estado muda para Pronto e o botão Abrir é apresentado junto ao nome da aplicação.

Controlo de acesso e chave secreta

A sua aplicação Web é implementada com o controlo de acesso Permitir não autenticado ativado por predefinição. Pode desativar esta opção clicando no botão do ícone de lápis . Consulte a secção Desative o acesso público para mais informações.

Para oferecer proteção básica, a aplicação Web requer que uma chave secreta seja anexada ao URL para enviar o comando. Pode encontrar a chave secreta na coluna Chave secreta. Se abrir a aplicação Web a partir do Vertex AI Studio, a chave é anexada ao URL automaticamente.

Abra a aplicação Web e envie o comando

Clique em Abrir na caixa de diálogo Gerir app Web para aceder à aplicação implementada. A aplicação deve ser aberta com a chave secreta anexada ao URL no formato ?key=SECRET_KEY.

Introduza um valor para a variável e, de seguida, clique em Enviar. Deve conseguir ver os resultados à direita.

Abra a aplicação Web a partir do menu do botão Criar com código

Se a sua aplicação Web estiver pronta, também a pode abrir a partir do menu do botão Criar com código.

O Cloud Run é um serviço sem servidor, o que significa que o contentor da aplicação é encerrado se não for usado ativamente. Por conseguinte, a aplicação Web pode demorar alguns segundos a carregar ou um envio não funciona se tiver deixado a aplicação Web inativa durante demasiado tempo. Atualizar a página deve resolver este problema.

Monitorizar o estado a partir do sino de notificações

Também pode monitorizar o estado no menu Notificações clicando no ícone de sino. O ícone de sino para a animação de carregamento e mostra um círculo verde se a implementação for concluída com êxito.

Se clicar na notificação, é redirecionado para a página do Cloud Run. O URL na página do Cloud Run não tem a chave secreta anexada. Tem de a anexar manualmente no formato ?key=SECRET_KEY.

Atualize e volte a implementar o comando

Pode editar ainda mais o comando no Vertex AI Studio e transformá-lo numa conversa. Em seguida, clique no botão Criar com código e clique em Gerir app para abrir a caixa de diálogo Gerir app Web. Clique em Atualizar app para voltar a implementar a sua aplicação Web com o comando atualizado.

É apresentada uma caixa de diálogo de confirmação. Indica que, se voltar a implementar, perde todas as alterações feitas à aplicação Web implementada fora do Vertex AI Studio (por exemplo, no editor de código-fonte do Cloud Run). Clique em Confirmar para continuar.

A caixa de diálogo Faça a gestão da app Web é apresentada novamente. O processo é semelhante à implementação inicial. Pode monitorizar o progresso da mesma forma que a primeira implementação.

Após a atualização, pode abrir novamente a aplicação Web. É apresentada a IU de conversa com a variável de comando. Preencha o valor e escreva qualquer conteúdo não vazio para continuar a conversa.

Insira conteúdo multimodal

Pode inserir entradas como imagens, vídeo, áudio e documentos na IU de conversa. As entradas suportadas dependem do modelo selecionado para o comando. Consulte a documentação para obter apoio técnico multimodal para cada modelo.

Para inserir um ficheiro, clique no botão do ícone de clipe na caixa de introdução da conversa.

Pode interagir com o modelo através da entrada que fornecer.

Tópicos avançados

Depois de se familiarizar com o processo de implementação, pode considerar as seguintes ações.

Edite o código-fonte no Cloud Run

Se quiser personalizar a aplicação Web, pode fazer alterações ao código fonte no Cloud Run. Abra a página do código fonte do Cloud Run a partir da caixa de diálogo Gerir app para a Web clicando no botão do ícone Mais no final da linha.

Em alternativa, também pode navegar para a página de segurança a partir da aplicação 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 Guardar e voltar a implementar.

Nota: o Cloud Run não suporta o controlo de versões diretamente. Se voltar a implementar a partir do Vertex AI Studio, as alterações também são substituídas. Para guardar uma versão, pode clicar em Transferir ZIP no canto inferior esquerdo para guardar a versão atual antes de voltar a implementar.

Após a nova implementação estar concluída, tem de abrir a aplicação a partir do Vertex AI Studio. Pode navegar para a página do Vertex AI Studio a partir do link no emblema Implementado a partir do Vertex AI.

Conceder acesso

Para conceder aos utilizadores ou grupos acesso à app, siga os passos:

1. Abra a caixa de diálogo Gerir app Web.
2. Clique no ícone de lápis na coluna Controlo de acesso. A página de segurança do Cloud Run é aberta num novo separador.
3. Na página de segurança do Cloud Run, encontre a caixa de verificação do Identity-Aware Proxy (IAP). Certifique-se de que está selecionada e, em seguida, clique em Editar política.
4. É apresentada uma subtarefa que lhe permite editar o acesso. Introduza os emails de utilizadores ou grupos no campo Principal. Se for um utilizador de uma organização, só pode adicionar utilizadores da mesma organização.
   
5. Deixe o campo dos níveis de acesso vazio.
6. Clique em Guardar.
7. Depois de fechar a subtarefa, clique novamente em Guardar na página do Cloud Run.
   
   O segundo passo de clique em Guardar é necessário para que as alterações entrem em vigor. Também existe um potencial atraso de alguns minutos para que a edição da política seja eficaz.

Desative o acesso público

Quando não precisa que a aplicação Web seja acessível publicamente, pode desativá-la no Cloud Run. Abra a caixa de diálogo Gerir app Web e clique no ícone de lápis na coluna Controlo de acesso. A página de segurança do Cloud Run é aberta num novo separador.

Também pode navegar para a página de segurança a partir da aplicação Web clicando no link Definições de segurança.

Na página Segurança do serviço do Cloud Run correspondente à sua aplicação Web, selecione Usar o Cloud IAM para autenticar pedidos recebidos e escolha Exigir autenticação. Clique em Guardar.

Isto vai fazer com que a sua aplicação Web deixe de estar acessível através do URL. Se tentar aceder a esta página, é apresentado o erro Erro: proibido.

Ative novamente o acesso público

Se quiser ativar novamente o acesso público, desmarque a caixa de verificação Usar o Cloud IAM para autenticar pedidos recebidos e guarde. Se escolher a opção Permitir invocações não autenticadas, esta não funciona se o seu projeto estiver numa organização. Consulte a autenticação no Cloud Run para mais detalhes.

Configure o acesso local para desenvolvimento

Na Pré-visualização pública, o controlo de acesso ainda não é suportado. Por conseguinte, depois de desativar o acesso público, a única forma de aceder à aplicação Web é configurar um proxy local. Pode fazê-lo através de comandos gcloud. Primeiro, abra o Cloud Shell através do botão ícone do terminal no canto superior direito da Google Cloud consola. É-lhe pedido que autorize o Cloud Shell. Clique em Autorizar para continuar.

Quando terminar, abra a caixa de diálogo Gerir app Web e clique no botão do ícone mais no final da linha para ver mais ações. Clique em Configurar acesso local através do Cloud Shell.

É adicionado um comando ao Cloud Shell. Prima Enter e aguarde até que a impressão esteja concluída. Clique no link na linha que começa com Click on the link to preview. Pode ver a sua candidatura. Este link só funciona quando o comando gcloud está em execução.

Problemas comuns

Erro de autenticação: nenhuma chave secreta

Se vir o seguinte erro, significa que não foi anexada nenhuma chave secreta ao URL. Siga as instruções para abrir a aplicação Web a partir do Vertex AI Studio ou copie a chave secreta da caixa de diálogo Gerir app e anexe-a ao URL no formato ?key=SECRET_KEY.

Erro de autenticação: chave secreta inválida

O erro seguinte significa que a chave anexada ao URL é inválida. A chave secreta é exclusiva de cada comando. Se tiver uma chave secreta de outro comando, não funciona. Siga as instruções para abrir a aplicação Web corretamente.

400 Argumento inválido: entrada vazia

O seguinte erro ocorre quando tem entradas na variável de comando, mas o chat está vazio. É apresentada uma mensagem de erro 400. Pode corrigir este problema escrevendo algo que não esteja vazio e voltando a enviar.

400 Argumento inválido: o tipo MIME não é suportado

Se escolher um tipo de ficheiro que o modelo não suporta, é devolvido um erro 400. Isto é esperado e tem de usar outros tipos de ficheiros suportados pelo modelo. Consulte a documentação para ver o suporte multimodal de cada modelo.

Passos seguintes

• Consulte mais funcionalidades no Vertex AI Studio na documentação ou no curso Introdução ao Vertex AI Studio Google Cloud Skills Boost.

• Consulte os preços do Cloud Run.

• Consulte a autenticação no Cloud Run.