Leitor e extrator de NF(Nota Fiscal)

Propósito

Este projeto consiste em realizar a leitura de uma nota fiscal, e retornar ao usuário as informações existentes na nota fiscal, como Nomes, valores, data, entre outras informações.

Funcionamento

A aplicação permite a realização de upload de imagens de notas fiscais, que são convertidas automaticamente em dados estruturados utilizando OCR (Reconhecimento Óptico de Caracteres) via AWS Textract. Após a extração inicial, a aplicação realiza uma análise semântica dos dados utilizando LLM para identificar informações como o nome do emissor, CNPJ, valores, formas de pagamento, e outros dados relevantes. Estes dados são refinados e organizados para garantir precisão e consistência.

Descrição

Este projeto foi criado no intuito de desenvolver uma aplicação para o processamento automatizado de imagens de recibos e notas fiscais eletrônicas, transformando-os em objetos JSON estruturados. A aplicação foi construída utilizando FastAPI e é projetada para operar 100% na AWS Cloud, aproveitando uma arquitetura serverless com AWS Lambda, API Gateway, e AWS Step Functions para orquestrar o fluxo de processamento, com isso, a idéia é fornecer uma solução escalável, automatizada e segura para a extração de dados de documentos fiscais, eliminando a necessidade de intervenção manual, aumentando a eficiência no tratamento e armazenamento de informações fiscais, e garantindo conformidade e precisão.

Ferramentas Utilizadas

• Python - Linguagem de programação principal.
• FastAPI - Framework web para construção de APIs RESTful.
• VSCode - Editor de código.
• Postman - Ferramenta para testes de APIs.
• AWS CDK - Framework para desenvolvimento de infraestrutura como código.
• AWS Lambda - Serviço de computação serverless.
• AWS Step Functions - Orquestração de fluxos de trabalho serverless.
• AWS S3 - Serviço de armazenamento de objetos.
• AWS Textract - Serviço de extração de dados de documentos.
• AWS API Gateway - Serviço de gerenciamento de APIs.
• AWS IAM - Serviço de gerenciamento de identidade e acesso.
• AWS Layer - Camadas de execução para funções Lambda.
• AWS Secrets Manager - Serviço de gerenciamento de segredos.
• AWS CloudWatch - Serviço de monitoramento e logs.
• AWS SSO - Serviço de autenticação única.
• AWS CDK - Framework para desenvolvimento de infraestrutura como código.
• AWS CloudFormation - Serviço de provisionamento de recursos AWS.
• OpenCV - Biblioteca de visão computacional para pré-processamento de imagens.
• HTML - Linguagem de marcação para construção de páginas web.
• CSS - Linguagem de estilização para páginas web.
• JavaScript - Linguagem de programação para páginas web.
• Hugging Face - Plataforma de modelos de LLL(Large Language Model).
• LLM (Mistral 7B) - Modelo de linguagem para análise e organização de dados.
• Git - Sistema de controle de versões.
• GitHub - Plataforma de hospedagem de código.

Interface do projeto

Estrutura json de uma nota fiscal

A aplicação irá gerar e processar notas fiscais com a seguinte estrutura JSON:

{
    "nome_emissor": "<nome-fornecedor>",
    "CNPJ_emissor": "00.000.000/0000-00",
    "endereco_emissor": "<endereco-fornecedor>",
    "CNPJ_CPF_consumidor": "000.000.000-00",
    "data_emissao": "00/00/0000",
    "numero_nota_fiscal": "123456",
    "serie_nota_fiscal": "123",
    "valor_total": "0000.00",
    "forma_pgto": "<dinheiropix/outros>"
}

Exemplo de dados extraídos de uma nota fiscal

Desenvolvimento do projeto

Como dito o objetivo do projeto é provisionar uma aplicação para processamento de notas fiscais 100% em cloud na AWS, com isso, o projeto foi dividido em duas partes, sendo a primeira parte o desenvolvimento local da aplicação servido como ponto de partida do desenvolvimento e a segunda parte a implementação da aplicação na AWS.

