Módulo de Configuração

O Módulo de Configuração da Busca por Imagens é utilizado para enviar as imagens dos produtos ao Google Cloud, acompanhar o processamento dessas imagens e manter atualizado o índice utilizado nas pesquisas por similaridade visual.
A utilização deste módulo é feita após a preparação do ambiente no Google Cloud.

Por meio desse módulo, é possível:

• vincular imagens aos produtos cadastrados no PlusCom;

• enviar as imagens para o armazenamento do Google Cloud;

• importar as imagens para o corpus do Google Vision;

• analisar o corpus;

• atualizar o índice utilizado nas pesquisas;

• acompanhar as operações executadas;

• excluir ou substituir imagens já cadastradas;

• testar a consulta por similaridade visual;

• acessar as opções administrativas do ambiente.

Depois que a implantação inicial estiver concluída, a inclusão de novas imagens não exige a criação de outro índice, de outro endpoint ou a realização de um novo deploy.

Acessando o módulo

No PlusCom, acesse:

Cadastros → Produtos → Busca por Imagens → Módulo de Configuração

A tela principal apresenta as operações utilizadas no processo de envio, importação, análise e atualização das imagens.

As opções de configuração, gerenciamento e administração ficam disponíveis no botão Configurações, localizado na parte superior da tela.

Tela principal

A tela principal é dividida nas seguintes áreas:

Dados do produto

Nesta área, informe o código do produto ao qual as imagens serão vinculadas.

O código deve corresponder a um produto válido cadastrado no PlusCom.

Depois de informar o produto, clique em Selecionar imagens para localizar os arquivos no computador.

Podem ser selecionadas até seis imagens em cada envio.

Os formatos aceitos são:

• JPG;

• JPEG;

• PNG;

• WEBP.

Imagens selecionadas

Apresenta os arquivos escolhidos antes do envio.

O botão Limpar remove da tela o código informado e a lista de imagens selecionadas.

Essa operação não exclui imagens que já tenham sido enviadas ou importadas.

Fila local de imagens

Apresenta os registros das imagens enviadas pelo módulo.

Cada linha corresponde a uma imagem e contém informações como:

• código do produto;

• identificador do asset no Google;

• endereço do arquivo no Cloud Storage;

• operação vinculada;

• datas de processamento;

• status;

• mensagem de erro, quando existente.

Status da fila

Pendente

A imagem foi enviada ao Cloud Storage e registrada no banco de dados, mas ainda não foi importada para o corpus.

Importando

A imagem foi incluída em uma solicitação de importação e está sendo processada pelo Google.

Importado

A importação foi concluída com sucesso e a imagem está registrada no corpus.

Erro

A importação da imagem terminou com erro.

Excluindo

A exclusão da imagem foi solicitada e ainda está sendo processada.

ErroExclusao

Ocorreu um erro ao solicitar ou acompanhar a exclusão da imagem.

Operações gerais do Vision Warehouse

Apresenta as operações executadas sobre o corpus, o índice e o endpoint.

Entre as operações exibidas estão:

• análise do corpus;

• criação do índice;

• criação do endpoint;

• deploy do índice;

• atualização do índice;

• desativação do índice.

A grade permite acompanhar o tipo da operação, seu status, a descrição, o identificador retornado pelo Google, as datas de início e conclusão e eventuais mensagens de erro.

Inclusão de novas imagens

A inclusão rotineira de novas imagens deve seguir a sequência apresentada a seguir.

1. Informar o produto

No campo Código do Produto, informe o código do produto ao qual as imagens serão vinculadas.

2. Selecionar as imagens

Clique em Selecionar imagens.

Localize os arquivos no computador e selecione as imagens desejadas.

Os arquivos selecionados serão apresentados na lista de imagens da tela.

3. Subir as imagens

Clique em Subir imagens.

O sistema executará duas operações:

1. enviará os arquivos ao Cloud Storage;

2. criará os registros correspondentes na fila local com o status Pendente.

Neste momento, as imagens ainda não fazem parte do corpus utilizado pela busca.

É possível repetir esse procedimento para vários produtos antes de iniciar a importação.

Importação das imagens

4. Importar as imagens pendentes

Depois de concluir o envio das imagens, clique em Importar pendentes.

O sistema criará o manifesto necessário e enviará ao Google uma solicitação para importar todas as imagens que estiverem com o status Pendente.

Durante esse processo, as imagens passarão para o status Importando.

