Em Desenvolvimento
Esta documentação ainda está em desenvolvimento. Agradecemos sua paciência!
Pular para o conteúdo principal
Versão: 03.008.000 🚧 (em desenvolvimento)

🤖 IA Gemini: Classificação e Extração Inteligente de Documentos

Versão mínima requerida

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çãoO que faz
ClassifierIdentifica o tipo do documento (ex: Nota Fiscal, Contrato, Boleto)
SplitterDivide um PDF com múltiplos documentos em arquivos separados, identificando o tipo de cada um
ExtractorExtrai 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.

  1. Abra o ScanDesigner no Alfresco Share.
  2. Abra o fluxo de captura ao qual os templates serão associados.
  3. 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​

  1. Clique no botão "New" na barra de ferramentas.
  2. Na caixa de diálogo, digite um nome para o template.
Nomenclatura

O nome do template é vinculado ao processo (ex: meuprocesso/NotaFiscal). Caracteres especiais (^ ~ ? , @ # + ' " * . \\ / -) são removidos automaticamente.

  1. 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
Boas práticas para o Prompt
  • 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:

PropriedadeDescrição
Field IDIdentificador técnico do campo. Deve ser único no template.
PromptInstrução em linguagem natural para o Gemini extrair o dado.
ExpressionFórmula em Ruby para validar ou transformar o valor extraído.

Adicionando um campo​

  1. Clique em "Add field".
  2. Preencha as três propriedades conforme descrito abaixo.
  3. Repita para cada informação que deseja extrair.

Field ID​

O identificador técnico do campo. É preenchido automaticamente com o prefixo fixo Field_ (com F maiúsculo), que não pode ser removido; o restante do identificador é sempre em minúsculas.

  • Utilize apenas letras minúsculas, números e underline.
  • Exemplos: Field_numero_nota, Field_data_emissao, Field_valor_total
aviso

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 IDPrompt sugerido
Field_numero_notaNúmero da Nota Fiscal
Field_data_emissaoData de emissão no formato DD/MM/AAAA
Field_cnpj_emitenteCNPJ do emitente
Field_valor_totalValor total da nota fiscal
Field_chave_acessoChave de acesso (44 dígitos)
dica

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
Editor de Expression

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.

  1. Clique em "Test Classification".
  2. Arraste ou selecione o arquivo PDF.
  3. 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.

  1. Clique em "Test Extraction" (com o template aberto).
  2. Faça o upload do PDF de teste.
  3. O resultado mostra uma tabela com: Field ID, Prompt, Valor Extraído e Resultado da Expression.
dica

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.

  1. Clique em "Test Splitter".
  2. Faça o upload de um PDF com mais de um documento.
  3. O resultado indica a página inicial, página final e tipo identificado para cada subdocumento.
Comportamento do Splitter em produção

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:

PropriedadeDescrição
DestinoCaminho no Alfresco onde o documento será arquivado
Nome do arquivoNome gerado para o documento
TagsTags aplicadas ao documento
Tipo de conteúdoContent type do Alfresco
MetadadosLista de pares nome / valor com expressões Ruby
WorkflowFluxo de trabalho a iniciar após o arquivamento
OCR, corte, compressãoOpções de processamento de imagem
Extração de campos IAToggle que habilita ou desabilita a extração de campos para este tipo de documento
Toggle "Extração de campos IA"

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_. A variável diferencia maiúsculas de minúsculas: use sempre #Field_ com F maiúsculo.

Exemplos:

Field ID no templateVariá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:

  1. 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.
  2. 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.
  3. Após o preenchimento manual, cada valor é validado pela Expression configurada no campo. Se válido, o processamento é retomado do ponto onde parou.
dica

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 pelo arquivo .env (ver Configuração via arquivo .env), na variável HTF_GEMINI_KEYS (equivalente à propriedade htf.gemini.keys). Ela aceita múltiplas chaves de API, separadas por ponto e vírgula (;).

Cada chave segue o formato API_KEY:MODELO:RPM:TPM:RPD:

CampoDescrição
API_KEYA chave obtida no Google (ver abaixo)
MODELOO modelo Gemini (ex.: gemini-3.5-flash-lite, econômico e rápido para captura em volume, ou gemini-3.5-flash, mais capaz)
RPMRequisições por minuto
TPMTokens por minuto
RPDRequisições por dia

Os limites (RPM/TPM/RPD) aceitam os sufixos k e M (ex.: 4M = 4.000.000) e os valores unlimited ou -1 para sem limite.

# Duas chaves, separadas por ; — cada uma no formato API_KEY:MODELO:RPM:TPM:RPD
HTF_GEMINI_KEYS=CHAVE_1:gemini-3.5-flash-lite:4000:4M:-1;CHAVE_2:gemini-3.5-flash-lite:4000:4M:-1

# Máximo de tarefas simultâneas (por instância do serviço)
HTF_GEMINI_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.

Limites

Os três limites servem para o serviço se auto-limitar (pacear as chamadas e evitar recusas do Google por excesso de cota). Informe valores iguais aos limites reais da sua conta. Usar -1 (sem limite) em uma chave de camada gratuita faz o serviço ultrapassar o teto diário e receber recusas (HTTP 429).

Após alterar a variável, aplique com ./run.sh sync e reinicie o serviço de IA (iagemini), que lê a configuração ao subir.

Como criar a chave da API Gemini​

O módulo usa a Gemini Developer API do Google, que autentica por chave de API (não por conta de serviço nem OAuth).

Opção A — Google AI Studio (mais simples, recomendada)

  1. Acesse https://aistudio.google.com/apikey com a conta que será a titular (e responsável pelo faturamento).
  2. Clique em Create API key e escolha (ou crie) o projeto do Google Cloud.
  3. Copie a chave — ela é exibida uma única vez. Chaves do AI Studio começam com AIza.

Opção B — Google Cloud Console

  1. Em https://console.cloud.google.com, crie ou selecione um projeto.
  2. Em APIs e serviços > Biblioteca, ative a Generative Language API.
  3. Em APIs e serviços > Credenciais, clique em Criar credenciais > Chave de API e copie a chave.
  4. Edite a chave e, em Restrições de API, marque somente a Generative Language API. Se o IP do servidor for fixo, restrinja também por endereço IP (não use "Referenciadores HTTP", pois o uso é do lado do servidor).
observação

O Console pode gerar chaves vinculadas a conta de serviço (prefixo AQ.), dependendo de uma política da organização. Essas chaves também funcionam. Se a política bloquear a criação, use a Opção A.

Escolhendo o modelo e conferindo os limites

  • Modelos antigos deixam de ser oferecidos a novas contas; confira a lista vigente em https://ai.google.dev/gemini-api/docs/models antes de configurar.
  • Os limites variam por conta e por camada de faturamento. Veja os valores efetivos em https://aistudio.google.com/rate-limit ou, no Cloud Console, em IAM e Admin > Cotas (filtrando por "Generative Language API"). Sem faturamento a conta fica na camada gratuita, de cota baixa; para volume de captura, ative o faturamento.

Testando a chave antes de configurar

KEY=SUACHAVE; MODEL=gemini-3.5-flash-lite
curl -s -o /dev/null -w '%{http_code}\n' \
-X POST "https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent?key=${KEY}" \
-H 'Content-Type: application/json' \
-d '{"contents":[{"parts":[{"text":"responda so: ok"}]}]}'
  • 200: chave e modelo corretos.
  • 404 com "no longer available": troque o modelo.
  • 400/403 (API_KEY_INVALID ou PERMISSION_DENIED): chave incorreta ou Generative Language API não ativada.
aviso

A chave é um segredo: mantenha-a somente no .env da instalação, fora de repositórios de código. Se vazar, revogue-a no AI Studio/Console e crie outra. Restrinja-a à Generative Language API e, quando possível, ao IP do servidor.

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.