--- title: RAG Chat Local emoji: 🧠 colorFrom: blue colorTo: indigo sdk: docker pinned: false --- # 🧠 RAG Chat Local - Assistente de Documentação Técnica ![Python](https://img.shields.io/badge/python-3.10%2B-blue) ![FastAPI](https://img.shields.io/badge/FastAPI-0.110.0-009688?logo=fastapi&logoColor=white) ![LangChain](https://img.shields.io/badge/LangChain-0.1.20-green) ![ChromaDB](https://img.shields.io/badge/ChromaDB-Local-orange) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) **Powered by:** ![Groq](https://img.shields.io/badge/Groq-Llama_3-f55036) ![Google Gemini](https://img.shields.io/badge/Google_AI-Gemini_Flash-4285F4?logo=google&logoColor=white) ![OpenAI](https://img.shields.io/badge/OpenAI-GPT--3.5%2F4-412991?logo=openai&logoColor=white) Este projeto é um sistema de **RAG (Retrieval-Augmented Generation)** projetado para permitir conversas naturais e inteligentes com sua base de documentos técnicos locais (PDFs, DOCX, Excel, Configurações, etc.). Ele utiliza Inteligência Artificial para ler, entender e responder perguntas sobre seus arquivos, citando as fontes e garantindo que as respostas sejam baseadas estritamente nos dados fornecidos. --- ## 🏗️ Arquitetura e Conceitos Chave O sistema opera em três etapas principais: 1. **🔍 Ingestão e Processamento (ETL):** * **Leitura Robusta:** Utilizamos uma abordagem híbrida com `python-docx` para preservar a ordem de tabelas em DOCX, `pypdf` para PDFs, `pandas` para Excel e `unstructured` como fallback, garantindo a melhor extração de texto possível para cada formato. * **Chunking:** O texto é dividido em pedaços menores ("chunks") de ~1000 caracteres. Isso é crucial para que a IA consiga focar em trechos específicos sem perder o contexto, especialmente em tabelas. * **Embeddings:** Cada chunk é convertido em um vetor numérico usando o modelo `paraphrase-multilingual-mpnet-base-v2`. Isso permite que o computador entenda o *significado* do texto. * **Vector Store:** Os vetores são armazenados no **ChromaDB**, um banco de dados local que roda sem a necessidade de um servidor externo. 2. **🎯 Recuperação (Retrieval):** * **Busca Híbrida:** Quando você faz uma pergunta, o sistema busca documentos de duas formas: pelo *significado* da pergunta (busca semântica) e pelo *nome do arquivo* (busca de metadados), garantindo que arquivos de configuração (`.ini`) sejam encontrados mesmo com pouco texto. * **Reranking (Reordenação):** Utilizamos um modelo `Cross-Encoder` para reavaliar os documentos encontrados e ordenar os mais relevantes para o topo, garantindo precisão máxima. * **Rede de Segurança:** Os 3 melhores resultados da busca inicial são sempre incluídos no contexto final, garantindo que a informação mais provável nunca seja descartada pelo Reranker. 3. **💬 Geração (Generation):** * **LLM (Large Language Model):** O contexto selecionado é enviado para uma IA Generativa (como Llama 3 via Groq, Gemini ou GPT) junto com a pergunta. * **Fallback Automático:** O sistema prioriza a **Groq** (pela velocidade). Se a cota acabar, ele muda automaticamente para o **Google Gemini** ou **OpenAI**, garantindo alta disponibilidade. --- ## 🚀 Tecnologias Utilizadas * **Linguagem:** Python 3.10+ * **Framework API:** FastAPI * **Orquestração de IA:** LangChain * **Banco Vetorial:** ChromaDB * **Processamento de Arquivos:** `python-docx`, `pypdf`, `pandas`, `unstructured` * **Modelos de IA:** * *Embeddings:* Sentence-Transformers (HuggingFace) * *Reranker:* MS-Marco-MiniLM * *LLMs Suportadas:* Llama 3 (Groq), Gemini Flash (Google), GPT-3.5/4 (OpenAI) --- ## 🛠️ Pré-requisitos * Python 3.10 ou superior instalado. * Git instalado. --- ## ⚙️ Instalação e Configuração ### 1. Clone o Repositório ```bash git clone https://github.com/celiolr/tfs_docs_chroma_rag_local.git cd tfs_docs_chroma_rag_local ``` ### 2. Crie um Ambiente Virtual ```bash # Windows python -m venv venv .\venv\Scripts\activate # Linux/Mac python3 -m venv venv source venv/bin/activate ``` ### 3. Instale as Dependências ```bash pip install -r requirements.txt ``` ### 4. Configure as Variáveis de Ambiente Copie o arquivo de exemplo para criar o seu arquivo de configuração real: ```bash # Windows copy .env.example .env # Linux/Mac cp .env.example .env ``` Agora, abra o arquivo `.env` em um editor de texto (Bloco de Notas, VS Code) e preencha as chaves de API conforme explicado abaixo. --- ## 🔑 Como Obter as Chaves de API O sistema precisa de pelo menos uma chave de API para gerar as respostas. Recomendamos obter as três para garantir que o sistema nunca pare de funcionar (fallback). ### 1. Groq (Recomendado - Grátis e Muito Rápido) 1. Acesse [console.groq.com/keys](https://console.groq.com/keys). 2. Faça login (pode usar conta Google). 3. Clique em **"Create API Key"**. 4. Dê um nome (ex: `RAG Local`) e clique em Submit. 5. Copie a chave (começa com `gsk_`) e cole no `.env` em `GROQ_API_KEY`. ### 2. Google Gemini (Ótimo Fallback - Cota Gratuita Generosa) 1. Acesse [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey). 2. Faça login com sua conta Google. 3. Clique em **"Create API key"**. 4. Selecione um projeto (ou crie um novo). 5. Copie a chave e cole no `.env` em `GOOGLE_API_KEY`. ### 3. OpenAI (Pago - Padrão de Indústria) 1. Acesse [platform.openai.com/api-keys](https://platform.openai.com/api-keys). 2. Crie uma conta e adicione um método de pagamento em "Billing". 3. Vá em "API Keys" e clique em **"Create new secret key"**. 4. Dê um nome e clique em "Create secret key". 5. Copie a chave (começa com `sk-`) e cole no `.env` em `OPENAI_API_KEY`. --- ## 🧠 Configuração Avançada ### Modelo de Vetorização (Embeddings) O "modelo de embeddings" é o cérebro que transforma seu texto em números para que o sistema possa buscar por similaridade. Você pode alterar esse modelo no arquivo `.env`. No arquivo `.env`, procure pela linha: ```ini EMBEDDINGS_MODEL=paraphrase-multilingual-mpnet-base-v2 ``` **Opções Recomendadas:** 1. **`paraphrase-multilingual-mpnet-base-v2` (Padrão)** * **Melhor para:** Textos em Português e Inglês. Alta precisão semântica. * **Velocidade:** Média. 2. **`all-MiniLM-L6-v2`** * **Melhor para:** Velocidade extrema e máquinas com pouco processamento. * **Velocidade:** Muito Rápida. (Nota: Funciona melhor em Inglês). ⚠️ **IMPORTANTE:** Se você mudar o modelo no `.env`, o banco de dados antigo se tornará incompatível. **Você deve obrigatoriamente resetar o banco:** `python scripts/ingest_documents.py --reset` ### Tipos de Arquivo Suportados O sistema está configurado para processar uma lista específica de extensões de arquivo. Você pode modificar esta lista diretamente no arquivo `app/core/config.py`, na variável `supported_extensions`. **Extensões Padrão:** ```python self.supported_extensions: List[str] = [ '.txt', '.md', '.pdf', '.docx', '.ini', '.xlsx', '.xls', '.pptx', '.ppt', '.html', ] ``` Para adicionar um novo tipo, como `.csv`, basta adicioná-lo à lista. Lembre-se que a qualidade da extração dependerá das bibliotecas de processamento (`pandas` para CSV, por exemplo). --- ## 🏃‍♂️ Como Usar ### 1. Adicione seus Documentos Coloque seus arquivos na pasta: `data/raw_documents` ### 2. Ingestão de Dados (Indexação) Execute o script para ler os arquivos e criar o banco de dados. ```bash python scripts/ingest_documents.py --reset ``` ### 3. Inicie a Aplicação Existem três formas de interagir com o sistema: * **API Web (Recomendado):** Inicia a API RESTful e a interface de chat no navegador. ```bash python app/main.py ``` * 💬 **Acesse o Chat:** 👉 **http://localhost:8000/chatdoc** * 📄 **Documentação da API (Swagger):** 👉 **http://localhost:8000/docs** * **Chat Interativo no Terminal:** Uma interface de linha de comando para perguntas e respostas rápidas. ```bash python scripts/chat_rag.py --interactive ``` * **Pergunta Única no Terminal:** Faça uma única pergunta e saia (útil para scripts). ```bash python ask.py "Qual a senha de homologação do Sistema X?" python ask.py "Quais documentos estão no escopo?" python ask.py "Quais são as linguagens de programação mencionadas nos documentos?" ... ``` --- ## ☁️ Deploy (Hugging Face Spaces) Este projeto está pronto para ser hospedado gratuitamente no Hugging Face Spaces usando Docker. ### Passos para Deploy: 1. **Crie o Space:** * Vá em huggingface.co/spaces. * Crie um novo Space. * Escolha o SDK: **Docker**. 2. **Prepare os Arquivos:** * Certifique-se de ter o `Dockerfile` na raiz. * Certifique-se de que a pasta `data/chroma_db` contém o banco já ingerido (o deploy gratuito não persiste dados novos, então suba o banco pronto). 3. **Envie via Git (Recomendado):** ```bash # 1. Clone o repositório do Space git clone https://huggingface.co/spaces/SEU_USUARIO/NOME_DO_SPACE cd NOME_DO_SPACE # 2. Configure o Git LFS (para suportar o banco de dados) git lfs install git lfs track "*.sqlite3" "*.bin" # 3. Copie os arquivos do projeto para esta pasta (app, scripts, data, Dockerfile, requirements.txt) # 4. Envie git add . git commit -m "Deploy inicial" git push # ⚠️ Importante: Quando pedir a senha, NÃO use sua senha de login. Use um Access Token (Write) criado em Settings -> Access Tokens. ``` ### Opção C: Sincronização Automática (GitHub Actions) Se você já usa o GitHub, pode configurar para que ele atualize o Hugging Face automaticamente. 1. **No Hugging Face:** Crie seu Space e copie o nome (ex: `usuario/meu-rag`). 2. **No GitHub:** * Vá no seu repositório em **Settings** > **Secrets and variables** > **Actions**. * Clique em **New repository secret**. * Nome: `HF_TOKEN`. * Valor: Seu token de acesso do Hugging Face (com permissão `write`). 3. **Crie o Workflow:** * Crie um arquivo no seu projeto: `.github/workflows/sync_to_hub.yml`. * Cole o conteúdo abaixo (substitua `SEU_USUARIO/NOME_DO_SPACE`): ```yaml name: Sync to Hugging Face hub on: push: branches: [main] workflow_dispatch: jobs: sync-to-hub: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 lfs: true - name: Push to hub env: HF_TOKEN: ${{ secrets.HF_TOKEN }} run: | git config --global user.email "bot@github.com" git config --global user.name "GitHub Actions" git remote add space https://SEU_USUARIO:$HF_TOKEN@huggingface.co/spaces/SEU_USUARIO/NOME_DO_SPACE git push --force space main ``` * **Atenção:** Para isso funcionar, você precisa commitar a pasta `data/chroma_db` no seu GitHub (use Git LFS se for muito grande). 4. **Configure as Variáveis:** * No painel do Space, vá em **Settings** -> **Variables and secrets**. * Adicione `GROQ_API_KEY`, `SECRET_KEY`, etc. --- ## 📂 Estrutura do Projeto ``` . ├── app/ # Contém a lógica da aplicação e da API │ ├── api/ # Endpoints da API (Rotas) │ ├── core/ # Configurações e inicialização │ ├── services/ # Lógica de Negócio (RAG, Processamento, etc.) │ ├── static/ # Frontend (HTML/JS do Chat) │ └── utils/ # Utilitários (Cliente TFS) ├── data/ │ ├── chroma_db/ # Banco de dados vetorial (Gerado automaticamente) │ ├── raw_documents/ # Coloque seus arquivos aqui │ └── processed/ # Arquivos movidos para cá após ingestão ├── scripts/ │ ├── ingest_documents.py # Script principal de ingestão │ ├── download_tfs_docs.py # Script para baixar docs do TFS │ ├── list_tfs_docs.py # Script para listar docs do TFS │ ├── inspect_db.py # Ferramenta para inspecionar o banco │ ├── check_models.py # Ferramenta para listar modelos disponíveis Google │ ├── ask.py # Script para perguntas rápidas via terminal │ ├── query.py # Script to query the RAG API │ ├── valida_search.py # Ferramenta de teste de busca │ └── chat_rag.py # Interface de chat via terminal ├── tests/ # Testes unitários e de integração ├── .env.example # Exemplo de arquivo de configuração └── requirements.txt # Lista de dependências ``` --- ## 📄 Licença Este projeto está licenciado sob a Licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes. --- **Desenvolvido com ❤️ para simplificar a gestão de conhecimento técnico.**