A importação é executada de forma assíncrona. Portanto, o retorno inicial da operação não significa que todas as imagens já foram processadas.

5. Consultar a importação

Clique em Consultar importação para verificar o andamento das importações.

Repita a consulta até que todas as imagens passem do status Importando para Importado.

Não execute a análise do corpus enquanto existirem imagens com os seguintes status:

• Pendente;

• Importando;

• Excluindo;

• ErroExclusao.

Caso alguma imagem apresente o status Erro, consulte a mensagem registrada antes de prosseguir.

Análise do corpus

6. Analisar o corpus

Depois que todas as novas imagens estiverem importadas, clique em Analisar corpus.

Essa operação prepara as imagens existentes no corpus para que possam ser utilizadas na pesquisa por similaridade visual.

A operação será registrada na grade Operações gerais do Vision Warehouse com o status Processando.

7. Consultar as operações

Clique em Consultar operações para acompanhar o processamento da análise.

Repita a consulta até que a operação AnalyzeCorpus apareça com o status Concluída.

O índice não deve ser atualizado antes da conclusão dessa operação.

Atualização do índice

8. Atualizar o índice

Depois que a análise do corpus estiver concluída, clique em Atualizar índice.

Essa operação atualiza o índice que já está implantado, incorporando as imagens atualmente existentes e analisadas no corpus.

Durante o processo normal de atualização:

• não é criado um novo índice;

• não é criado um novo endpoint;

• o índice atual não precisa ser desativado;

• não é necessário realizar outro deploy;

• o mesmo endpoint continua sendo utilizado pela consulta.

Antes de enviar a atualização, o sistema verifica:

• se existe um endpoint configurado;

• se o endpoint possui um índice implantado;

• se o índice pertence ao corpus configurado;

• se o endpoint e o índice estão disponíveis;

• se existem imagens pendentes;

• se existem imagens sendo importadas;

• se existem imagens sendo excluídas;

• se existem erros de exclusão;

• se a última análise foi concluída;

• se a análise foi realizada depois da última importação;

• se a análise já foi aplicada anteriormente ao índice;

• se existe outra operação geral em andamento.

Quando alguma dessas condições não for atendida, a operação será interrompida e o sistema apresentará a orientação correspondente.

9. Acompanhar a atualização

Depois de enviar a atualização, clique em Consultar operações.

Repita a consulta até que a operação UpdateIndex apareça com o status Concluída.

Após a conclusão, as novas imagens estarão disponíveis na pesquisa por similaridade visual.

Consultando uma imagem

Clique em Consultar imagem, na parte superior da tela, para testar a pesquisa.

Selecione uma imagem de referência e execute a consulta.

O sistema pesquisará as imagens semelhantes no índice implantado e agrupará os resultados pelo código do produto.

Quando um mesmo produto possuir várias imagens entre os resultados, o sistema utilizará a imagem com maior relevância para posicionar o produto no ranking.

A consulta busca páginas adicionais de resultados quando necessário, até atingir a quantidade de produtos solicitada ou até não existirem mais resultados disponíveis.

Para que uma nova imagem possa aparecer na consulta, ela deve concluir todas as seguintes etapas:

1. envio ao Cloud Storage;

2. importação para o corpus;

3. análise do corpus;

4. atualização do índice.

Atualizando as informações da tela

O botão Atualizar grids recarrega:

• a fila local de imagens;

• a grade de operações gerais;

• o contexto do índice implantado.

Esse botão apenas atualiza as informações apresentadas na tela.

Ele não envia imagens e não inicia operações no Google.

Gerenciamento de imagens

A tela de gerenciamento permite localizar, excluir ou substituir imagens já registradas.

Para acessá-la, clique em:

Configurações → Gerenciar imagens

A tela apresenta todas as imagens ativas registradas na fila.

Localizando uma imagem

No campo Produto ou AssetId, informe:

• o código do produto;

• o código normalizado do produto; ou

• parte do AssetId da imagem.

A grade será filtrada automaticamente conforme o texto informado.

Clique em Atualizar lista para recarregar os dados do banco de dados.

A grade apresenta:

• ID do registro;

• código do produto;

• status;

• AssetId;

• endereço no Cloud Storage;

• operação vinculada;

• data de cadastro;

• data de conclusão;

• mensagem de erro.

Selecione uma linha para habilitar as operações disponíveis.

Excluindo uma imagem

1. Selecionar a imagem

Localize o produto ou AssetId e selecione a imagem desejada na grade.

2. Solicitar a exclusão

