🤖 IA Gemini: Classificação e Extração Inteligente de Documentos
O módulo IA Gemini está disponível a partir da versão 03.008.000 do Capture/HTF.
O módulo IA Gemini integra o modelo de linguagem Google Gemini ao pipeline do Capture/HTF, permitindo classificar, dividir e extrair dados de documentos automaticamente, sem regras manuais ou OCR tradicional.
Para que o Capture utilize essa inteligência, é necessário configurar um template de classificação IA na Análise Inteligente de Documento do ScanDesigner. Este guia explica como criar esse template e como o Capture o utiliza durante o processamento.
🧩 1. Conceitos Fundamentais
Antes de criar o template, entenda as três ações que o módulo pode executar sobre um documento PDF:
| Ação | O que faz |
|---|---|
| Classifier | Identifica o tipo do documento (ex: Nota Fiscal, Contrato, Boleto) |
| Splitter | Divide um PDF com múltiplos documentos em arquivos separados, identificando o tipo de cada um |
| Extractor | Extrai campos específicos do documento (ex: número, data, valor total) |
O template que você configura no ScanDesigner define quais tipos de documento o sistema reconhece e quais campos devem ser extraídos de cada um.
⚙️ 2. Acessando a Análise Inteligente de Documento
Os templates de IA são sempre criados e gerenciados dentro do contexto de um fluxo de captura aberto. Por isso, o acesso à Análise Inteligente de Documento é feito exclusivamente pelo ícone correspondente na toolbar do ScanDesigner, com um processo já aberto.
- Abra o ScanDesigner no Alfresco Share.
- Abra o fluxo de captura ao qual os templates serão associados.
- Clique no ícone de Análise Inteligente de Documento na toolbar do ScanDesigner.
A tela principal exibe a lista de templates cadastrados para aquele processo, com opções de abrir, renomear, duplicar e excluir.
A toolbar também possui um botão de Upload para enviar um PDF diretamente à página. Use-o para carregar um documento de teste antes de utilizar os botões de teste de classificação, extração ou splitter.
➕ 3. Criando um Novo Template
- Clique no botão "New" na barra de ferramentas.
- Na caixa de diálogo, digite um nome para o template.
O nome do template é vinculado ao processo (ex: meuprocesso/NotaFiscal). Caracteres especiais (^ ~ ? , @ # + ' " * . \\ / -) são removidos automaticamente.
- Clique em OK. O template criado aparecerá na lista e você poderá editá-lo.
✏️ 4. Configurando o Template
Clique no ícone de edição ao lado do template para abrir o formulário de configuração. O formulário é dividido em duas partes: o Prompt principal e os Campos de extração.
4.1 Perfil (Profile)
O campo Profile define a qual tipo de documento do processo esse template se aplica. Selecione na lista suspensa o documento IA correspondente ao processo de capture que utilizará este template.
4.2 Prompt Principal
O campo Prompt contém a instrução principal enviada ao Gemini para classificar o documento.
Escreva de forma clara e objetiva qual é o tipo de documento esperado. O valor aqui é utilizado nas ações de Classifier e Splitter.
Exemplos:
Nota Fiscal Eletrônica
Contrato de Prestação de Serviços
- Use o nome oficial do tipo de documento.
- Seja específico: prefira
"Nota Fiscal Eletrônica"a"NF". - Este valor é comparado com a resposta do modelo, então mantenha consistência entre os templates de um mesmo processo.
4.3 Campos de Extração (Fields)
Os campos definem quais informações o Gemini deve extrair do documento. Cada campo possui três propriedades:
| Propriedade | Descrição |
|---|---|
| Field ID | Identificador técnico do campo. Deve ser único no template. |
| Prompt | Instrução em linguagem natural para o Gemini extrair o dado. |
| Expression | Fórmula em Ruby para validar ou transformar o valor extraído. |
Adicionando um campo
- Clique em "Add field".
- Preencha as três propriedades conforme descrito abaixo.
- Repita para cada informação que deseja extrair.
Field ID
O identificador técnico do campo. É preenchido automaticamente com o prefixo field_.
- Utilize apenas letras minúsculas, números e underline.
- Exemplos:
field_numero_nota,field_data_emissao,field_valor_total
Dois campos não podem ter o mesmo Field ID dentro do mesmo template. O sistema bloqueará o salvamento caso haja duplicatas.
Prompt do Campo
A instrução que o Gemini receberá para extrair o dado específico. Seja direto e preciso.
Exemplos:
| Field ID | Prompt sugerido |
|---|---|
field_numero_nota | Número da Nota Fiscal |
field_data_emissao | Data de emissão no formato DD/MM/AAAA |
field_cnpj_emitente | CNPJ do emitente |
field_valor_total | Valor total da nota fiscal |
field_chave_acesso | Chave de acesso (44 dígitos) |
Incluir o formato esperado no Prompt melhora a consistência dos resultados. Ex: "Data de emissão no formato DD/MM/AAAA".
Expression
A Expression é um trecho de código Ruby executado após a extração. A regra é simples: retorne o valor esperado em caso de sucesso, ou false caso a validação falhe.
A variável value representa o valor extraído pelo modelo.
Exemplos comuns:
# Retorna o valor como está (sem validação)
value
# Retorna o valor como inteiro se for numérico, senão false
value.to_s =~ /\A\d+\z/ ? value.to_i : false
# Valida formato de data DD/MM/AAAA e retorna o próprio valor
value.to_s =~ /\A\d{2}\/\d{2}\/\d{4}\z/ ? value : false
# Valida CNPJ usando a função nativa
check_cnpj(value) ? value : false
# Retorna o valor em maiúsculas se não estiver vazio, senão false
value.to_s.strip.empty? ? false : value.to_s.upcase
Clique no ícone ao lado do campo para abrir o editor completo com realce de sintaxe Ruby e botão de formatação automática.
💾 5. Salvando o Template
Após preencher o Prompt principal e todos os campos, clique em "Save".
O sistema valida automaticamente:
- Todos os campos preenchidos (ID, Prompt e Expression não podem estar em branco).
- Ausência de Field IDs duplicados.
- Field ID não pode ser apenas
field_sem sufixo.
Campos com erro são destacados em vermelho. Corrija-os antes de salvar.
🧪 6. Testando o Template
Antes de ativar o template em produção, utilize os botões de teste na barra de ferramentas para validar o comportamento com um documento real.
6.1 Testar Classificação (Test Classification)
Faz o upload de um PDF e verifica se o documento é corretamente identificado pelo Prompt principal.
- Clique em "Test Classification".
- Arraste ou selecione o arquivo PDF.
- O resultado exibirá o tipo identificado, o tempo de processamento e o consumo de tokens.
6.2 Testar Extração (Test Extraction)
Valida se os campos configurados estão sendo extraídos corretamente.
- Clique em "Test Extraction" (com o template aberto).
- Faça o upload do PDF de teste.
- O resultado mostra uma tabela com: Field ID, Prompt, Valor Extraído e Resultado da Expression.
Execute o teste com documentos variados (boa qualidade, baixa qualidade, formatos diferentes) para garantir robustez antes de ativar em produção.
6.3 Testar Splitter (Test Splitter)
Testa a divisão de um PDF com múltiplos documentos.
- Clique em "Test Splitter".
- Faça o upload de um PDF com mais de um documento.
- O resultado indica a página inicial, página final e tipo identificado para cada subdocumento.
Quando o Splitter é executado no pipeline real, o captureprocessor fatia automaticamente o PDF nos intervalos identificados e cada subdocumento gerado é re-enfileirado como um novo documento independente, passando pelo pipeline completo desde o início — incluindo extração de campos e, se necessário, conferência individuais. O documento original é descartado após o fatiamento.
🔄 7. Usando os Campos no Node App.ClassificableFile
Após configurar os campos no template de Análise Inteligente de Documento, o próximo passo é configurar o node App.ClassificableFile no ScanDesigner. É nele que os tipos de documento reconhecidos pelo Gemini ganham suas regras de tratamento e metadados.
7.1 Grupos de Propriedades por Tipo de Documento
O App.ClassificableFile carrega automaticamente os templates de IA cadastrados para o processo e cria um grupo de propriedades separado para cada tipo de documento. Cada grupo recebe o nome do template correspondente e fica recolhido por padrão no painel de propriedades do ScanDesigner.
Isso significa que, se o processo tiver os templates NotaFiscal, Contrato e Boleto, o node exibirá três grupos independentes — um para cada tipo — cada um com seu próprio conjunto de configurações de tratamento e metadados.
Documentos recusados (não classificados pelo Gemini, com conferência desativada) seguem as definições configuradas no node fora dos grupos, que funcionam como o comportamento padrão do node para esse cenário.
As principais propriedades disponíveis em cada grupo são:
| Propriedade | Descrição |
|---|---|
| Destino | Caminho no Alfresco onde o documento será arquivado |
| Nome do arquivo | Nome gerado para o documento |
| Tags | Tags aplicadas ao documento |
| Tipo de conteúdo | Content type do Alfresco |
| Metadados | Lista de pares nome / valor com expressões Ruby |
| Workflow | Fluxo de trabalho a iniciar após o arquivamento |
| OCR, corte, compressão | Opções de processamento de imagem |
| Extração de campos IA | Toggle que habilita ou desabilita a extração de campos para este tipo de documento |
Cada grupo possui um toggle independente para habilitar a extração de campos. Quando desativado, o processamento realiza apenas a classificação do documento (Classifier/Splitter), sem executar o Extractor nem acionar a conferência por campo. Use essa opção quando o tipo de documento precisa ser identificado mas não requer extração de metadados via IA.
7.2 Usando Campos Extraídos como Variáveis
Qualquer propriedade do grupo (destino, nome do arquivo, metadados etc.) aceita variáveis que são substituídas em tempo de execução pelos valores extraídos pelo Gemini. O padrão é:
#field_nomedofield#
Onde nomedofield corresponde ao Field ID configurado no template, incluindo o prefixo field_.
Exemplos:
| Field ID no template | Variável no ScanDesigner |
|---|---|
field_numero_nota | #field_numero_nota# |
field_data_emissao | #field_data_emissao# |
field_cnpj_emitente | #field_cnpj_emitente# |
field_valor_total | #field_valor_total# |
Exemplo de configuração do nome do arquivo:
NF_#field_numero_nota#_#field_data_emissao#.pdf
Exemplo de metadado com expressão Ruby:
# campo "valor" de um metadado de nota fiscal
"R$ " + "#field_valor_total#"
7.3 Conferência se Recusado
Cada grupo de tipo de documento possui a opção "Conferência se recusado". Quando ativada, documentos que o Gemini não conseguiu classificar (tipo retornado como desconhecido ou sem template correspondente) não são descartados — eles são pausados e encaminhados para a fila de conferência.
Como funciona:
- O captureprocessor tenta classificar o documento. Se o tipo não for reconhecido:
- Com a opção ativada: o documento é marcado como pausado e disponibilizado na página Capture Conference no Alfresco Share.
- Com a opção desativada: o documento é marcado como recusado e segue as definições do node fora dos grupos.
- Um operador acessa a fila de conferência, visualiza o documento e pode:
- Preencher manualmente os campos de extração que não foram obtidos corretamente.
- Recusar o documento, cancelando o processamento.
- Após o preenchimento manual, cada valor é validado pela Expression configurada no campo. Se válido, o processamento é retomado do ponto onde parou.
Ative "Conferência se recusado" em ambientes onde a qualidade dos documentos é variável (digitalizações, PDFs de câmera) para garantir que nenhum documento seja perdido por falha na classificação.
🔑 8. Configuração do Serviço (Administrador)
8.1 Chaves de API
A integração com o Google Gemini é configurada em alfresco-global.properties. A propriedade iageminikeys aceita múltiplas chaves de API separadas por vírgula.
# Formato de cada chave: API_KEY:MODELO:RPM:TPM:RPD
# RPM = requisições por minuto | TPM = tokens por minuto | RPD = requisições por dia (-1 = ilimitado)
iageminikeys=CHAVE_1:gemini-2.5-flash-lite:4000:4000000:-1,CHAVE_2:gemini-2.5-flash-lite:4000:4000000:-1
# Máximo de tarefas simultâneas (por instância do serviço)
iagemini_max_concurrent_tasks=3
Seleção da chave por capacidade disponível
A cada requisição, o serviço seleciona a chave com maior capacidade de RPM disponível no momento — não há rodízio fixo. Os três limites (RPM, TPM e RPD) são verificados simultaneamente: uma chave só é elegível se tiver capacidade em todos os três ao mesmo tempo. Se todas as chaves estiverem com algum limite esgotado, a requisição aguarda em fila até que uma chave fique disponível.
As chaves de API são obtidas no Google AI Studio ou no Google Cloud Console. Guarde-as com segurança e não as compartilhe.
8.2 Monitorando as Chamadas ao Gemini
O Alfresco Share disponibiliza a página 3rd Integrations - Gemini, acessível pelo menu de administração, que lista o histórico de todas as chamadas realizadas ao serviço ia_gemini. Para cada chamada são exibidos: usuário, modelo utilizado, ação executada (classifier/extractor/splitter), status, tempo de fila, tempo total e consumo de tokens (prompt e resposta).
Utilize essa página para acompanhar o volume de uso, identificar chamadas com erro e monitorar o consumo de tokens por processo.
❓ Dúvidas Frequentes
Posso ter múltiplos templates para o mesmo processo? Sim. Cada template representa um tipo de documento diferente dentro do mesmo processo. O Classifier identifica qual template usar para cada documento.
O que acontece se o Gemini não conseguir extrair um campo?
O campo retorna vazio e a Expression retorna false. Se "Conferência se recusado" estiver ativada no grupo, o documento é pausado e vai para a fila do Capture Conference, onde um operador pode preencher o valor manualmente. Com a opção desativada, o documento é marcado como recusado e segue as definições do node fora dos grupos.
O Prompt deve estar em português? Sim, para documentos em português. O Gemini é multilíngue, mas Prompts no idioma do documento melhoram a precisão da extração.
Posso reutilizar um template em outro processo? Use o botão "Duplicate" na lista de templates para criar uma cópia e adaptá-la ao novo processo.