chatdoc / README.md
celiolr's picture
Deploy Docker: README.md
b0469f0 verified
|
Raw History Blame Contribute Delete
13.2 kB
metadata
title: RAG Chat Local
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

🧠 RAG Chat Local - Assistente de Documentação Técnica

Python FastAPI LangChain ChromaDB License: MIT

Powered by: Groq Google Gemini OpenAI

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

git clone https://github.com/celiolr/tfs_docs_chroma_rag_local.git
cd tfs_docs_chroma_rag_local

2. Crie um Ambiente Virtual

# Windows
python -m venv venv
.\venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

3. Instale as Dependências

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:

# 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.
  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.
  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.
  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:

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:

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.

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.

    python app/main.py
    
  • Chat Interativo no Terminal: Uma interface de linha de comando para perguntas e respostas rápidas.

    python scripts/chat_rag.py --interactive
    
  • Pergunta Única no Terminal: Faça uma única pergunta e saia (útil para scripts).

    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):

    # 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):
    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 para mais detalhes.


Desenvolvido com ❤️ para simplificar a gestão de conhecimento técnico.