Skip to content

RamonCintas/Find_Pets

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
assets
assets
 
 
src
src
 
 
CODE_OF_CONDUCT.md
CODE_OF_CONDUCT.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
SECURITY.md
SECURITY.md
 
 

Repository files navigation

Idiomas

Ícone da bandeira do Brasil. Clique para acessar o conteúdo em Português.

Logo do projeto find-pets Logo da empresa fênix

🏆 Projeto Find Pets (esquerda) e Logo da empresa FÊnix (direita)

📑 índice

🔹 🚀 Apresentação (PDF)

🔹 📈 Status do Projeto

🔹 📐 Desenho do Sistema

🔹 🗂️ Estrutura de Arquivos e Pastas

🔹 ☁️ Deploy na CloudRender

🔹 🤖 Chappie Chatbot

🔹 🏗️ Arquitetura e Fluxo de Interação

🔹 🖨️ Integração com Impressora Térmica POS-58

🔹 📚 Glossário

🔹 📋 Referências

🔹 📝 Autores

🔹 ⚖️ Licença

🚀 Apresentação Find Pets

🌐 Marketing Digital do Find Pets

marketing marketing

📱 exposição-frente-camiseta e exposição-verso-camiseta

exposicao-frente-camiseta exposicao-verso-camiseta

🖨️ Impressora POS-58 X Feira e 🧾 Impressão X Feira

Impressora POS-58 X Feira Impressão X Feira

📈 Status do projeto

Note

☁️ Hospedado na Cloud Render, Clever Cloud e Expo

Tip

🔎 Qualquer feedback entrar em contato com os desenvolvedores

Resultado

Important

🛰️ Projeto concluído

Caution

⛔ Após a apresentação o projeto será excluído das plataformas de hospedagem

Logotipo do YouTube
Descrição da Imagem Esta imagem contém o logotipo do YouTube em movimento, sugerindo que o usuário pode clicar para assistir ao vídeo do projeto. O logotipo está centralizado, e o GIF cria uma sensação de interatividade. Ao clicar na imagem, o usuário será redirecionado para o vídeo do projeto no YouTube.

Vídeo hospedado no github

PROJETO.FIND.PETS.mp4

Logotipo do gif da x feira no youtube
Descrição da Imagem Esta imagem contém o gif do video da x feira no YouTube, sugerindo que o usuário pode clicar para assistir ao vídeo do projeto apresentado na feira. O GIF cria uma sensação de interatividade. Ao clicar na imagem, o usuário será redirecionado para o vídeo do projeto na feira no YouTube.

Vídeo hospedado no github

X.FEIRA.DE.TECNOLOGIA._.FIND.PETS.mp4

📐 Desenho do sistema

mermaid

graph TD subgraph Find-Pets

    U[Usuario-no-app-Expo-Go] --> IniciaCadastro[Inicia-cadastro-de-animal-encontrado]

    IniciaCadastro --> EnviaImagem[Imagem-enviada-para-API-Cloud-Render]

    EnviaImagem --> Roboflow[Roboflow-identifica-tipo-e-raca]:::external
    EnviaImagem --> HuggingFace[HuggingFace-identifica-apenas-raca]:::external

    Roboflow --> ResultadoTipoRaca[Resultado-com-tipo-e-raca]
    HuggingFace --> ResultadoRacaExtra[Validacao-extra-da-raca]

    ResultadoTipoRaca --> AguardaAcao[Espera-usuario-prosseguir-para-cadastro]
    ResultadoRacaExtra --> AguardaAcao

    AguardaAcao --> Prossegue[Usuario-prossegue-para-cadastrar]

    Prossegue --> CloudRenderBusca[Cloud-Render-envia-tipo-e-raca-para-Clever-Cloud]:::external

    CloudRenderBusca --> CleverBusca[Clever-Cloud-retorna-coordenadas-de-pets-perdidos]:::external

    CleverBusca --> VerificaDistancia[Cloud-Render-calcula-distancia-geografica]

    VerificaDistancia --> VerificaMatch{Existe-pet-perdido-do-mesmo-tipo-e-raca-a-menos-de-10km?}

    VerificaMatch -- Sim --> EnviaEmail[Envia-email-ao-dono-do-pet-perdido]
    VerificaMatch -- Nao --> CadastroFinalizado[Cadastra-pet-encontrado-no-banco-Clever-Cloud]

end

%% Estilos
classDef user fill:#000000,color:#ffffff,stroke:#333,stroke-width:2px;
classDef external fill:#FFD700,color:#000000,stroke:#999,stroke-width:2px;

class U,IniciaCadastro,Prossegue user;
class Roboflow,HuggingFace,CloudRenderBusca,CleverBusca external;

