PrivateGPT v2: chatbot para documentos 100% privado

#Por que o PrivateGPT v2 para um chatbot de documentos locais

A necessidade é clássica: poder fazer perguntas em linguagem natural a um corpus de documentos internos (contratos, holerites, faturas, relatórios) sem enviar esses dados para OpenAI, Anthropic ou Google. É exatamente isso que o PrivateGPT visa desde a primeira versão lançada em 2023.

A versão 2 do projeto tomou uma decisão clara: não há mais motor LLM integrado nem gerenciamento interno de quantização. Em vez disso, o PrivateGPT v2 delega a geração a um backend externo — Ollama na maioria dos casos. Isso torna o projeto muito mais fácil de manter e permite acesso a toda a biblioteca de modelos Ollama (Qwen, Gemma, Granite, Mistral, etc.) sem configuração específica.

100% local

Tudo roda na sua máquina. Nenhuma telemetria, nenhuma chamada de saída após o download dos modelos.

UI do Gradio incluída

Uma interface web é aberta em localhost, pronta para conversar com seus documentos — não é preciso improvisar um front-end.

API compatível com OpenAI

O servidor PrivateGPT também expõe endpoints REST próximos do formato da OpenAI, úteis se você quiser integrá-lo a uma aplicação desenvolvida internamente.

Formatos compatíveis

PDF, DOCX, PPTX, MD, TXT, HTML, EPUB, CSV e vários outros formatos por meio dos loaders subjacentes do LlamaIndex.

#Pré-requisitos

Python 3.11

O PrivateGPT v2 suporta oficialmente apenas Python 3.11. Com versões 3.12+, algumas dependências ainda falham.

Poetry

O projeto usa o Poetry para gerenciar suas dependências com extras (ui, llms-ollama, embeddings-ollama, vector-stores-qdrant).

Ollama instalado e ativo

Daemon do Ollama acessível em http://localhost:11434. Se você ainda não o tiver, instale-o primeiro — o instalador leva 3 minutos.

No mínimo 8 GB de RAM

16 GB são suficientes para trabalhar com conforto. Se você carregar um modelo 8B–9B Q4 na VRAM via Ollama, conte com mais 5 a 7 GB na GPU.

GPU recomendada (opcional)

Uma GPU RTX 3060 de 12 GB ou superior permite o uso de modelos de 8B a 14B com tempo de resposta adequado. Sem GPU, fique nos modelos de 3B (Granite 4.2 3B ou Qwen 3.5 2B).

#1. Instalar o PrivateGPT v2

O projeto está no GitHub em zylon-ai/private-gpt. Clonamos o repositório, instalamos o Poetry se ainda não estiver instalado e depois instalamos as dependências com os extras correspondentes ao backend escolhido.

git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt

curl -sSL https://install.python-poetry.org | python3 -
# Ajoutez ~/.local/bin au PATH si ce n'est pas déjà fait

poetry install --extras "ui llms-ollama embeddings-ollama vector-stores-qdrant"

Este comando instala quatro grupos de extras: a UI do Gradio, o cliente LLM Ollama, o cliente de embeddings Ollama e o Qdrant como banco vetorial local integrado. A instalação leva de 5 a 15 minutos, dependendo da sua conexão — há muitas dependências científicas (numpy, scipy, transformers).

#2. Configurar o Ollama como backend de LLM e embeddings

O PrivateGPT v2 usa um sistema de perfis YAML em settings/. O perfil ollama é ativado por meio da variável de ambiente PGPT_PROFILES.

Antes de tudo, baixamos os dois modelos de que vamos precisar: um modelo de geração e um modelo de embeddings. Para o francês, Qwen 3.5 9B é uma boa escolha padrão de LLM em 2026 (6,6 GB, 256k de contexto, licença Apache 2.0), e nomic-embed-text continua sendo uma excelente opção leve de embeddings multilíngues.

# LLM de génération
ollama pull qwen3.5:9b

# Modèle d'embeddings (137M, ~280 Mo)
ollama pull nomic-embed-text

