Arquitetura RAG Completa
Nesta página
Lição atualizada a 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_papenas são aceites com um esforço de raciocínio denone, ao passo que os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(Respostas da API) oureasoning_effort="none"(Completamentos de Chat). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.
Objetivos
- Compreender a arquitetura RAG de ponta a ponta
- Implementar um pipeline RAG funcional
- Identificar componentes a otimizar
O que é o RAG?
O RAG (Retrieval-Augmented Generation — Geração Aumentada por Recuperação) combina a pesquisa de documentos com a geração de texto por um LLM. Em vez de depender exclusivamente do seu conhecimento interno, o modelo recebe documentos relevantes como contexto e elabora a sua resposta com base nesse contexto. Tudo o que construiu desde o início deste curso — incorporações (embeddings), indexação, pesquisa e avaliação — torna-se aqui a metade inicial de um sistema completo.
Porquê o RAG?
Quatro razões o justificam, e elas acumulam-se. Primeiro, dados proprietários: a sua política de trabalho remoto, os procedimentos internos e o catálogo de produtos nunca fizeram parte dos dados de treino do modelo, e nenhum prompt os fará aparecer lá. Segundo, informação recente: tudo o que seja posterior à data de treino é invisível para o modelo, ao passo que um índice se atualiza no próprio dia. A verificabilidade é igualmente crucial, pois cada resposta está ancorada em fontes identificáveis que o utilizador pode abrir e verificar — transformando a natureza da confiança depositada no sistema. Por fim, o custo joga a seu favor: adicionar conhecimento via RAG custa muito menos do que o ajuste fino (fine-tuning), e as correções fazem-se eliminando um documento em vez de retreinar um modelo.
Fases do Pipeline
Leia o RAG em duas fases distintas que não deve confundir. A ingestão ocorre offline, uma vez por todas ou sempre que o corpus seja atualizado:
Documentos → Fragmentação → Incorporações → Armazenamento Vetorial
A consulta ocorre online, para cada pergunta feita, e deve permanecer rápida:
Pergunta → Incorporação → Pesquisa → Contexto + Pergunta → LLM → Resposta
Esta separação tem uma consequência prática: os custos de ingestão pagam-se uma única vez e podem ser elevados, enquanto os custos de consulta se pagam por chamada e ditam a experiência do utilizador. Pode, portanto, permitir-se um processamento de ingestão sofisticado, mas deve manter-se enxuto no lado da consulta.
Implementação Completa
A classe seguinte materializa as três fases em três métodos distintos, mais um quarto que os encadeia. Esta separação não é cosmética: permite-lhe testar a pesquisa sem consumir tokens de geração e reproduzir a geração num contexto fixo para comparar dois prompts.
from openai import OpenAI
import numpy as np
client = OpenAI()
class PipelineRAG:
def __init__(
self,
model_embedding: str = "text-embedding-3-large",
model_generation: str = "gpt-5.6-terra"
):
self.client = OpenAI()
self.model_embedding = model_embedding
self.model_generation = model_generation
self.chunks: list[dict] = []
self.embeddings: np.ndarray | None = None
# --- Fase de Ingestão ---
def ingest(self, documents: list[dict]):
"""Ingerir documentos {id, text, metadata}."""
self.chunks = documents
texts = [d["text"] for d in documents]
# Gerar incorporações em lotes
all_emb = []
for i in range(0, len(texts), 100):
batch = texts[i:i + 100]
resp = self.client.embeddings.create(
input=batch, model=self.model_embedding
)
batch_emb = sorted(resp.data, key=lambda x: x.index)
all_emb.extend([e.embedding for e in batch_emb])
self.embeddings = np.array(all_emb, dtype=np.float32)
print(f"Ingestão concluída: {len(self.chunks)} fragmentos indexados")
# --- Fase de Recuperação ---
def search(self, question: str, k: int = 5) -> list[dict]:
"""Encontrar os k fragmentos mais relevantes."""
query_emb = self.client.embeddings.create(
input=question, model=self.model_embedding
).data[0].embedding
scores = self.embeddings @ np.array(query_emb)
top_k = np.argsort(scores)[-k:][::-1]
return [
{**self.chunks[i], "score": float(scores[i])}
for i in top_k
]
# --- Fase de Geração ---
def generate(self, question: str, contexts: list[dict]) -> str:
"""Gerar uma resposta com base nos contextos recuperados."""
# Construir o prompt
formatted_context = "\n\n---\n\n".join(
f"[Source: {c.get('id', 'unknown')}]\n{c['text']}"
for c in contexts
)
messages = [
{
"role": "system",
"content": (
"You are an assistant that answers questions "
"based solely on the provided documents. "
"If the information is not in the documents, "
"state this clearly. Cite your sources."
)
},
{
"role": "user",
"content": (
f"Reference documents:\n\n{formatted_context}\n\n"
f"---\n\nQuestion: {question}"
)
}
]
response = self.client.chat.completions.create(
model=self.model_generation,
reasoning_effort="none", # temperature requires effort none
messages=messages,
temperature=0.2
)
return response.choices[0].message.content
# --- Pipeline Completo ---
def answer(self, question: str, k: int = 5) -> dict:
"""Pipeline RAG completo: pesquisa → geração."""
contexts = self.search(question, k=k)
response = self.generate(question, contexts)
return {
"question": question,
"response": response,
"sources": [
{"id": c["id"], "score": c["score"],
"excerpt": c["text"][:150]}
for c in contexts
]
}
Três detalhes na fase de geração determinam a maior parte da qualidade. A mensagem de sistema exige responder apenas com base nos documentos fornecidos e admitir quando falta informação: sem esta instrução, o modelo preencherá as lacunas com o seu conhecimento geral, produzindo uma resposta plausível mas inventada. O prefixo [Source: id] antes de cada excerto dá ao modelo algo específico para citar, em vez de um vago “de acordo com os documentos”. Por fim, uma temperature de 0,2 reduz a variabilidade: para perguntas factuais contra uma base documental, quer consistência, não criatividade.
Utilização
Vamos testar o pipeline num caso de negócio mínimo — três políticas internas e uma pergunta que não copia nenhuma das suas formulações exatas.
# Preparar documentos
documents = [
{
"id": "leave-policy",
"text": "Employees receive 25 days of paid leave "
"per year. Leave must be requested at least 2 weeks "
"in advance via the HR portal.",
"metadata": {"type": "hr", "date": "2026-01"}
},
{
"id": "remote-work-policy",
"text": "Remote work is authorized up to 3 days per week. "
"Tuesdays and Thursdays are mandatory office days. "
"Written agreement with the manager is required.",
"metadata": {"type": "hr", "date": "2026-01"}
},
{
"id": "reimbursement-procedure",
"text": "Expense reports must be submitted within 30 days "
"of the expense. Attach the original receipt. "
"Validation by the direct supervisor required for amounts over 200 euros.",
"metadata": {"type": "finance", "date": "2026-01"}
},
]
# Criar o pipeline
rag = PipelineRAG()
rag.ingest(documents)
# Fazer uma pergunta
result = rag.answer("How many days of remote work per week?")
print(result["response"])
print("\nSources used:")
for s in result["sources"]:
print(f" [{s['score']:.3f}] {s['id']}: {s['excerpt']}")
Leve o exercício mais longe fazendo uma pergunta que nenhum documento responda, como uma sobre o plano de saúde da empresa. O pipeline devolverá ainda assim três fontes — a pesquisa devolve sempre os seus k melhores candidatos — e é a mensagem de sistema que deve impedir o modelo de inventar uma resposta. Verificar este comportamento antes da produção é preferível a descobri-lo através de uma reclamação.
Pontos de Otimização
Cada etapa do pipeline pode ser melhorada independentemente, permitindo avanços através de pequenos ajustes mensuráveis.
| Etapa | Otimizações Possíveis |
|---|---|
| Fragmentação | Tamanho do fragmento, sobreposição, fragmentação semântica |
| Incorporação | Escolha do modelo, dimensões, enriquecimento de texto |
| Pesquisa | Híbrida, reordenamento (reranking), filtros de metadados |
| Prompt | Instruções de sistema, formato do contexto, few-shot |
| Geração | Modelo, temperatura, citações |
As lições seguintes detalham cada uma destas otimizações. Aborde-as nesta ordem: a fragmentação determina o que pode ser recuperado, e nenhum reordenamento corrigirá um documento mal fragmentado.
Pontos-chave
- RAG = Pesquisa + Contexto + Geração LLM
- O pipeline divide-se em ingestão (offline) e consulta (online)
- Cada componente (fragmentação, incorporação, pesquisa, prompt, geração) pode ser otimizado independentemente
- O RAG é mais flexível e menos dispendioso do que o ajuste fino para adicionar conhecimento