`

Warning

🚧 GitHub mobile não tem suporte para Mermaid, segue abaixo o diagrama ilustrado do sistema Find Pets

Fluxograma do sistema Find Pets, representando a interação entre o usuário no app mobile, o backend Cloud Render, os serviços de reconhecimento Roboflow e HuggingFace, e a verificação de pets perdidos no banco Clever Cloud.

Descrição da Imagem

Este fluxograma descreve o funcionamento do sistema Find Pets:

  • O Usuário inicia o fluxo no aplicativo mobile desenvolvido com Expo Go ao tentar cadastrar um animal encontrado na rua.
  • A imagem do animal é imediatamente enviada para a API hospedada no Cloud Render, que encaminha essa imagem para dois serviços:
    • Roboflow: Identifica o tipo e a raça do animal.
    • HuggingFace: Faz uma validação adicional da raça.
  • Os resultados são processados e aguardam até que o usuário prossiga para finalizar o cadastro.
  • Ao prosseguir:
    • O backend (Cloud Render) envia as informações de tipo e raça para o Clever Cloud, onde está o banco de dados.
    • O Clever Cloud retorna uma lista de pets perdidos com tipo e raça correspondentes, incluindo suas coordenadas geográficas (latitude e longitude).
    • O Cloud Render calcula a distância geográfica entre o local onde o animal foi encontrado e cada animal perdido.
  • Se algum animal perdido estiver a menos de 10km de distância, e possuir o mesmo tipo e raça, o sistema:
    • Envia automaticamente um e-mail ao dono do animal perdido alertando sobre a possível correspondência.
  • Caso não haja nenhum pet semelhante no raio especificado:
    • O animal encontrado é cadastrado normalmente no banco de dados remoto (Clever Cloud).

As caixas do diagrama representam:

  • O usuário em preto.
  • Os serviços externos e backend (Cloud Render, Roboflow, HuggingFace, Clever Cloud) em amarelo.
  • As conexões entre os módulos são feitas por setas indicando o fluxo da informação.
{
  "message": "🐾 Tipo: Cachorro\n🏷️ Raças: Siberian Husky, Alaskan Malamute, Tamaskan"
}
{
  "message": "🐾 Tipo: Gato\n🏷️ Raças: British Shorthair, Chartreux, Russian Blue"
}

🗂️ Estrutura de arquivos e pastas

/Find_Pets                               # Diretório raiz do projeto Find Pets
│
├── assets/                              # Recursos auxiliares (documentações, imagens, etc.)
│   ├── docs/                            # Documentos diversos do projeto
│   └── imgs/                            # Imagens utilizadas em apresentações, docs, etc.
│
├── src/                                 # Diretório principal de código-fonte
│   │
│   ├── web_find-pets/                   # Aplicação Web (PHP)
│   │   ├── index.php                    # Arquivo inicial da aplicação web
│   │   ├── Dockerfile                   # Define o ambiente Docker para o app web
│   │   ├── docker-compose.yml           # Define os serviços da aplicação em containers
│   │   ├── Controller/                  # Controladores da aplicação (lógica do servidor)
│   │   │   └── Controller.php           # Lógica de controle geral
│   │   ├── Models/                      # Modelos da aplicação (ex: banco de dados)
│   │   │   └── DbConfig.php             # Configuração de conexão com o banco de dados
│   │   ├── View/                        # Arquivos de visualização (HTML + PHP + JS)
│   │   │   ├── login.php                # Página de login
│   │   │   ├── envio-senha.php          # Página de envio de senha
│   │   │   ├── esqueceu-senha.php       # Página de recuperação de senha
│   │   │   ├── add.php                  # Página de adição de usuário
│   │   │   ├── animal/                  # Páginas relacionadas aos animais
│   │   │   │   ├── add.php              # Formulário para adicionar animal
│   │   │   │   ├── animal.php           # Página individual de um animal
│   │   │   │   ├── anuncios.php         # Listagem de anúncios de animais
│   │   │   │   └── upload.php           # Upload de imagens dos animais
│   │   │   └── user/                    # Páginas relacionadas ao usuário
│   │   │       ├── perfil.php           # Página de perfil do usuário
│   │   │       ├── pet.php              # Detalhes de um pet do usuário
│   │   │       ├── meuspets.php         # Lista de pets cadastrados pelo usuário
│   │   │       ├── sentinelapet.php     # Sentinela de um único pet
│   │   │       └── sentinelapets.php    # Sentinela de vários pets
│   │   └── Assets/                      # Recursos estáticos (CSS, JS e imagens)
│   │       ├── Css/
│   │       │   ├── estilo-template1.css # Estilo visual template 1
│   │       │   └── estilo-template2.css # Estilo visual template 2
│   │       ├── Js/                      # Scripts JavaScript
│   │       │   ├── index.js             # Script da página inicial
│   │       │   ├── add-animal.js        # Script para a página de animal
│   │       │   ├── add-user.js          # Script para a página de usuário
│   │       │   └── anuncios.js          # Script para a página de anúncios
│   │       └── Imagens/                 # Imagens utilizadas na aplicação
│   │           ├── Site/                # Imagens do site (interface geral)
│   │           │   └── Imgs/            # Pasta específica para imagens do site
│   │           ├── Perfis/              # Imagens de perfil dos usuários
│   │           │   └── Uploads/         # Imagens enviadas pelo usuário
│   │           └── Anuncios/            # Imagens dos anúncios de pets
│   │               └── Uploads/         # Uploads de imagens de anúncios
│   │
│   ├── app_mobile-expo/                 # Aplicativo mobile desenvolvido com Expo/React Native
│   │   └── src/
│   │       ├── App.js                   # Arquivo principal da aplicação mobile
│   │       ├── app/                     # Lógica da aplicação (telas e funcionalidades)
│   │       │   ├── Animais.js           # Tela de visualização de animais
│   │       │   ├── Anuncio.js           # Tela de detalhes de um anúncio
│   │       │   ├── Cadastro.js          # Tela de cadastro de usuário
│   │       │   ├── Findpets.js          # Tela principal com busca de pets
│   │       │   └── Login.js             # Tela de login
│   │       └── assets/                  # Recursos estáticos do app mobile
│   │           ├── imagens/             # Imagens utilizadas na interface do app
│   │           └── Estilos/
│   │               └── Estilos.js       # Estilos centralizados da aplicação
│   │
│   ├── api_chatbot/                     # API Python e Chatbot integrado (Telegram, etc)
│   │   ├── main.py                      # Arquivo principal que inicializa a API/chatbot
│   │   ├── requirements.txt             # Dependências da API em Python
│   │   ├── python-version.txt           # Define a versão exata do Python (ex: 3.12.9)
│   │   ├── .env                         # Variáveis de ambiente sensíveis (chaves, senhas)
│   │   ├── api/                         # Rotas da API (FastAPI)
│   │   │   ├── animal_router.py         # Rotas relacionadas aos animais
│   │   │   ├── user_router.py           # Rotas relacionadas aos usuários
│   │   │   └── telegram_bot.py          # Integração com Telegram (bot)
│   │   ├── services/                    # Serviços auxiliares e módulos do backend
│   │   │   ├── dataset.py               # Manipulação de datasets
│   │   │   ├── dbconfig.py              # Configuração do banco de dados
│   │   │   ├── embed.py                 # Embeddings para IA (ex: vetores semânticos)
│   │   │   ├── image.py                 # Processamento de imagens
│   │   │   ├── loader.py                # Carregamento de dados
│   │   │   ├── llm.py                   # Integração com modelos de linguagem (LLMs)
│   │   │   └── rag.py                   # Implementação de RAG (Retrieval-Augmented Generation)
│   │   ├── dataset/                     # Diretório de datasets
│   │   │   ├── dataset/                 # Dados em formato compactado
│   │   │   │   └── Chappie_Dataset.zip  # Dataset com informações de treino/teste
│   │   │   └── hero.jpg                 # Imagem ilustrativa/mascote
│   │   ├── utils/                       # Utilitários diversos da API
│   │   │   ├── email.py                 # Envio de e-mails
│   │   │   ├── logs.py                  # Registro de logs
│   │   │   └── registros.txt            # Arquivo com registros manuais ou de teste
│   │   └── swagger/                     # Interface da documentação Swagger
│   │       ├── index.html               # Página principal da documentação Swagger
│   │       ├── model/                   # Modelo OpenAPI (esquema de endpoints)
│   │       │   └── openapi/
│   │       │       └── openapi.json     # Definições dos endpoints e modelos
│   │       ├── assets/                  # Arquivos estáticos do Swagger
│   │       │   └── css/                 # Estilos da interface Swagger
│   │       │       ├── index.css
│   │       │       └── swagger-ui.css
│   │       └── controller/              # Scripts de inicialização da interface do swagger
│   │           └── js/
│   │               ├── swagger-initializer.js
│   │               ├── swagger-ui-bundle.js
│   │               └── swagger-ui-standalone-preset.js
│   │
│   └── impressora_termica_POS-58/       # Scripts e configs para impressora térmica (ex: POS-58)
|      	├── windows/                     # Scripts específicos para impressão no sistema Windows
|      	│   ├── printer-x-feira.py       # Script de impressão customizado para a feira "X Feira"
|      	│   ├── printer.py               # Script de impressão padrão utilizado no sistema Find Pets
|      	│   ├── requirements.txt         # Lista de dependências (ex: pywin32) necessárias para acessar drivers de impressora
|      	│   └── venv.bat                 # Script para ativar o ambiente virtual e executar a impressão automaticamente
|      	│          
│       └── terraform-aws-vmbox/         # Infraestrutura como código (Terraform)
│           ├── main.tf                  # Script principal do Terraform
│           ├── infra.bat                # Script batch para provisionamento
│           ├── aws_ec2/                 # Arquivos específicos da imagem EC2 (Linux AMI) ISO inicial e Imagem do sistema em VDI
│           │   ├── al2023-amzn3-virtualbox.vdi 
│           │   └── Seed.iso             
|           |
│           └── instalacao/seed-cloud-init-amazon-linux-2023/ # Scripts de configuração automatizada
│               ├── seed-original/       # ISO original sem modificações
│               │   └── Seed.iso
│               ├── seed-modificado/     # ISO modificada com configs da impressora
│               │   ├── Seed.iso
│               │   └── Seed.mds
│               └── seed-descompactado/  # Conteúdo extraído da ISO
│                   ├── install/         # Arquivos de instalação
│                   ├── meta-data        # Metadata de provisionamento
│                   ├── user-data        # Script de inicialização (cloud-init)
│                   └── printer.py       # Script Python para interface com impressora térmica
│
├── README.md                            # Arquivo de descrição geral do projeto
├── LICENSE                              # Licença de uso do projeto
├── SECURITY.md                          # Política de segurança e vulnerabilidades
└── CODE_OF_CONDUCT.md                   # Código de conduta para colaboradores

☁️ Deploy na cloudrender

Para rodar o projeto Find Pets na cloud render, siga os passos abaixo.

Passo a passo para deploy no render

Obtenha este Projeto

  • Clonar via Git
git clone https://github.com/RamonCintas/Find_Pets
  • Download ZIP

  1. Clique aqui para baixar o repositório

  2. Extraia na sua máquina.

Deploy do projeto:

Faça o deploy dos arquivos da pasta app_mobile-expo em uma snack previamente criada no site expo.dev Video O que é o Expo no React Native?

Deploy das pastas api_chatbot e web_find-pets no cloud render utilizando o repositorio do github obs: plano gratuito do cloud render é válido por 1 mês. https://dashboard.render.com/

deploy-render_api_chatbot.pdf deploy-render_web_find-pets.pdf ENV-API-CHATBOT.txt ENV-WEB-FINDPETS.txt Video DEPLOY SPRING BOOT NO RENDER

SQL para criar o banco de dados mysql-modificado-clever-cloud.sql

OBS: cloud render suspende o serviço se ficar 5 minutos sem inatividade use o https://uptimerobot.com/ para fazer pings e requisições para o serviço do cloud render ficar sempre ativo

Para testar no smartphone instale o aplicativo da expo go na play store e scaneie o qrcode do site da expo.dev

sites para conseguir os tokens e os modelos estão na seção de links

Dificuldade encontrada no desenvolvimento do projeto localmente e como resolver erros com o ChromaDB no Windows

Se você estiver enfrentando erros ao instalar ou rodar o chromadb em sistemas Windows, certifique-se de que o Visual Studio esteja corretamente configurado com os seguintes componentes:

Desktop development with C++

✔️ Workload: Desktop development with C++

Compilador C++ v143

✔️ MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)

Windows 11 SDK

✔️ Windows 11 SDK (10.0.22621.0)

Essas configurações são necessárias para que o Python consiga compilar extensões nativas como as utilizadas pelo chromadb.

🤖 Chappie Chatbot

Este sistema de RAG (Retrieval-Augmented Generation) utilizando LangChain, Hugging Face, ChromaDB e Telegram Bot, permite interações em linguagem natural com base em documentos PDF contendo anúncios de animais.

📸 Demonstrações

🐶 Documento PDF Utilizado 💬 Interface via Telegram
Imagem do anúncio da Amora Imagem do Telegram Bot

📘 Pipeline Completo

graph TD;

    %% Estilos
    classDef deploy fill:#cce5ff,stroke:#004085,color:#004085,font-weight:bold;
    classDef loader fill:#b3d7ff,stroke:#003366,color:#003366,font-weight:bold;
    classDef embed fill:#99ffcc,stroke:#006633,color:#006633,font-weight:bold;
    classDef persist fill:#ccffcc,stroke:#009933,color:#009933,font-weight:bold;
    classDef core fill:#e6f7ff,stroke:#3399ff,color:#0066cc,font-weight:bold;
    classDef telegram fill:#ffe6cc,stroke:#cc6600,color:#cc6600,font-weight:bold;
    classDef rag fill:#fff2cc,stroke:#b38b00,color:#b38b00,font-weight:bold;
    classDef llm fill:#fff5f5,stroke:#cc0000,color:#cc0000,font-weight:bold;
    classDef response fill:#fff0f5,stroke:#b30059,color:#b30059,font-weight:bold;
    classDef logs fill:#ffd6d6,stroke:#cc0000,color:#cc0000,font-weight:bold,font-style:italic;
    classDef arrow stroke:#888,stroke-width:2px;

    %% PRÉ-PROCESSAMENTO (DEPLOY)

    A1["1️⃣ Geração de Anúncios | dataset.py |<br>- Busca dados de animais e anunciantes no MySQL |<br>- Cria PDFs com FPDF |<br>- Compacta PDFs em arquivo .zip"]:::deploy

    A2["2️⃣ Carregamento de PDFs | loader.py |<br>- Descompacta o arquivo .zip |<br>- Lê PDFs com PyPDFLoader |<br>- Segmenta documentos em chunks com metadados"]:::loader

    A3["3️⃣ Vetorização com Embeddings | embed.py |<br>- Usa sentence-transformers/all-MiniLM-L6-v2 |<br>- Gera vetores semânticos dos chunks |<br>- Armazena vetores localmente no ChromaDB"]:::embed

    A4["4️⃣ Persistência Vetorial | ChromaDB + SQLite |<br>- Armazena vetores em arquivo chroma.sqlite3 para consultas rápidas"]:::persist

    A1 --> A2 --> A3 --> A4

    %% NÚCLEO DO PIPELINE

    C["📦 ChromaDB + SQLite |<br>- Base de dados vetorial persistente |<br>- Alimentada no deploy, consultada em runtime"]:::core

    %% CONSULTA EM TEMPO REAL (INTERAÇÃO)

    B1["💬 Interface Telegram Bot |<br>- Usuário envia perguntas em linguagem natural"]:::telegram

    B1 --> B1b["🧠 Geração de Embeddings da Pergunta | embed.py |<br>- Envia pergunta para sentence-transformers no Hugging Face<br>- Gera embedding da pergunta em runtime"]:::embed

    B1b --> B2["🔍 Recuperação de Contexto | rag.py |<br>- Busca chunks relevantes por similaridade no ChromaDB com embedding da pergunta |<br>- Usa LangChain para orquestrar"]:::rag

    B2 --> C

    B2 --> B3["🧠 Consulta ao Modelo LLM | llm.py |<br>- Modelo DeepSeek-R1-Distill da Hugging Face |<br>- Responde só com o contexto recuperado (modo RAG) |<br>- Remove HTML e duplicações automaticamente"]:::llm

    B3 --> B4["📲 Resposta ao Usuário |<br>- Bot envia resposta gerada"]:::response

    %% LOGS

    L["📝 Logs Automatizados | logs.py |<br>- Registro automático de eventos e erros |<br>- Rotação inteligente: mantém últimos 50 registros"]:::logs

    A1 -.-> L
    A2 -.-> L
    A3 -.-> L
    A4 -.-> L
    B1 -.-> L
    B1b -.-> L
    B2 -.-> L
    B3 -.-> L

    %% Estilo das setas
    class A1,A2,A3,A4,B1,B1b,B2,B3,B4,L arrow
    class C arrow
Loading

Warning

🚧 GitHub mobile não tem suporte para Mermaid, segue abaixo o diagrama ilustrado do sistema Find Pets

Fluxograma do ChatBot Chappie do Find Pets, representando o pipeline completo

📘 Descrição do Pipeline - Find Pets (ChatBot Chappie)

Este pipeline representa o funcionamento completo do sistema Find Pets, utilizado pelo ChatBot Chappie no Telegram. A arquitetura combina pré-processamento com geração de respostas baseada em RAG (Retrieval-Augmented Generation).

🏗️ 1. Geração de Anúncios (dataset.py)

  • Extrai dados de animais e anunciantes do banco MySQL.
  • Gera anúncios em formato PDF usando a biblioteca FPDF.
  • Compacta os arquivos PDF em um .zip para facilitar o carregamento.

📥 2. Carregamento e Segmentação (loader.py)

  • Descompacta o .zip contendo os PDFs.
  • Lê os arquivos com PyPDFLoader.
  • Segmenta os documentos em chunks semânticos com metadados.

🔢 3. Vetorização dos Chunks (embed.py)

  • Utiliza o modelo all-MiniLM-L6-v2 da Hugging Face para gerar embeddings dos chunks.
  • Os vetores são armazenados localmente no ChromaDB, usando um banco persistente em SQLite.

💾 4. Persistência Vetorial (chroma.sqlite3)

  • A base vetorial construída no deploy é armazenada em um arquivo local:
    • ChromaDB + SQLite (chroma.sqlite3).
  • Isso permite consultas rápidas por similaridade semântica durante as interações com o bot.

💬 5. Entrada do Usuário via Telegram

  • O usuário interage com o ChatBot Chappie via mensagens de texto no Telegram.
  • As perguntas são processadas em tempo real.

🧠 6. Geração de Embeddings da Pergunta (embed.py)

  • A pergunta do usuário é enviada ao modelo all-MiniLM-L6-v2 (via Hugging Face).
  • O sistema gera um embedding vetorial da pergunta em runtime.

🔍 7. Recuperação de Contexto (rag.py)

  • Utiliza LangChain para buscar os chunks mais relevantes no ChromaDB, com base na similaridade com a pergunta.
  • Fornece o contexto ideal para a geração da resposta.

🧾 8. Geração de Resposta com LLM (llm.py)

  • Com o contexto em mãos, o modelo DeepSeek-R1-Distill da Hugging Face gera uma resposta contextualizada.
  • Etapa de pós-processamento remove HTML e duplicações automaticamente.

📲 9. Resposta ao Usuário

  • A resposta final é enviada ao usuário pelo Telegram de forma direta e personalizada.

📝 10. Logs Automatizados (logs.py)

  • O pipeline registra automaticamente eventos e erros em logs rotativos.
  • Armazena os últimos 50 eventos para garantir rastreabilidade e performance.

🔄 Visão Geral

O sistema opera em duas fases complementares:

⚙️ Fase 1 — Pré-processamento (Deploy)

  • Executada sempre que há novo deploy (por exemplo, após commit no GitHub).
  • Geração dos anúncios em PDF → segmentação em chunks → vetorização e armazenamento no ChromaDB.

🚀 Fase 2 — Runtime (Execução Online)

  • O usuário envia uma pergunta → embedding gerado → consulta vetorial → resposta com LLM.
  • Todo o processo ocorre em tempo real, com base na base vetorial local.

✅ Benefícios

  • Arquitetura eficiente e escalável.
  • Sistema explicável, com contexto baseado em documentos reais.
  • Respostas rápidas e personalizadas.

🏗️ Arquitetura e fluxo de interação

Imagem da arquitetura e fluxo do chatbot

🖨️ Integração com impressora térmica POS-58

Impressora POS-58 (esquerda) e exemplo de impressão (direita).

Impressora POS-58 Exemplo de Impressão

Guia Definitivo: Instalação e Configuração da Impressora Térmica POS-58

Este guia completo foi desenvolvido para te orientar, passo a passo, na instalação e configuração da impressora térmica POS-58, abordando:

  • Instalação dos drivers;
  • Configuração da porta USB;
  • Preparação do ambiente no Windows e no Linux;
  • Garantia de impressão correta e funcional.

Além disso, este material também apresenta um processo detalhado para configurar uma máquina virtual com Amazon Linux 2023 no VirtualBox, a partir de um sistema Windows, incluindo:

  • Conversão da imagem .qcow2 para o formato .vdi;
  • Instalação do Terraform;
  • Utilização do terraform-provider-virtualbox;
  • Configuração automatizada com cloud-init.

Ao final, você terá um ambiente totalmente funcional e automatizado para testes com o Amazon Linux 2023 no VirtualBox, incluindo inicialização via cloud-init.

Este guia foi testado com sucesso no Amazon Linux 3 executado no VirtualBox.

Obtenha este Projeto

  • Clonar via Git
git clone https://github.com/RamonCintas/Find_Pets
  • Download ZIP

  1. Clique aqui para baixar o repositório

  2. Extraia na sua máquina.

Instalação da Impressora no windows

  1. Descompacte o arquivo printer-driver.zip.

  2. Acesse:

printer-driver/DRIVE_MINI_IMPRESSORA/POS_Printer_Driver_V11.3.0.0/

  1. Localize o arquivo POS58.INF. para prosseguir com a instalação.

  2. Assista ao Tutorial em Vídeo Como Instalar Impressora de 58mm │ POS-58 driver │ iFood Configuração
    Assista do minuto 1:48 até 8:41 para a instalação.

Tempo Passo
1:48 Descompactar o arquivo do driver.
1:58 Salvar a pasta onde desejar (ex.: Downloads, Desktop).
2:17 Confirmar que a pasta do driver está pronta para instalação.
2:45 Acessar “Dispositivos e Impressoras” via Painel de Controle.
3:16 Ligar a impressora e conectar os cabos USB.
3:31 Observar o dispositivo USB printer aparecer.
3:45 Clicar em "Adicionar uma impressora".
3:56 Caso não apareça, escolher "A impressora que eu quero não está na lista".
4:07 Selecionar "Adicionar impressora local ou de rede com configurações manuais".
4:14 Escolher a porta correta (ex: USB001, USB002, USB003).
4:41 Confirmar a porta e avançar.
4:49 Selecionar "Com Disco" para carregar o driver manualmente.
4:52 Navegar até o arquivo POS58.INF e selecionar.
5:16 Prosseguir com a instalação e substituir driver se necessário.
5:32 Opcional: renomear a impressora para “POS-58”.
5:49 Definir como impressora padrão e imprimir página de teste.
5:57 Se houver erro, verificar porta USB selecionada.
6:27 Ajustar a porta USB nas propriedades da impressora, testando as opções disponíveis.
7:06 Confirmar que o trabalho de impressão foi enviado corretamente.
7:28 Continuar testando portas até acertar a correta.
7:57 Aguardar alguns segundos entre os testes para evitar travamentos.
8:16 Não alterar a porta USB depois de configurada para evitar erros.
8:37 Imprimir páginas de teste adicionais para confirmar a instalação.
  1. Defina o nome da Impressora

⚠️ Nome recomendado:

POS-58

Verifique se o nome da impressora está como POS-58

verificar_nome_POS-58_e_compartilhamento

Configurando o Ambiente para Rodar o Projeto no windows

No diretório raiz do projeto, execute o script para executar o ambiente virtual do Python:

.\venv.bat

Para desativar o ambiente Python:

deactivate

Visutal Studio Code (VS CODE)

Terminal VS Code

Configurando e Executando Amazon Linux 2023 no VirtualBox (Windows)

Impressora POS-58 no Amazon Linux 3 da AWS com Terraform e Virtual Box

pos-58 imprimindo pelo virtual box

Downloads Necessários

VirtualBox 7.1.6

Instale o Virtualbox com permissões de ADMIN

vmbox-execute-admin

Dependencias do virtual box 7.1.6

VirtualBox Extension Pack 7.1.6

OBS: Mova o arquivo baixado para a pasta raiz do oracle virtual box e clique duas vezes no arquivo .vbox-extpack para abrir o virtualbox e instalar os extension pack

  • pasta donwloads

C:\Users\Admin\Downloads\Oracle_VirtualBox_Extension_Pack-7.1.6.vbox-extpack

  • pasta de instalação do vmbox

C:\Program Files\Oracle\

Terraform Provider VirtualBox

Amazon Linux 2023

Baixar imagem (formato .qcow2)

Convertendo QCOW2 para VDI

Baixar QEMU (Windows)

Tutorial

**Comandos (executar no CMD como administrador)

"C:\Program Files\qemu\qemu-img.exe" qemu-img convert -f qcow2 -O raw al2023-kvm-2023.6.20250218.2-kernel-6.1-x86_64.xfs.gpt.qcow2 al2023-amzn3-virtualbox-2023.6.20250218.2-kernel-6.1-x86_64.xfs.gpt.raw

"C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" convertfromraw al2023-amzn3-virtualbox-2023.6.20250218.2-kernel-6.1-x86_64.xfs.gpt.raw al2023-amzn3-virtualbox-2023.6.20250218.2-kernel-6.1-x86_64.xfs.gpt.vdi --format VDI

"C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" modifyhd al2023-amzn3-virtualbox-2023.6.20250218.2-kernel-6.1-x86_64.xfs.gpt.vdi --compact

Baixar arquivo Seed.iso para cloud-init

Arquivo Seed.iso modificado para automatizar as instalações de pacotes e driver através da alteração do cloud-init

Cloud-init do Seed.iso modificado utilizando o imgburn-Running AL2 no VirtualBox (YouTube)

  • user-data.yaml
#cloud-config
# vim:syntax=yaml
users:
# A user by the name ec2-user is created in the image by default.
  - default
# Following entry create user1 and assigns password specified in plain text.
# Please not use of plain text password is not recommended from security best
# practises standpoint
  - name: user1
    groups: sudo
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    plain_text_passwd: amazon
    lock_passwd: false
# Following entry creates user2 and attaches a hashed passwd to the user. Hashed
# passwords can be generated with:
# python -c 'import crypt,getpass; print crypt.crypt(getpass.getpass())'
  - name: user2
    passwd: amazon
    lock_passwd: false
  - name: user3
    ssh-authorized-keys:
            - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6qTLUKcplsxt8IxzGC13YpqA+9ZXforvJdF3XeQKOzLrikjMGdYPUFTqjRzQwQMzmuRZJDPDPXbJ1MqpTI7xmP2LRJ84THn2+6kUofSKXMmzTV8EQvsxWJf9nDzJCtQWfYrFAGxEwtIK2CuycfrwqGqB5MZhFulpLes2U9LtpJpFwinwLoAiabZHlX+WW/6ZWt38WS8wgdJziyWHmyMUt1rMEOaS1E4xJ/nUDEOAMjYqNHj/gZLTNzJm9d2qtseGYbHuF7q/Dd52YeT8VLyQqupDR8YeKnUdbVwW6KNa6Scm5efwPvZL4EiTDDD2Q0HdNehieXbBhXJGMJ73sBV5r praween@u480fcf43c9865820ec18
    lock_passwd: true

chpasswd:
  list: |
    ec2-user:amazon
  expire: false

runcmd:
  - sudo dnf update -y
  - sudo dnf install -y gcc
  - sudo dnf install -y systemd
  - sudo dnf install -y systemd-devel
  - sudo dnf install -y cups
  - sudo dnf install -y cups-devel
  - sudo systemctl enable --now cups
  - sudo systemctl start cups
  - sudo usermod -aG lp ec2-user
  - sudo dnf install -y python3
  - sudo dnf install -y python3-pip
  - sudo dnf install -y python3-devel
  - pip3 install --upgrade --ignore-installed pip setuptools
  - pip3 install escpos
  - pip3 install pyusb
  - pip3 install pyserial
  - pip3 install pycups
  - sudo ln -sf /usr/bin/python3 /usr/bin/python
  - sudo mkdir -p /mnt
  - sudo mount /dev/cdrom /mnt
  - cd /mnt
  - sudo chmod +x install
  - sudo chmod +r install
  - sudo ./install
  - sleep 10
  - sudo lpadmin -p POS-58 -v usb://Unknown/Printer?serial=Printer -E -m raw
  - sudo lpadmin -d POS-58
  - sleep 10
  • meta-data.yaml
local-hostname: amazonlinux.onprem

# eth0 is the default network interface enabled in the image. You can configure
# static network settings with an entry like below.
#network-interfaces: |
#  iface eth0 inet static
#  address 192.168.1.10
#  network 192.168.1.0
#  netmask 255.255.255.0
#  broadcast 192.168.1.255
#  gateway 192.168.1.254

  • Install.sh drivers da impressora

    • ver src\impressora_termica_POS-58\windows\printer-driver\install.sh

  • printer.py arquivo para imprimir

    • ver src\impressora_termica_POS-58\windows\printer.py

Passo a Passo imgburn

imgbur

Instalação do Terraform no Windows

  1. Baixar o binário do Terraform
  1. Extrair e mover o binário
  • Extraia o conteúdo do .zip.
  • Mova de donwload para a pasta para: C:\Program Files\terraform_1.10.5_windows_amd64

  1. Adicionar o Terraform à variável de ambiente PATH

  2. Clique com o botão direito em Este Computador > Propriedades

  3. Vá em Configurações avançadas do sistema

  4. Clique em Variáveis de ambiente

  5. Em Variáveis do sistema, selecione Path > Editar > Novo

  6. Adicione: C:\Program Files\terraform_1.10.5_windows_amd64

  7. Clique em OK em todas as janelas

  8. Testar a instalação

  • Feche e reabra o terminal
  • Digite:
terraform --version
  • Deve retornar algo como:
Terraform v1.10.5

📺 Vídeo Tutorial

YouTube: Instalando o Terraform no Windows, Linux e MacOS

Verificar as variáveis de ambiente

  • usuario

    • path
      • C:\Users\Admin\AppData\Local\Programs\Python\Python312\Scripts\
      • C:\Users\Admin\AppData\Local\Programs\Python\Python312\

  • sistema

    • PATH
      • C:\Program Files\Terraform\
    • VBOX_MSI_INSTALL_PATH
      • C:\Program Files\Oracle\VirtualBox\

Verificar o endereço da impressora atraves do infra.bat

para anexar a impressora no virtualbox, quando o sistema mostrar a lista de impressoras verifique se o anddress configurado no infra.bat está igual ao anddress que está listado no sistema, o usb addres do infra.bat precisa ser igual ao adrress listado pelo 'list usbhost'

  • terminal vs code
  usb_devices.txt
  UUID: fb1ba32b-8955-4c8d-b102-1fe549ba54cf
  VendorId: 0x0416 (0416)
  ProductId: 0x5011 (5011)
  Revision: 2.0 (0200)
  Port: 1
  USB version/speed: 2/Full
  Manufacturer: STMicroelectronics
  Product: USB Portable Printer
  SerialNumber: Printer
  '''
  Address: {36fc9e60-c465-11cf-8056-444553540000}\0020
  '''
  Current State: Busy
  • infra.bat
'''
set "USB_ADDRESS={36fc9e60-c465-11cf-8056-444553540000}\0020"
'''

Rodando a impressora no amazon linux 2023 usando virtual box e terraform

  • Coloque o arquivo 'vdi' na pasta

    • terraform-aws-vmbox\terraform\aws_ec2\al2023-amzn3-virtualbox-2023.6.20250218.2-kernel-6.1-x86_64.xfs.gpt.vdi

  • Coloque o arquivo 'Seed.iso' na pasta

    • terraform-aws-vmbox\terraform\aws_ec2\Seed.iso

OBS: Não esqueça de conectar a impressora na mesma porta usb que você baixou os drivers verifique se todas as variáveis de ambiente estão com as informações corretas. Os nomes dos adaptadores de rede precisam estar corretos para que a VM possa acessar a internet e baixar os pacotes necessarios através do cloud-init quando iniciar a VM pela primeira vez

  • Verifique o infra.bat se todas as informações estão corretas antes de executar
'''
set "VBOX_PATH=C:\Program Files\Oracle\VirtualBox\VBoxManage.exe"
set "VM_NAME=AWS_EC2"
set "SEED_ISO_PATH=C:\Users\Admin\Desktop\terraform-aws-vmbox\aws_ec2\seed.iso"
set "BRIDGE_ADAPTER1=Realtek PCIe GBE Family Controller"
set "BRIDGE_ADAPTER2=Adaptador de Rede 802.11n Broadcom"
set "USB_PRINTER_NAME=POS58"
set "USB_VENDOR_ID=0416"
set "USB_PRODUCT_ID=5011"
set "USB_REVISION=0200"
set "USB_MANUFACTURER=STMicroelectronics"
set "USB_PRODUCT=USB Portable Printer"
set "USB_SERIALNUMBER=Printer"
set "USB_ADDRESS={36fc9e60-c465-11cf-8056-444553540000}\0020"
start "" "C:\Program Files\Oracle\VirtualBox\VirtualBox.exe"
cd /d "C:\Users\Admin\Desktop\terraform-aws-vmbox\"

'''

execute o comando

.\infra.bat

terraform

Saída do terminal VS CODE com Terraform e logs

🔐 Credenciais Padrão

Campo Valor
Login ec2-user
Usuário user1
Senha amazon

Login no Amazon Linux 3 da AWS

Login no Amazon Linux 3 da AWS

Teste de Impressão

ls
cd /mnt
ls
python printer.py

Amazon Linux 3 da AWS, simulando uma EC2 no Virtual box e executando impressão da POS-58

Imprimindo no Amazon Linux 3 da AWS

Detalhes da máquina virtual box

Config Da Máquina virtual

vmbox

Faça um backup do arquivo .VDI e .ISO para quando resetar a VM só substituir os arquivos .VDI e o .ISO pelas versões de backup

resetar-vm

Diagnóstico e Verificação

  • Verificar impressoras:
lpstat -p
lpstat -d
lpstat -v
lpinfo -v
  • Verificar conexão USB:
dmesg | grep usb
  • Verificar pacotes:
rpm -q systemd systemd-devel git cups cups-devel python3-devel
gcc --version
python3 --version
pip3 --version
groups $USER
  • Verificar bibliotecas Python:
pip3 show setuptools escpos pyusb pyserial pycups

Observações

Nota:
Caso a impressora não imprimir, verifique se a porta USB correta foi configurada no Windows. Teste portas diferentes, como USB001, USB002, etc.
Comando no PowerShell para pegar vendor id e output id da impressora:

Get-WmiObject -Query "Select * From Win32_PnPEntity Where DeviceID Like 'USB%'" | Select-Object DeviceID, Name
USB\VID_0416&PID_5011\PRINTER  Suporte de impressão USB
  • Sempre conecte a impressora na mesma porta USB configurada.
  • Caso não imprima, revise a porta configurada: USB001, USB002, etc.
  • Use Imprimir página de teste para validar.
  • Siga rigorosamente os passos do vídeo.
  • Certifique-se de que o CUPS esteja ativo.
  • Ajuste o nome e o serial da impressora conforme necessário no comando lpadmin.
  • Comando para gerar o requirements pip freeze > requirements.txt
  • Execute todos os comandos com permissão de administrador no CMD.
  • Use sempre a versão testada do VirtualBox (7.1.6) e do Terraform Provider para evitar problemas de compatibilidade.
  • Após converter a imagem .qcow2 para .vdi, adicione-a como disco primário ao criar a máquina no VirtualBox.
  • Use o Seed.iso modificado como unidade de CD/DVD para inicializar com suporte ao cloud-init.
  • gmail senha para aplicação ative o modo duas etapas

📚 Glossário

Certos termos são usados ao longo do projeto Find Pets com significados consistentes ou convenções. Abaixo estão 10 deles:

Termo Descrição
ISO Imagem de disco óptico usada para distribuição de sistemas operacionais ou software.
VDI Imagem de disco virtual usada por máquinas virtuais, especialmente no VirtualBox.
VM Máquina Virtual, ambiente isolado que simula um computador dentro de outro sistema.
QCOW2 Formato de imagem de disco usado pelo QEMU com recursos como compactação e snapshots.
EC2 Elastic Compute Cloud, serviço da AWS para criação e gestão de máquinas virtuais na nuvem.
AWS Amazon Web Services, plataforma de serviços de computação em nuvem da Amazon.
RAG Retrieval-Augmented Generation, técnica de IA que combina busca de dados com geração de texto.
ChromaDB Banco de dados vetorial usado para armazenar embeddings e facilitar buscas semânticas.
Embed Representação vetorial de dados (como texto ou imagem) usada em modelos de IA.
LLM Large Language Model, modelo de linguagem treinado com grandes volumes de texto.

📋 Links

🤖 api_chatbot • 📱 app_mobile-expo • 🌐 web_find-pets

📄 Documentação e Guias

⚠️ Erros Comuns e Soluções

🖥️ VirtualBox & CLI

☁️ Cloud-Init

🎓 Tutoriais e Vídeos

📝 Autores

Imagem de perfil de Camila Assunção
LinkedIn de Camila Assunção
Descrição da Imagem Esta imagem mostra a foto de perfil de Camila Assunção no Linkedin. O badge do linkedin, e ao clicar na imagem ou no badge, você será direcionado ao perfil.
Imagem de perfil de Sueli Alves
LinkedIn de Sueli Alvess
Descrição da Imagem Esta imagem mostra a foto de perfil de Sueli Alves no Linkedin. O badge do linkedin, e ao clicar na imagem ou no badge, você será direcionado ao perfil.
Imagem de perfil de Thiago Faria Borges
LinkedIn de Thiago Farias
Descrição da Imagem Esta imagem mostra a foto de perfil de Thiago Faria no Linkedin. O badge do linkedin, e ao clicar na imagem ou no badge, você será direcionado ao perfil.
Imagem de perfil de Ramon Gomes no GitHub
Badge com o nome Ramon Gomes LinkedIn de Ramon Gomes
Descrição da Imagem Esta imagem mostra a foto de perfil de Ramon Gomes no GitHub. O badge do github e outro badge do linkedin, e ao clicar na imagem ou nos badges, você será direcionado ao perfil.

⚖️ Licença

Projeto licenciado sob a MIT License Copyright © Fênix - Todos os direitos reservados.

(Voltar ao topo)

About

⚡ Find Pets Sistema Multiplataforma com Inteligência Artificial | https://www.youtube.com/shorts/9PWKri_mIpI

www.youtube.com/watch?v=Zq6zqtHITw4

Topics

api docker open-source php aws react-native telegram-bot terraform chatbot mobile-app web-application cloud-init expo animal-rescue rag fastapi pet-adoption llm lost-and-found-pets find-pets

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Languages