Download README.md from aionaion/chatdoc: direct link, hf CLI and curl.
- Browser
- Download file 13.2 kB
-
https://huggingface.co/spaces/aionaion/chatdoc/resolve/main/README.md
- Command line
-
hf download hf://spaces/aionaion/chatdoc/README.md
-
curl -L -o README.md https://huggingface.co/spaces/aionaion/chatdoc/resolve/main/README.md
title: RAG Chat Local
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
🧠 RAG Chat Local - Assistente de Documentação Técnica
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:
🔍 Ingestão e Processamento (ETL):
- Leitura Robusta: Utilizamos uma abordagem híbrida com
python-docxpara preservar a ordem de tabelas em DOCX,pypdfpara PDFs,pandaspara Excel eunstructuredcomo 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.
- Leitura Robusta: Utilizamos uma abordagem híbrida com
🎯 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-Encoderpara 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.
- 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 (
💬 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)
- Acesse console.groq.com/keys.
- Faça login (pode usar conta Google).
- Clique em "Create API Key".
- Dê um nome (ex:
RAG Local) e clique em Submit. - Copie a chave (começa com
gsk_) e cole no.envemGROQ_API_KEY.
2. Google Gemini (Ótimo Fallback - Cota Gratuita Generosa)
- Acesse aistudio.google.com/app/apikey.
- Faça login com sua conta Google.
- Clique em "Create API key".
- Selecione um projeto (ou crie um novo).
- Copie a chave e cole no
.envemGOOGLE_API_KEY.
3. OpenAI (Pago - Padrão de Indústria)
- Acesse platform.openai.com/api-keys.
- Crie uma conta e adicione um método de pagamento em "Billing".
- Vá em "API Keys" e clique em "Create new secret key".
- Dê um nome e clique em "Create secret key".
- Copie a chave (começa com
sk-) e cole no.envemOPENAI_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:
paraphrase-multilingual-mpnet-base-v2(Padrão)- Melhor para: Textos em Português e Inglês. Alta precisão semântica.
- Velocidade: Média.
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- 💬 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.
python scripts/chat_rag.py --interactivePergunta Ú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:
Crie o Space:
- Vá em huggingface.co/spaces.
- Crie um novo Space.
- Escolha o SDK: Docker.
Prepare os Arquivos:
- Certifique-se de ter o
Dockerfilena raiz. - Certifique-se de que a pasta
data/chroma_dbcontém o banco já ingerido (o deploy gratuito não persiste dados novos, então suba o banco pronto).
- Certifique-se de ter o
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.
No Hugging Face: Crie seu Space e copie o nome (ex:
usuario/meu-rag).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).
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_dbno seu GitHub (use Git LFS se for muito grande).
- Crie um arquivo no seu projeto:
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.