• NF_PROJECT: API FastAPI contém um processamento básico de notas fiscais e serviu como ponto inicial para todo o desenvolvimento. Ele contém rotas para upload de imagens, extração de dados, processamento de imagens, e extração de texto. Além disso, possui uma interface web simples para interação com o usuário. Fluxo do Projeto Local
  • O usuário acessa a interface web através do index.html, que permite carregar uma imagem de nota fiscal.
  • A imagem é enviada para o endpoint da FastAPI que realiza o pré-processamento utilizando o pre_processor.py.
  • O processamento de OCR é realizado pelo textract_processor.py para extrair o texto e dados da nota fiscal.
  • Os dados extraídos são exibidos na interface web, permitindo que o usuário visualize as informações diretamente.
• NF_PROJECT_AWS: API RESTful implementa a infraestrutura e os serviços necessários para realizar o processamento completo de notas fiscais na AWS. Utiliza vários recursos como: Lambda, Step Functions, S3, IAM Roles, API Gateway, além de camadas de processamento adicionais.
  • O usuário acessa a interface web hospedada no S3, configurada para interagir com a API na nuvem.
  • API Gateway lida com requisições do usuário e invoca a Lambda endpoint que faz o upload da imagem para o S3.
  • Após o upload, a Lambda endpoint inicia a Step Function, que executa a sequência de processamento:
  • Pre-processamento: A imagem é tratada para facilitar o reconhecimento de caracteres.
  • Processamento de OCR: A imagem é enviada para o Textract através da função textract_dados_lambda.py para extração do texto.
  • Extração de Dados: Os dados são estruturados e salvos no S3 para posterior análise e visualização.
  • O usuário faz requisições para visualizar dados processados. A Lambda endpoint_dados_lambda.py recupera o arquivo processado do S3 e retorna os dados para exibição.

Ambos os projetos possuem uma estrutura semelhante, com pastas e arquivos organizados e modularizados de forma a facilitar o desenvolvimento e manutenção do código. O projeto NF_PROJECT_AWS foi desenvolvido para ser executado na AWS, enquanto o NF_PROJECT é executado localmente.

Estrutura do Projeto

