RAG com ChromaDB e Mistral

#O que construímos: um RAG Mistral totalmente local

O RAG (geração aprimorada por recuperação) consiste em localizar os trechos dos seus documentos relacionados à pergunta e colá-los no prompt do modelo para que ele responda com base nesses trechos. O resultado esperado aqui é um pequeno utilitário de linha de comando: um script indexa uma pasta de documentos; um segundo lê uma pergunta, encontra os cinco trechos mais próximos no ChromaDB, os envia a um modelo Mistral via Ollama juntamente com a pergunta e exibe a resposta seguida dos arquivos consultados. Nada sai da máquina: Ollama fornece o modelo de geração e o modelo de embeddings, o ChromaDB armazena os vetores em uma pasta local.

O termo “Mistral” é usado em dois sentidos: os modelos de pesos abertos da Mistral AI, que você baixa e executa por conta própria (objeto deste guia), e as APIs hospedadas pela empresa, que enviam seus trechos para os servidores dela. Para documentos confidenciais, apenas o primeiro atende à exigência “100% local”.

#Qual modelo Mistral escolher para o RAG

Um RAG tem necessidades específicas: o modelo deve seguir uma instrução rigorosa (« responda apenas com base nos trechos »), ler vários trechos sem se perder e responder em francês. O tamanho importa menos do que na conversa livre; no entanto, a memória disponível para o contexto é mais importante. Os tamanhos abaixo são os exibidos pela biblioteca Ollama, com a quantização padrão.

A família Ministral 3 (3B, 8B e 14B) é publicada sob licença Apache 2.0, conforme indicado no anúncio do Mistral 3, e a página do Ollama a descreve como projetada para implantação na borda, capaz de rodar em uma ampla gama de equipamentos. Mistral Small 4, lançado em 2026 com 119 bilhões de parâmetros no total segundo o nome de sua ficha no Hugging Face, é voltado para hardware de servidor: não é um candidato para uma máquina pessoal. Para ter uma ideia da ordem de grandeza da memória necessária, a calculadora de VRAM do site fornece o tamanho do modelo mais o cache de contexto.

#Stack técnica

Geração

Um modelo Mistral servido por Ollama, via API HTTP local na porta 11434.

Embeddings

bge-m3 disponibilizado pelo Ollama: a página da biblioteca o descreve como um modelo da BAAI versátil, multilíngue e com múltiplas granularidades, de 567 milhões de parâmetros. Ele dispensa a instalação de PyTorch e sentence-transformers.

Base vetorial

ChromaDB em modo local (PersistentClient): uma pasta, nenhum servidor. O Chroma fornece um wrapper, OllamaEmbeddingFunction, que chama a API de embeddings do Ollama.

Leitura de arquivos

pypdf para PDFs que contêm texto, leitura direta para Markdown e texto simples. Um PDF escaneado é uma imagem: primeiro é necessário fazer o reconhecimento de caracteres.

#Preparar o ambiente

1. 01
   Instalar Ollama e baixar os modelos

   Instale o Ollama, depois baixe o modelo de geração e o modelo de embeddings com os dois comandos abaixo.
2. 02
   Criar o ambiente Python

   Python 3.10 ou superior. Um ambiente virtual mantém as dependências do projeto separadas.
3. 03
   Colocar os documentos

   Copie seus arquivos PDF, Markdown e texto para uma pasta docs/ ao lado dos scripts.

ollama pull ministral-3:8b
ollama pull bge-m3

mkdir mon-rag && cd mon-rag
python3 -m venv venv
source venv/bin/activate   # .\venv\Scripts\activate sous Windows
pip install chromadb pypdf requests

#2. Indexar os documentos no ChromaDB

O script lê cada arquivo, divide o texto em trechos de aproximadamente 1.800 caracteres, cortando entre parágrafos, e depois entrega esses trechos ao Chroma, que chama o bge-m3 via Ollama para calcular os vetores. Dois pontos são importantes: cada trecho mantém o nome do arquivo como metadado (para citar a fonte) e as adições são feitas em lotes, em vez de um trecho por vez.

from pathlib import Path
import chromadb
from chromadb.utils.embedding_functions.ollama_embedding_function import OllamaEmbeddingFunction
from pypdf import PdfReader