Clique em Excluir imagem.

O sistema apresentará uma confirmação contendo:

• código do produto;

• AssetId;

• status atual da imagem.

Depois da confirmação, o sistema solicitará a exclusão do asset no Google Vision.

Quando aplicável, a operação será executada de forma assíncrona e o registro passará para o status Excluindo.

A exclusão compreende:

• remoção do asset no Google Vision;

• remoção do arquivo no Cloud Storage;

• exclusão lógica do registro na fila local.

A remoção do registro local somente será finalizada depois que a exclusão no Google estiver concluída.

3. Consultar a exclusão

Clique em Consultar exclusões.

Repita a consulta até que a operação seja concluída.

Depois da conclusão, a imagem deixará de aparecer na lista de registros ativos.

4. Atualizar o corpus e o índice

Depois de excluir uma ou mais imagens, retorne à tela principal e execute:

1. Analisar corpus;

2. Consultar operações até a conclusão;

3. Atualizar índice;

4. Consultar operações até a conclusão.

Enquanto essas etapas não forem concluídas, o índice implantado poderá continuar refletindo a situação anterior do corpus.

Substituindo uma imagem

A substituição permite enviar uma nova imagem para o mesmo produto e solicitar a exclusão da imagem antiga.

1. Selecionar a imagem antiga

Localize e selecione a imagem que será substituída.

2. Selecionar a nova imagem

Clique em Substituir imagem.

Localize no computador o novo arquivo que será utilizado.

Os formatos aceitos são JPG, JPEG, PNG e WEBP.

3. Confirmar a substituição

O sistema enviará primeiro a nova imagem ao Cloud Storage e criará um novo registro com o status Pendente.

Somente depois desse envio a exclusão da imagem antiga será solicitada.

Essa sequência evita que a nova imagem seja perdida caso ocorra uma falha ao excluir a imagem anterior.

Se o envio da nova imagem for concluído, mas a exclusão da antiga não puder ser iniciada, a nova imagem permanecerá registrada como Pendente.

Nesse caso, corrija o problema e solicite novamente a exclusão da imagem antiga.

4. Concluir a exclusão da imagem antiga

Clique em Consultar exclusões até que a imagem antiga seja removida.

5. Importar a nova imagem

Retorne à tela principal e clique em Importar pendentes.

Depois, clique em Consultar importação até que a nova imagem esteja com o status Importado.

6. Atualizar a busca

Depois da importação, execute:

1. Analisar corpus;

2. Consultar operações até a conclusão;

3. Atualizar índice;

4. Consultar operações até a conclusão.

Após essas etapas, a imagem antiga será retirada do índice e a nova imagem passará a participar das consultas.

Reprocessando uma exclusão com erro

Quando uma exclusão terminar com erro, o registro receberá o status ErroExclusao.

Para tentar novamente:

1. acesse Configurações → Gerenciar imagens;

2. localize e selecione o registro;

3. clique em Reprocessar exclusão;

4. confirme a operação;

5. clique em Consultar exclusões caso a nova solicitação fique em processamento.

O botão Reprocessar exclusão somente fica disponível para registros com o status ErroExclusao.

Durante o reprocessamento, o sistema verifica novamente a situação do asset.

Se a exclusão anterior já tiver sido concluída pelo Google, o sistema finalizará apenas a limpeza do arquivo e do registro local.

Restrições durante uma exclusão

Enquanto existirem imagens com o status Excluindo, o sistema não permitirá:

• analisar o corpus;

• atualizar o índice;

• iniciar operações incompatíveis com a exclusão em andamento.

Enquanto existirem registros com o status ErroExclusao, o sistema também impedirá a análise e a atualização do índice.

Esses registros devem ser reprocessados antes da continuidade do fluxo.

Configurações do módulo

Clique em Configurações, na parte superior da tela, para acessar as opções administrativas.

Configurações gerais

Permite consultar e alterar os parâmetros utilizados pelo módulo.

Essas configurações devem ser alteradas somente por usuários responsáveis pela implantação ou manutenção do ambiente.

Gerenciar imagens

Permite:

• localizar imagens por produto ou AssetId;

• excluir imagens;

• substituir imagens;

• acompanhar exclusões;

• reprocessar exclusões com erro.

Administração Google Vision

Permite:

• consultar os assets existentes no corpus;

• verificar informações do ambiente;

• provisionar um novo corpus quando necessário.

A criação de um novo corpus não substitui automaticamente o corpus configurado na aplicação.

