Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Arquitetura RAG Completa

Aula 11 de 22 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Objetivos
  2. O que é o RAG?
  3. Fases do Pipeline
  4. Implementação Completa
  5. Utilização
  6. Pontos de Otimização
  7. Pontos-chave

Lição atualizada a 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p apenas são aceites com um esforço de raciocínio de none, ao passo que os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (Respostas da API) ou reasoning_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.

EtapaOtimizações Possíveis
FragmentaçãoTamanho do fragmento, sobreposição, fragmentação semântica
IncorporaçãoEscolha do modelo, dimensões, enriquecimento de texto
PesquisaHíbrida, reordenamento (reranking), filtros de metadados
PromptInstruções de sistema, formato do contexto, few-shot
GeraçãoModelo, 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