ef = OllamaEmbeddingFunction(url="http://localhost:11434", model_name="bge-m3")
coll = chromadb.PersistentClient(path="./chroma_db").get_or_create_collection("mes_docs", embedding_function=ef)

def lire(path: Path) -> str:
    if path.suffix.lower() == ".pdf":
        return "\n\n".join(p.extract_text() or "" for p in PdfReader(str(path)).pages)
    return path.read_text(encoding="utf-8", errors="ignore")

def decouper(texte: str, max_chars=1800):
    """Regroupe des paragraphes entiers jusqu'à max_chars ; un paragraphe trop long est coupé."""
    chunks, courant = [], ""
    for para in (p.strip() for p in texte.split("\n\n")):
        if not para:
            continue
        while len(para) > max_chars:
            if courant:
                chunks.append(courant); courant = ""
            chunks.append(para[:max_chars]); para = para[max_chars:]
        if len(courant) + len(para) + 2 > max_chars and courant:
            chunks.append(courant); courant = ""
        courant = (courant + "\n\n" + para).strip()
    if courant:
        chunks.append(courant)
    return chunks

n = 0
for path in sorted(Path("docs").rglob("*")):
    if path.suffix.lower() not in {".pdf", ".md", ".txt"}:
        continue
    chunks = decouper(lire(path))
    if not chunks:
        print(f"  ! {path.name} : aucun texte extrait (PDF scanné ?)")
        continue
    for i in range(0, len(chunks), 32):  # par lots de 32
        lot = chunks[i:i + 32]
        coll.upsert(
            ids=[f"{path.name}-{i + j}" for j in range(len(lot))],
            documents=lot,
            metadatas=[{"source": path.name}] * len(lot),
        )
    n += len(chunks)
    print(f"  + {path.name} : {len(chunks)} passages")
print(f"Terminé : {n} passages indexés")

O uso de upsert com identificadores construídos a partir do nome do arquivo e do número do trecho permite executar o script novamente: reindexar a mesma pasta atualiza os trechos em vez de duplicá-los. Atenção, porém: se um documento ficar mais curto, os trechos antigos excedentes permanecem na base; para uma alteração importante, exclua a pasta chroma_db e reindexe. A escolha do tamanho dos trechos é detalhada no guia sobre estratégias de chunking.

#3. Consultar: busca e depois geração

O segundo script incorpora a pergunta, recupera os cinco trechos mais próximos e compõe o prompt. A instrução é decisiva: ela pede que o modelo responda apenas com base nos trechos, admita quando faltar informação e cite o arquivo. O parâmetro num_ctx aumenta a janela de contexto: a documentação do Ollama indica que a janela padrão é de 4.096 tokens e que a variável OLLAMA_CONTEXT_LENGTH ou o parâmetro num_ctx a modificam. Com cinco trechos de 400 a 500 tokens, a instrução e a resposta, 4.096 tokens ficam no limite: um contexto muito curto é cortado silenciosamente, e o modelo responde sem ter lido o final dos seus trechos.

import sys, requests
import chromadb
from chromadb.utils.embedding_functions.ollama_embedding_function import OllamaEmbeddingFunction

MODELE = "ministral-3:8b"
ef = OllamaEmbeddingFunction(url="http://localhost:11434", model_name="bge-m3")
coll = chromadb.PersistentClient(path="./chroma_db").get_collection("mes_docs", embedding_function=ef)

SYSTEME = (
    "Tu réponds en français, uniquement à partir des passages fournis. "
    "Si la réponse n'y figure pas, dis-le clairement au lieu de deviner. "
    "Termine chaque affirmation par le nom du fichier source entre crochets."
)

def repondre(question: str, k: int = 5):
    res = coll.query(query_texts=[question], n_results=k)
    passages = list(zip(res["documents"][0], res["metadatas"][0]))
    contexte = "\n\n---\n\n".join(f"[{m['source']}]\n{p}" for p, m in passages)
    r = requests.post("http://localhost:11434/api/chat", json={
        "model": MODELE,
        "stream": False,
        "options": {"temperature": 0.2, "num_ctx": 8192},
        "messages": [
            {"role": "system", "content": SYSTEME},
            {"role": "user", "content": f"PASSAGES :\n{contexte}\n\nQUESTION : {question}"},
        ],
    }, timeout=300)
    r.raise_for_status()
    return r.json()["message"]["content"], sorted({m["source"] for _, m in passages})