A organização dos diretórios e arquivos do projeto segue a seguinte estrutura:

     /NF_PROJECT/                       # Projeto NF_PROJECT
    ├── /api/                           # Subdiretório a API FastAPI
    │   ├── api.py                      # Definição de rotas 
    │   └── /endpoints/                 # Subdiretório endpoints da API
    │       └── nota_fiscal.py          # Endpoint processamento  
    │
    ├── /extractors/                    # Subdiretório extração de dados
    │   └── nota_fiscal_extractor.py    # Extração de dados
    │
    ├── /local_storage/                 # Subdiretório armazenamento local de imagens processadas
    │   └── img.jpg                     # Imagem de exemplo teste da aplicação 
    │
    ├── /processing/                    # Subdiretório processamento de imagens   
    │   ├── pre_processor.py            # Pré-processamento de imagens
    │   └── textract_processor.py       # Processamento de imagens
    │   
    ├── /public/                        # Subdiretório interface web
    │   ├── index.html                  # Página inicial 
    │   ├── /img/                       # Subdiretório imagens 
    │   │   └── logo.png                # Imagem da interface web
    │   ├── /css/                       # Subdiretório estilos CSS 
    │   │   └── style.css               # Estilos CSS 
    │   └── /js/                        # Subdiretório scripts JavaScript 
    │       └── script.js               # Scripts JavaScript
    │  
    ├── /models/                        # Subdiretório modelos de dados
    │   └── nota_fiscal_model.py        # Modelo de dados da nota fiscal 
    │  
    ├── .gitignore                      # Ignorar diretórios desnecessários
    ├── main.py                         # Ponto de entrada FastAPI
    └── requirements.txt                # Dependências do projeto
    
    /NF_PROJECT_AWS/                                # Projeto NF_PROJECT AWS
    ├── /aws/                                       # Subdiretório para infraestrutura AWS 
    │   ├── /lambda/                                # Subdiretório para as funções Lambda
    │   │   ├── endpoint_lambda.py                  # Função Lambda endpoint da API Gateway
    │   │   |── endpoint_dados_lambda.py            # Função Lambda endpoint da API Gateway extração de dados
    │   │   |── nota_fiscal_extractor_lambda.py     # Função Lambda extração dados LLM
    │   │   |── pre_processor_lambda                # Função Lambda pré-processamento de imagens
    │   │   └── textract_dados_lambda               # Função Lambda processamento de imagens com AWS Textract
    │   │ 
    │   ├── /layers/                                # Subdiretório para camadas Lambda
    │   │   ├── pre_processor_layer.zip             # Layer Lambda pré-processamento de imagens
    │   │   └── transformer_layer.zip               # Layer Lambda LLM
    │   │
    │   ├── /modules/                               # Subdiretório para stacks de infraestrutura
    |   |   ├── /secrets/                           # Subdiretório secretmanager
    |   |   |   └── hugging_face_secret_module.py   # Stack secretmanager
    |   |   ├── api_gateway_module.py               # Stack API Gateway RestApi
    |   |   ├── lambda_endpoint_module.py           # Stack Lambda para endpoints
    |   |   ├── lambda_processing_module.py         # Stack Lambda para processamento
    |   |   ├── role_module.py                      # Stack IAM Roles
    |   |   ├── s3_module.py                        # Stack buckets S3
    |   |   ├── statics_module.py                   # Stack recursos estáticos
    |   |   └── step_function_module.py             # Stack stepfunction
    |   |   
    │   └── py_starter_stack.py                     # Stack principal para criação de recursos AWS   
    │          
    ├── /public/                                    # Subdiretório interface web
    │   ├── index.html                              # Página inicial
    │   ├── /img/                                   # Subdiretório imagens
    │   │   └── logo.png                            # Logo da aplicação
    │   ├── /css/                                   # Subdiretório estilos CSS 
    │   │   └── style.css                           # Estilos CSS 
    │   └── /js/                                    # Subdiretório scripts JavaScript 
    │       └── script.js                           # Scripts JavaScript 
    │ 
    ├── .gitignore                                  # Ignorar arquivos desnecessários  
    ├── app.py                                      # Ponto de entrada do CDK
    |── requirements.txt                            # Dependências do projeto
    |── requirements-dev.txt                        # Dependências de desenvolvimento do projeto
    |── source.bat                                  # Script de ativação ambiente virtual
    └── cdk.json                                    # Configuração do CDK

Resumo do fluxo de processamento

• O usuário faz o upload da imagem da nota fiscal na interface web.
• A imagem é enviada para o S3 e um evento é acionado para a função Lambda principal (endpoint_lambda.py).
• Essa função invoca a Step Function, que orquestra o processamento da imagem através das funções de pré-processamento, extração de texto (Textract) e análise dos dados (LLM).
• Após o processamento, as imagens são redirecionadas para os respectivos diretórios: notas_dinheiro ou notas_outros no S3, de acordo com a forma de pagamento descrita na nota.
• Os dados extraídos são armazenados em JSON em um outro diretório resultados também no S3 e por fim são servidos pelo front-end(endpoint_dados_lambda.py).
• Durante o fluxo, o CloudWatch Logs personalizados, monitoram todo o processamento.

Fluxo de Processamento Step Functions:

Estrturura de pastas do projeto na AWS:

Região AWS: Toda a infraestrutura é provisionada na região us-east-1 (Norte da Virgínia).

Endpoints da API:

A rota principal da API configurada no endpoint para receber requisições das imagens é: /api/v1/invoice.

Desafios Enfrentados

No decorrer do desenvolvimento do projeto, enfrentamos diversos desafios técnicos e operacionais, que exigiram soluções criativas e trabalho em equipe para superar. Alguns dos desafios mais significativos incluíram:

1. Configuração de Infraestrutura e Permissões na AWS

   • Configuração de permissões: Integrar AWS Lambda, API Gateway, S3 e Step Functions com o CDK exigiu ajustes de IAM Roles e dependências entre stacks.
   • Passagem de variáveis de ambiente: Foi complexo sincronizar o ID do API Gateway (apiId) e outras variáveis com o front-end hospedado no S3 devido a tokens gerados automaticamente pelo CDK, levando à necessidade de ajustes manuais.