Em seguida, verifica-se o arquivo settings/settings-ollama.yaml fornecido no repositório. Ele deve apontar para os nomes corretos dos modelos e para a URL correta do Ollama:

llm:
  mode: ollama
  max_new_tokens: 512
  context_window: 8192

embedding:
  mode: ollama

ollama:
  llm_model: qwen3.5:9b
  embedding_model: nomic-embed-text
  api_base: http://localhost:11434
  embedding_api_base: http://localhost:11434
  request_timeout: 120.0

vectorstore:
  database: qdrant

qdrant:
  path: local_data/private_gpt/qdrant

#3. Iniciar o servidor e a UI

1. 01
   Verificar se o Ollama está em execução

   Digite "ollama list" em um terminal. Se o comando responder com a lista de modelos, o daemon está ativo. Caso contrário, execute "ollama serve" em um terminal separado.
2. 02
   Ativar o perfil do ollama

   No terminal em que você vai iniciar o PrivateGPT, exporte a variável PGPT_PROFILES=ollama. Isso indica ao projeto que deve carregar settings-ollama.yaml sobre settings.yaml.
3. 03
   Iniciar o servidor

   A partir da raiz do repositório, execute "PGPT_PROFILES=ollama make run". O servidor inicia na porta 8001 e o Gradio abre a interface no mesmo endereço.
4. 04
   Abrir a UI

   Acesse http://localhost:8001 no seu navegador. Você verá uma interface de chat com um painel lateral para carregar documentos.

PGPT_PROFILES=ollama make run

Na primeira inicialização, você verá nos logs o PrivateGPT entrar em contato com Ollama para verificar se os modelos declarados estão disponíveis. Se faltar um modelo, o servidor será encerrado com uma mensagem explícita — baixe o modelo ausente com ollama pull e reinicie.

#4. Indexar seus documentos

A interface Gradio oferece uma aba "Ingest" onde você arrasta e solta seus arquivos. Nos bastidores, o PrivateGPT divide cada documento em chunks (por padrão, ~1024 tokens com overlap de 200), calcula os embeddings via Ollama e armazena tudo no Qdrant.

PDF

Texto extraído via pypdf. Os PDFs escaneados (compostos apenas por imagens) não passam por OCR — use uma ferramenta como ocrmypdf antes da ingestão.

DOCX / PPTX

Suportados nativamente pelos carregadores do LlamaIndex. Tabelas e listas são preservadas em texto simples.

Markdown / TXT / HTML

Indexação imediata: este é o formato que funciona melhor para RAG na prática.

CSV

Cada linha se torna um chunk. Útil para bases de FAQ ou extrações de dados empresariais.

# Depuis la racine du repo private-gpt
python scripts/ingest_folder.py /chemin/vers/mes/documents \
  --watch  # surveille en continu les nouveaux fichiers

#Casos de uso profissionais concretos

#RH: consultar holerites e convenções coletivas

Caso típico: um departamento de RH com 200 contracheques mensais arquivados em PDF, mais a convenção coletiva do setor (geralmente mais de 100 páginas). O PrivateGPT v2 permite que um colaborador de RH faça perguntas do tipo "Qual é o coeficiente da Sra. Dupont em 2025?" ou "O que diz a convenção coletiva sobre os dias de afastamento para cuidar de um filho doente?".

Modelo recomendado

Qwen 3.5 9B Q4 é suficiente para extração factual. Para a interpretação jurídica do acordo, passe para Mistral Small 24B (bom em francês, 14 GB) ou Qwen 3.8 27B (18 GB, 262k de contexto), se houver VRAM suficiente.

Divisão em blocos

Para contracheques (1 página), um chunk = um documento. Para a convenção, o chunking por seção (título H2/H3) funciona melhor que o chunking por tokens.

Privacidade

É exatamente nesse caso que o PrivateGPT v2 faz a diferença: os contracheques nunca deveriam passar por um serviço na nuvem, inclusive no modo "empresa".

