Preparação do ambiente no Google Cloud 

Antes de utilizar as funções da aplicação Busca por Imagem, é necessário preparar um ambiente no Google Cloud.

Essa preparação normalmente é realizada uma única vez durante a implantação do módulo e deve ser executada pelo responsável técnico, administrador do Google Cloud ou parceiro responsável pela instalação do PlusCom.

Depois que o ambiente estiver configurado, os usuários poderão utilizar a aplicação para enviar imagens, importar assets, analisar o corpus, criar o índice e disponibilizar a pesquisa visual, feita pelo módulo de configuração.

1. Criar uma Conta do Google

Para acessar o Google Cloud, é necessário possuir uma Conta do Google.

Pode ser utilizada:

• uma conta do Gmail;

• uma conta corporativa administrada pelo Google Workspace;

• uma Conta do Google criada com um endereço de e-mail corporativo já existente.

Para ambientes empresariais, recomenda-se utilizar uma conta pertencente à empresa, e não uma conta pessoal de um funcionário ou prestador de serviço.

A conta principal deve permanecer sob controle da empresa e possuir mecanismos adequados de recuperação e autenticação em duas etapas.

2. Acessar o Google Cloud

Com a Conta do Google criada, acesse o Console do Google Cloud e conclua o cadastro inicial.

Durante o primeiro acesso, o Google poderá solicitar:

• aceitação dos termos de uso;

• dados da empresa ou do responsável;

• país e moeda da conta;

• forma de pagamento;

• confirmação da identidade ou do meio de pagamento.

Novos clientes podem encontrar ofertas de avaliação ou créditos promocionais. Entretanto, essas ofertas podem mudar e não substituem a necessidade de controlar o faturamento.

3. Criar uma conta de faturamento

Os serviços utilizados pela busca por imagem podem gerar cobranças. Por isso, o projeto precisa estar associado a uma conta ativa do Cloud Billing.

No Console do Google Cloud:

1. abra o menu principal;

2. acesse Faturamento;

3. crie ou selecione uma conta de faturamento;

4. informe os dados solicitados;

5. confirme a forma de pagamento.

A conta de faturamento não é a mesma coisa que o projeto. Uma conta de faturamento pode pagar os custos de um ou mais projetos.

Controle de custos

Depois de configurar o faturamento, recomenda-se criar um orçamento em:

Faturamento > Orçamentos e alertas

Defina um valor mensal compatível com a utilização esperada e configure alertas por e-mail.

O orçamento serve para acompanhar os gastos e emitir avisos. Ele não interrompe automaticamente os serviços quando o valor definido é atingido.

4. Criar um projeto para a Busca por Imagem

No seletor de projetos localizado na parte superior do Console do Google Cloud:

1. clique em Novo projeto;

2. informe um nome que identifique o ambiente;

3. selecione a organização ou pasta, quando aplicável;

4. vincule o projeto à conta de faturamento;

5. conclua a criação.

Exemplo de nome:

PlusCom – Busca por Imagem – Produção

Sempre que possível, utilize um projeto exclusivo para essa integração. Isso facilita o controle de permissões, custos, auditoria e recursos utilizados.

Identificadores do projeto

O Google Cloud possui três identificações diferentes:

• Nome do projeto: descrição apresentada ao usuário;

• ID do projeto: identificação textual única;

• Número do projeto: identificação numérica gerada pelo Google.

A aplicação utiliza o número do projeto para acessar os recursos do Vision Warehouse.

Anote o número do projeto apresentado na área de informações do projeto e encaminhe-o ao responsável pela configuração da aplicação.

5. Ativar as APIs necessárias

Com o projeto correto selecionado, acesse:

APIs e serviços > Biblioteca

Pesquise e ative os serviços necessários.

Gemini Enterprise Agent Platform Vision API

Ative a API identificada pelo serviço:

visionai.googleapis.com

Dependendo do idioma e da atualização do Console, ela poderá aparecer com nomes como:

• Agent Platform Vision;

• Gemini Enterprise Agent Platform Vision;

• Vertex AI Vision;

• Vision AI API.

Essa é a API utilizada para trabalhar com:

• corpus;

• assets;

• análise de imagens;

• índices;

• IndexEndpoints;

• deploy e undeploy;

• pesquisa visual.

Cloud Storage API

Ative também a API do Cloud Storage, utilizada para armazenar:

• imagens dos produtos;

• manifestos de importação;

• arquivos auxiliares utilizados no processamento.

Em algumas contas, o Cloud Storage já poderá estar disponível por padrão. Mesmo assim, confirme sua disponibilidade no projeto.

6. Definir a região do ambiente

O corpus de imagens deve ser criado na região:

us-central1

Na versão atualmente utilizada, os warehouses de imagens são suportados nessa região.