Administração do índice

Reúne as operações administrativas relacionadas à implantação inicial do índice:

• criar índice;

• criar endpoint;

• fazer deploy;

• desativar índice;

• consultar operações;

• atualizar o contexto do ambiente.

A tela também apresenta:

• número do projeto;

• região;

• corpus configurado;

• endpoint configurado;

• estado do endpoint;

• índice implantado;

• estado do índice;

• operações administrativas registradas.

Implantação inicial

As operações da tela Administração do índice são utilizadas principalmente durante a implantação inicial.

A sequência inicial é:

1. enviar as imagens;

2. importar as imagens pendentes;

3. consultar a importação até sua conclusão;

4. analisar o corpus;

5. consultar as operações até a conclusão da análise;

6. criar o índice;

7. consultar as operações até a conclusão da criação;

8. criar o endpoint;

9. consultar as operações até a conclusão da criação;

10. fazer o deploy do índice;

11. consultar as operações até a conclusão do deploy;

12. testar a consulta por imagem.

Depois que essa implantação estiver concluída, as opções Criar índice, Criar endpoint e Fazer deploy não fazem parte da inclusão normal de novas imagens.

Desativando o índice

A opção Desativar índice remove o índice atualmente implantado no endpoint.

Ela não exclui:

• o corpus;

• os assets;

• o índice;

• o endpoint.

Enquanto não houver um novo deploy, a consulta por imagem ficará indisponível.

Essa opção deve ser utilizada somente em situações administrativas ou de manutenção.

Sequência resumida para novas imagens

Após a implantação inicial, utilize esta sequência:

1. informar o código do produto;

2. selecionar as imagens;

3. clicar em Subir imagens;

4. clicar em Importar pendentes;

5. clicar em Consultar importação até que as imagens estejam importadas;

6. clicar em Analisar corpus;

7. clicar em Consultar operações até que a análise esteja concluída;

8. clicar em Atualizar índice;

9. clicar em Consultar operações até que a atualização esteja concluída;

10. testar a pesquisa em Consultar imagem.

Sequência resumida para exclusão

1. acessar Configurações → Gerenciar imagens;

2. localizar e selecionar a imagem;

3. clicar em Excluir imagem;

4. clicar em Consultar exclusões até a conclusão;

5. retornar à tela principal;

6. clicar em Analisar corpus;

7. consultar as operações até a conclusão;

8. clicar em Atualizar índice;

9. consultar as operações até a conclusão.

Sequência resumida para substituição

1. acessar Configurações → Gerenciar imagens;

2. localizar e selecionar a imagem antiga;

3. clicar em Substituir imagem;

4. selecionar a nova imagem;

5. consultar a exclusão da imagem antiga até a conclusão;

6. retornar à tela principal;

7. clicar em Importar pendentes;

8. consultar a importação até a conclusão;

9. clicar em Analisar corpus;

10. consultar as operações até a conclusão;

11. clicar em Atualizar índice;

12. consultar as operações até a conclusão.

Inclusão de imagens em lote

Quando houver imagens de vários produtos para incluir, é possível realizar todos os envios antes de iniciar o processamento.

Nesse caso:

1. informe o primeiro produto e envie suas imagens;

2. repita o procedimento para os demais produtos;

3. depois de concluir os envios, clique uma única vez em Importar pendentes;

4. aguarde a conclusão de todas as importações;

5. execute uma única análise do corpus;

6. aguarde a conclusão da análise;

7. execute uma única atualização do índice.

Esse procedimento evita análises e atualizações repetidas.

Observações importantes

Não execute Analisar corpus enquanto houver imagens pendentes, sendo importadas, sendo excluídas ou com erro de exclusão.

Não execute Atualizar índice antes que a análise mais recente do corpus esteja concluída.

Não utilize Criar índice para adicionar novas imagens a um índice já implantado.

Não realize um novo deploy depois de uma atualização normal do índice.

Aguarde sempre a conclusão de uma operação antes de iniciar a próxima etapa.

Depois de uma exclusão ou substituição, execute novamente a análise do corpus e a atualização do índice.

As operações são processadas pelo Google Cloud e podem levar algum tempo, dependendo da quantidade de imagens e da disponibilidade do serviço.

As telas, nomes das opções e procedimentos disponibilizados pelo Google Cloud podem ser alterados pelo fornecedor. As orientações deste manual têm como finalidade apresentar o processo utilizado pelo PlusCom e auxiliar o usuário na execução das operações necessárias.