#Jurídico: analisar uma carteira de contratos

Caso típico: um serviço jurídico com algumas centenas de contratos de clientes/fornecedores em PDF, às vezes digitalizados. As perguntas comuns: "Quais contratos expiram nos próximos 6 meses?", "Qual cláusula de rescisão se aplica ao contrato ACME?", "Quais contêm uma cláusula de exclusividade?".

Pré-processamento

Execute o ocrmypdf nos documentos digitalizados antes da ingestão. Sem OCR, esses PDFs são invisíveis para a recuperação de informações.

Modelo recomendado

Mistral Small 24B ou Qwen 3.8 27B para a qualidade do raciocínio jurídico em francês. Qwen 3.5 9B é suficiente apenas para buscas.

Prompt do sistema

Defina um prompt de sistema que obrigue o modelo a citar o nome do contrato e o número da cláusula em cada resposta — caso contrário, o modelo tende a sintetizar sem citar as fontes.

#Contador: consultar uma pasta de faturas e extratos

Caso típico: um escritório de contabilidade que deseja consultar um conjunto de faturas de fornecedores e extratos bancários de um cliente (PDF + CSV). Perguntas pretendidas: "Qual é o total das faturas da Free Mobile em 2025?", "Há alguma fatura não paga do fornecedor X?"

Limitação que você deve conhecer

O RAG não agrega dados naturalmente: ele encontra os trechos relevantes, mas não calcula a soma com perfeição em grandes volumes. Para análises rigorosas, exporte o CSV das faturas para uma ferramenta dedicada e use o PrivateGPT para o contexto qualitativo.

Formato a ser priorizado

Os CSVs de contabilidade são indexados linha por linha — isso é bom para consultas individuais, mas ruim para cálculos. Anexe um PDF de síntese por mês se quiser que o LLM tenha uma visão geral.

Modelo

Qwen 3.5 9B (ou até em Q8, 11 GB) é muito sólido em números e leitura de tabelas em comparação com um modelo pequeno de 3B. Se você tiver uma RTX 4070 de 12 GB ou mais, é a escolha padrão aqui.

#Solução de problemas comuns

"Connection refused" ao iniciar

O daemon Ollama não está em execução. Verifique com "curl http://localhost:11434" — você deve ver "Ollama is running".

Respostas muito lentas

Ou Ollama está rodando na CPU (verifique com "ollama ps" — coluna PROCESSOR), ou seu context_window está alto demais. Reduza para 4096 para testar.

"Model not found"

O nome do modelo no arquivo settings-ollama.yaml deve corresponder exatamente a um modelo listado por "ollama list". Cuidado com as tags de quantização: qwen3.5:9b ≠ qwen3.5:9b-q8_0.

Embeddings diferentes entre a ingestão e a consulta

Se você trocar o modelo de embeddings depois de uma ingestão, deverá reindexar. Exclua local_data/private_gpt/qdrant/ e execute a ingestão novamente.

UI do Gradio inacessível

Se você estiver em uma máquina remota, execute com "PGPT_PROFILES=ollama python -m private_gpt" e reconfigure o host em settings.yaml (server.host: 0.0.0.0).

#Para se aprofundar

PrivateGPT v2 é um excelente ponto de partida para RAG documental local, mas é apenas um componente. Algumas sugestões para ir além:

RAG sem programar com Open WebUI ou AnythingLLM

Se o PrivateGPT parecer trabalhoso de instalar (Poetry, Python 3.11), o Open WebUI oferece uma experiência RAG comparável, mais simples de implantar com Docker.

Embeddings em francês eficientes

nomic-embed-text dá conta do recado, mas modelos especializados em francês, como Solon ou BGE-M3, oferecem resultados melhores com conteúdo jurídico ou administrativo francês.

Estratégias avançadas de chunking

O chunking por seção (cabeçalhos Markdown, estrutura DOCX) supera amplamente o chunking em blocos com um número fixo de tokens em corpus estruturados — um ganho de relevância fácil de obter.