2. Timeout e Logs no Step Functions

   • Configuração de timeouts: Ajustar os parâmetros TimeoutSeconds e task_timeout para Step Functions para evitar que o fluxo expire prematuramente.
   • Gerenciamento de logs: Interpretar mensagens de erro de timeout e configurar logs adequados para diagnóstico.

3. Ambiente Local e Sincronização de Arquivos

   • Configuração do ambiente virtual: Dificuldades na instalação de pacotes como textract, pytesseract e Pillow no Windows, incluindo erros com permissões do pip e ao rodar o uvicorn.
   • Problemas com OneDrive: A execução do projeto dentro de uma pasta sincronizada com o OneDrive causou falhas de permissões, levando à necessidade de mover o projeto para uma pasta fora do OneDrive.

4. Integração de Lambda com Hugging Face

   • Armazenamento seguro da chave API: Configurar o Secrets Manager para gerenciar a chave da API Hugging Face e garantir que a Lambda pudesse acessá-lo de forma segura.
   • Estrutura de prompt para o modelo: O modelo Hugging Face necessitava de um input organizado para retornar dados precisos, o que exigiu estruturação dos dados extraídos.
   • Integração com camadas Lambda: Configurar camadas Lambda para reutilizar pacotes e bibliotecas, garantindo que a Lambda pudesse acessar o modelo Hugging Face e outras dependências.
   • LLL(Large Language Model): O modelo de linguagem LLM (Mistral 7B) exigiu ajustes para processar os dados extraídos e retornar informações precisas. Tivemos dificuldades relacionadas com a execução do LLM, onde ficamos um tempo travados neste passo, e depois na formatação do prompt onde o LLM não executava a função como o esperado.

5. Pré-processamento e Extração de Dados

   • Regex e Normalização de Dados OCR: Uso de expressões regulares para limpar e estruturar dados extraídos do OCR e preenchimento de campos ausentes para garantir a consistência dos dados.
   • Filtragem de informações irrelevantes: Foi importante remover textos promocionais e formatações inconsistentes, como máscaras de CNPJ e CPF, para preparar os dados de forma clara.

6. Otimização de Deploy e CORS

   • Otimização do processo de deploy: Simplificar o deploy de funções Lambda sem precisar realizar um deploy completo foi desafiador.
   • Configuração de CORS: Habilitar CORS no API Gateway corretamente para evitar erros de permissão foi recorrente, ajustando cabeçalhos e métodos permitidos.

Lições Aprendidas

Aprendemos sobre a utilização de vários recursos da Amazon Web Service(AWS), esses desafios forneceram experiência prática em configuração de infraestrutura, gerenciamento de permissões e integração de APIs, especialmente quando se trabalha com ferramentas como o CDK e serviços de inteligência artificial. A resolução desses problemas ajudou a aprimorar o fluxo de trabalho, a eficiência do deploy e a qualidade dos dados extraídos utilizando LLM, além de integra-lo ao projeto.

Links do Projeto

• NF_PROJECT_AWS-ANDRE | https://nota-fiscal-bucket-nfproject-andre.s3.us-east-1.amazonaws.com/public/index.html
• NF_PROJECT_AWS-BRUNO | https://nota-fiscal-bucket-nfproject-bruno.s3.us-east-1.amazonaws.com/public/index.html
• NF_PROJECT_AWS-IGOR | https://nota-fiscal-bucket-nfproject-igor.s3.us-east-1.amazonaws.com/public/index.html
• NF_PROJECT_AWS-MARCOS | https://nota-fiscal-bucket-nfproject-marcos.s3.us-east-1.amazonaws.com/public/index.html

INTEGRANTES

• Andre Guilherme Correa | andre.correa.pb@compasso.com.br
• Bruno Henrique Aureliano | bruno.aureliano.pb@compasso.com.br
• Igor Albiero | igor.albiero.pb@compasso.com.br
• Marcos Vinicius Francisco | marcos.francisco.pb@compasso.com.br