if __name__ == "__main__":
    q = " ".join(sys.argv[1:]) or input("Question : ")
    reponse, sources = repondre(q)
    print("\n" + reponse)
    print("\nSources consultées :", ", ".join(sources))

python index.py
python ask.py "Quel est le délai de préavis prévu au contrat ?"

#Verificar o que o ChromaDB retorna antes de culpar o modelo

Quando uma resposta é ruim, a causa está em um de dois pontos: a busca não trouxe o trecho correto ou o modelo o usou mal. É possível distinguir os dois casos exibindo os trechos recuperados com suas respectivas distâncias, sem chamar o modelo. Se o trecho correto não estiver entre os cinco primeiros, mude a divisão do texto em trechos, adicione uma busca por palavras-chave ou um reranker. Se ele estiver presente e a resposta continuar errada, o problema está no prompt, no contexto truncado ou no modelo: experimente o modelo de tamanho superior antes de concluir.

import sys
import chromadb
from chromadb.utils.embedding_functions.ollama_embedding_function import OllamaEmbeddingFunction

ef = OllamaEmbeddingFunction(url="http://localhost:11434", model_name="bge-m3")
coll = chromadb.PersistentClient(path="./chroma_db").get_collection("mes_docs", embedding_function=ef)
res = coll.query(query_texts=[" ".join(sys.argv[1:])], n_results=8)
for doc, meta, dist in zip(res["documents"][0], res["metadatas"][0], res["distances"][0]):
    print(f"{dist:.3f}  {meta['source']}  {doc[:120]!r}")

#Orçamento de memória: o que deve caber ao mesmo tempo

O RAG faz dois modelos coexistirem, o que gera e o que calcula os vetores, além do cache de contexto do primeiro. O Ollama carrega cada modelo sob demanda e pode descarregar um para liberar espaço para o outro, o que acrescenta um atraso a cada troca se houver pouca memória disponível. A tabela apresenta uma ordem de grandeza para três configurações; o tamanho do modelo vem da biblioteca do Ollama, e o restante é um cálculo a refinar com a calculadora de VRAM do site.

#As armadilhas que levam a respostas que fogem da pergunta

O contexto padrão é muito curto

Veja mais acima: sem aumentar num_ctx, os últimos trechos são truncados. Sintoma típico: a resposta correta é de fato recuperada pelo ChromaDB, mas o modelo diz que não a encontra.

PDFs escaneados

pypdf lê apenas texto já presente. Um documento digitalizado retorna um resultado vazio: o script mostra isso. Primeiro, passe o documento por um OCR, descrito no guia sobre Tesseract.

Trechos sem contexto

Um trecho retirado de seu documento (« o prazo é de 30 dias ») não indica a que se refere. Acrescente o título do documento ou da seção ao início de cada trecho.

Pergunta sem resposta nos documentos

Sem a instrução « diga claramente », um modelo preenche o vazio com o que sabe. Sempre teste uma pergunta cuja resposta não está em seus arquivos.

Identificadores e termos exatos

Um número de contrato ou de processo não é bem recuperado pelos embeddings: adicione uma busca por palavras-chave, como descrito no guia sobre busca híbrida.

#Para se aprofundar

Cada melhoria tem seu próprio guia: meça o recall em 30 a 50 perguntas reais antes e depois, em vez de acumular técnicas. Se você prefere uma interface pronta sem escrever código, o guia de RAG sem código apresenta Open WebUI e AnythingLLM.

#Perguntas frequentes sobre RAG com Mistral

• RAG local com ChromaDB e Ollama: tutorial em Python
• Estratégias de chunking
• Busca híbrida BM25 + vetorial
• Adicionar um reranker ao seu pipeline
• Calculadora de VRAM
• RAG local com Ollama sem programar

• Fonte: Ollama, ministral-3
• Fonte: Ollama, mistral-small3.2
• Fonte: Ollama, bge-m3
• Fonte: Chroma, embeddings Ollama
• Fonte: FAQ Ollama, janela de contexto