Todos os componentes relacionados ao Vision Warehouse devem utilizar a mesma localização configurada na aplicação.

Não altere a região depois de iniciar a implantação sem revisar todos os identificadores e recursos utilizados pelo módulo.

Atenção sobre localização dos dados

A escolha da região define a localização lógica do recurso. Entretanto, a documentação do Google informa que determinados recursos podem ser replicados para disponibilidade e recuperação.

Empresas que possuam requisitos específicos de residência de dados, contratos ou conformidade devem avaliar essa condição antes da utilização do serviço.

7. Criar um bucket no Cloud Storage

No Console do Google Cloud, acesse:

Cloud Storage > Buckets

Clique em Criar e informe os dados do bucket.

Nome do bucket

O nome precisa ser único em todo o Google Cloud.

Utilize um nome que identifique a empresa e o ambiente, por exemplo:

empresa-pluscom-busca-imagem-producao

Não utilize o mesmo bucket para produção e testes.

Localização

Sempre que possível, selecione uma localização compatível com o ambiente do Vision Warehouse, preferencialmente us-central1.

Classe de armazenamento

Para a utilização normal da aplicação, pode ser utilizada a classe de armazenamento padrão indicada pelo Google Cloud para acesso frequente.

Controle de acesso

Recomenda-se utilizar o acesso uniforme no nível do bucket, para que as permissões sejam administradas pelo IAM.

O bucket não deve ser público.

A aplicação criará objetos organizados em áreas como:

• Produtos;

• Manifestos.

Esses nomes representam caminhos lógicos dentro do bucket. Normalmente, não é necessário criar essas pastas manualmente.

8. Criar uma conta de serviço

A aplicação não utiliza diretamente a conta pessoal do usuário que acessa o Console do Google Cloud.

Ela utiliza uma conta de serviço, que funciona como uma identidade própria para o sistema.

No Console do Google Cloud, acesse:

IAM e administrador > Contas de serviço

Depois:

1. clique em Criar conta de serviço;

2. informe um nome identificável;

3. inclua uma descrição;

4. conclua a criação.

Exemplo de nome:

pluscom-busca-imagem

A descrição pode informar que a conta é utilizada pelo módulo de busca visual de produtos do PlusCom.

9. Conceder as permissões necessárias

A conta de serviço precisa ter permissão para trabalhar com o Vision Warehouse e com o bucket.

Permissão do Vision Warehouse

Conceda à conta de serviço o papel:

VisionAI Editor

Identificação técnica:

roles/visionai.editor

Esse papel permite que a aplicação trabalhe com os recursos necessários do Agent Platform Vision.

Não confunda esse papel com o papel interno de Cloud Vision AI Service Agent. Papéis de service agent são destinados aos agentes administrados pelo próprio Google e não devem ser atribuídos manualmente à conta da aplicação.

Permissão do Cloud Storage

A conta de serviço precisa conseguir criar, visualizar e gerenciar os objetos utilizados pela aplicação no bucket.

Uma opção prática é conceder no próprio bucket o papel:

Administrador de objetos do Storage

Identificação técnica:

roles/storage.objectAdmin

Sempre que possível, aplique essa permissão somente ao bucket da Busca por Imagem, e não a todos os buckets do projeto.

A definição final das permissões deve respeitar o princípio do menor privilégio e as políticas de segurança da empresa.

10. Criar a chave JSON da conta de serviço

A versão atual da aplicação utiliza um arquivo JSON para se autenticar no Google Cloud.

Na conta de serviço criada:

1. abra a conta de serviço;

2. acesse a guia Chaves;

3. clique em Adicionar chave;

4. selecione Criar nova chave;

5. escolha o formato JSON;

6. confirme a criação.

O navegador fará o download do arquivo.

Esse arquivo contém uma chave privada e permite que um sistema utilize as permissões da conta de serviço.

Cuidados com o arquivo

O arquivo JSON deve:

• ser armazenado em uma pasta protegida;

• ficar disponível somente no computador ou servidor que executa a aplicação;

• ter seu caminho informado na configuração da aplicação;

• possuir acesso restrito aos administradores autorizados;

• ser incluído na rotina de controle e substituição de credenciais.

O arquivo não deve:

• ser enviado por e-mail;

• ser compartilhado em aplicativos de mensagens;

• ser colocado em pastas públicas;

• ser incluído no código-fonte;

• ser armazenado em repositórios de desenvolvimento;

• ser entregue a usuários que não administram a integração.

Depois de gerar a chave, o Google não permite fazer novamente o download da mesma chave. Caso o arquivo seja perdido ou comprometido, crie uma nova chave e exclua a anterior.

11. Criar o Image Warehouse

A aplicação utiliza um Image Warehouse, representado tecnicamente por um recurso denominado corpus.

No Console do Google Cloud, utilize a barra de pesquisa para localizar:

Agent Platform Vision

Dependendo da versão e do idioma do Console, o serviço poderá ainda ser apresentado como Vertex AI Vision ou Vision AI.

Localize a área de Warehouses e crie um novo warehouse.

Na criação:

• selecione o tipo Imagem;

• utilize a região us-central1;

• informe um nome que identifique os produtos do PlusCom;

• habilite a capacidade de pesquisa por similaridade ou embeddings, quando essa opção for apresentada.

Exemplo de nome:

Produtos PlusCom

O corpus é o recipiente que armazenará os registros das imagens importadas pela aplicação.

Identificador do corpus

Depois da criação, localize e anote o Corpus ID.

Esse identificador deve ser informado ao responsável técnico para a configuração da aplicação.

A aplicação analisada pressupõe que o corpus já exista antes do primeiro envio de assets.

12. Preparar o metadado do código do produto

Cada imagem enviada pela aplicação é associada ao código do produto do PlusCom.

Na versão atual, a chave utilizada para essa associação é:

produto-id

Quando o manifesto de importação inclui uma anotação, o Vision Warehouse exige que exista um esquema de dados compatível antes da importação.

O responsável técnico deve criar, dentro do corpus, um Data Schema cuja chave seja exatamente igual à configurada na aplicação.

A chave não deve ser alterada diretamente no Google Cloud sem que a mesma alteração seja realizada na aplicação.

Os atributos do schema, como tipo do dado, granularidade e estratégia de pesquisa, devem seguir o formato do manifesto gerado pela versão implantada.

Caso o schema não corresponda ao manifesto, a importação poderá ser concluída com erro.

13. Registrar os dados da implantação

Ao concluir a preparação, registre os seguintes dados:

Informação

Finalidade

Nome do projeto

Identificação administrativa

ID do projeto

Administração do projeto no Google Cloud

Número do projeto

Acesso da aplicação às APIs

Região

Localização dos recursos do Vision Warehouse

Nome do bucket

Armazenamento das imagens e manifestos

Corpus ID

Identificação do Image Warehouse

Chave do metadado

Associação entre imagem e produto

E-mail da conta de serviço

Identificação da credencial utilizada

Caminho protegido do arquivo JSON

Autenticação da aplicação

Essas informações devem ser fornecidas ao responsável pela configuração do módulo.

Não inclua o conteúdo da chave privada em documentos de implantação ou manuais entregues aos usuários.

14. Recursos que não devem ser criados antecipadamente

A aplicação possui comandos próprios para:

• analisar o corpus;

• criar o índice;

• criar o IndexEndpoint;

• fazer o deploy do índice;

• fazer o undeploy do índice.

Por esse motivo, normalmente não é necessário criar manualmente índices ou IndexEndpoints no Console do Google Cloud antes da primeira utilização.

Criar recursos manualmente e novamente pela aplicação pode resultar em recursos duplicados e aumento de custos.

A criação manual somente deve ser realizada quando houver uma orientação técnica específica.

15. Configurar a aplicação

Depois da preparação do Google Cloud, o responsável técnico deve configurar na aplicação:

• número do projeto;

• região;

• Corpus ID;

• nome do bucket;

• chave de metadado do produto;

• caminho do arquivo JSON da conta de serviço.

Depois que a aplicação criar um IndexEndpoint e concluir seu deploy, o identificador do endpoint também deverá estar corretamente configurado para a janela de consulta por imagem.

Esses dados devem pertencer ao mesmo projeto e ao mesmo ambiente.

Não misture identificadores de produção com buckets, corpora ou credenciais de teste.

16. Verificação antes do primeiro uso

Antes de liberar o módulo, confirme:

• a Conta do Google está ativa;

• o projeto correto está selecionado;

• o faturamento está ativo;

• o orçamento e os alertas foram configurados;

• a API do Agent Platform Vision está habilitada;

• o Cloud Storage está habilitado;

• o bucket foi criado;

• o bucket não está público;

• a conta de serviço foi criada;

• a conta de serviço possui acesso ao Vision Warehouse;

• a conta de serviço possui acesso ao bucket;

• a chave JSON está armazenada em local protegido;

• o Image Warehouse foi criado em us-central1;

• o Corpus ID foi registrado;

• o schema do metadado foi criado, quando necessário;

• os identificadores foram configurados na aplicação.

Depois dessa validação, o usuário poderá iniciar o fluxo da aplicação:

1. informar o código do produto;

2. selecionar as imagens;

3. subir as imagens;

4. importar os itens pendentes;

5. consultar a importação;

6. analisar o corpus;

7. criar o índice;

8. criar o IndexEndpoint;

9. fazer o deploy;

10. testar a consulta por imagem.