Prompting aumentado por recuperação
Nesta página
Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_psó são aceites com um esforço de raciocínio denone, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(API de Respostas) oureasoning_effort="none"(Chat Completions). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.
Prompting aumentado por recuperação
O Prompting Aumentado por Recuperação (RAP) combina a pesquisa de documentos com o prompting para fornecer ao modelo um contexto relevante e atualizado. É a evolução natural do grounding: em vez de injetar manualmente o contexto, automatiza a pesquisa de passagens relevantes antes de cada chamada ao LLM.
A diferença torna-se óbvia à escala. Colar manualmente três parágrafos úteis da sua documentação funciona para uma demonstração; mas assim que a sua base documental atinge algumas centenas de páginas e as perguntas chegam continuamente, ninguém sabe já quais as passagens a colar. O RAP delega esta escolha a um componente automático, chamado antes de cada geração, cujo único papel é encontrar o que colocar no prompt.
Arquitetura de um sistema RAP
Um pipeline RAP divide-se em três passos que operam a velocidades e custos diferentes. A indexação transforma os seus documentos em embeddings vetoriais; isto acontece uma vez, offline, convertendo cada documento num vetor numérico que codifica o seu significado, armazenado juntamente com o texto original. A recuperação, pelo contrário, executa em cada pergunta: transforma a pergunta num vetor usando o mesmo modelo de embedding e depois procura os vetores de documentos mais próximos. Finalmente, o aumento é apenas um prompting padrão — constrói um prompt de sistema contendo as passagens recuperadas e instrui o modelo a não sair desse âmbito.
Lembre-se desta divisão: tudo o que é dispendioso acontece durante a indexação, onde pode dar-se ao luxo de ser exigente, enquanto tudo o que se repete para cada pergunta deve permanecer rápido. O código abaixo implementa os dois primeiros passos usando a similaridade do cosseno como medida de proximidade.
from openai import OpenAI
import numpy as np
client = OpenAI()
# Step 1: Generate document embeddings
def embed_texts(texts: list[str]) -> list[list[float]]:
"""Generates embeddings for a list of texts."""
response = client.embeddings.create(
model="text-embedding-3-large",
input=texts
)
return [item.embedding for item in response.data]
# Step 2: Search by cosine similarity
def cosine_similarity(a: list[float], b: list[float]) -> float:
"""Calculates cosine similarity between two vectors."""
a, b = np.array(a), np.array(b)
return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
def retrieve(query: str, documents: list[str],
doc_embeddings: list[list[float]],
top_k: int = 3) -> list[str]:
"""Returns the top_k most relevant documents."""
query_emb = embed_texts([query])[0]
scores = [
(i, cosine_similarity(query_emb, doc_emb))
for i, doc_emb in enumerate(doc_embeddings)
]
scores.sort(key=lambda x: x[1], reverse=True)
return [documents[i] for i, _ in scores[:top_k]]
Pipeline completo
A montagem destes blocos de construção resulta numa classe que cabe em cerca de trinta linhas. A maioria das decisões ocorre no prompt de sistema gerado, e vale a pena lê-lo linha por linha. O modelo recebe primeiro a ordem de responder APENAS com base nas passagens fornecidas, o que limita as respostas alucinadas quando a documentação é omissa. Recebe depois a instrução de citar o número da passagem para cada afirmação, e é isto que torna a verificação possível: um revisor pode rastrear a fonte num instante. Uma temperature de 0,1 completa a configuração — numa resposta ancorada em documentos, a criatividade é um erro.
class RAGPipeline:
"""Minimalist RAP pipeline."""
def __init__(self, documents: list[str]):
self.documents = documents
self.embeddings = embed_texts(documents)
def query(self, question: str, top_k: int = 3) -> str:
"""Answers a question based on the documents."""
# Retrieval
relevant_docs = retrieve(
question, self.documents,
self.embeddings, top_k
)
# Prompt augmentation
context = "\n\n---\n\n".join(
f"[Passage {i+1}]\n{doc}"
for i, doc in enumerate(relevant_docs)
)
system = f"""You are a technical assistant.
Answer ONLY based on the provided passages.
If the passages do not contain the answer, say so.
Cite the passage number for every claim.
RELEVANT PASSAGES:
{context}"""
# Generation
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
instructions=system,
input=question,
temperature=0.1
)
return response.output_text
Fragmentação: divisão de documentos
Dividir documentos em fragmentos (chunks) é crucial para a qualidade da recuperação. Se os fragmentos forem demasiado grandes, afogam a informação relevante; se forem demasiado pequenos, perdem o contexto. Um manual de API dividido em blocos de dez páginas devolverá sempre o mesmo bloco genérico, independentemente da pergunta feita. Dividido em frases isoladas, devolverá uma frase que começa por “este método” sem que o modelo saiba a qual método se refere. A sobreposição mitiga especificamente este risco: cada fragmento repete o fim do anterior, pelo que a informação que atravessa um limite permanece legível de pelo menos um dos lados.
Quando os seus documentos têm uma estrutura de cabeçalhos, a fragmentação baseada em secções é quase sempre superior à fragmentação de tamanho fixo: uma secção “Autenticação” permanece intacta, com a sua introdução e exemplos.
def chunk_document(text: str, chunk_size: int = 500,
overlap: int = 50) -> list[str]:
"""Splits text into chunks with overlap."""
words = text.split()
chunks = []
for i in range(0, len(words), chunk_size - overlap):
chunk = " ".join(words[i:i + chunk_size])
if chunk.strip():
chunks.append(chunk)
return chunks
def chunk_by_sections(text: str) -> list[str]:
"""Splits by sections (Markdown headings)."""
sections = []
current = []
for line in text.split("\n"):
if line.startswith("## ") and current:
sections.append("\n".join(current))
current = [line]
else:
current.append(line)
if current:
sections.append("\n".join(current))
return sections
Estratégias avançadas de recuperação
Reordenação (Reranking)
Após a recuperação inicial, utilize o LLM para reordenar os resultados. A lógica é a de um funil: a pesquisa vetorial é rápida mas aproximada, trazendo uma dúzia de candidatos plausíveis; o modelo, mais lento mas mais nuances, relê estes candidatos conhecendo a pergunta e classifica-os. Mantém então apenas o topo da lista para a geração. O ganho é mais visível em perguntas onde várias passagens falam do mesmo tópico, mas apenas uma responde efetivamente — três secções mencionam a palavra “quota”, mas apenas uma explica como aumentá-la.
def rerank(question: str, passages: list[str]) -> list[str]:
"""Reorders passages by relevance using the LLM."""
prompt = f"""Question: {question}
Here are candidate passages. Rank them from most relevant
to least relevant for answering the question.
Return only the numbers in order (e.g., 3, 1, 2).
{chr(10).join(f"[{i+1}] {p[:200]}" for i, p in enumerate(passages))}"""
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input=prompt,
temperature=0.0
)
# Parse returned order and reorganize
return response.output_text
Incorporação de Documentos Hipotéticos (HyDE)
Gere um documento hipotético ideal e depois procure documentos semelhantes. O problema que esta técnica resolve é a incompatibilidade de vocabulário: uma pergunta feita em linguagem corrente não se assemelha, vetorialmente, a um parágrafo de documentação técnica. Ao pedir primeiro ao modelo que escreva a resposta que imagina, obtém um texto escrito no registo dos seus documentos, e é este texto que utiliza como consulta. Não importa se o parágrafo hipotético contém aproximações: nunca serve de resposta, apenas como sonda.
def hyde_retrieve(question: str, documents: list[str],
doc_embeddings: list[list[float]]) -> list[str]:
"""Retrieval via HyDE."""
# Generate a hypothetical passage
hypo_response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input=f"Write a short technical paragraph that would perfectly "
f"answer this question: {question}",
temperature=0.5
)
hypothetical_doc = hypo_response.output_text
# Search for documents similar to the hypothetical passage
return retrieve(hypothetical_doc, documents,
doc_embeddings, top_k=3)
Utilizar a Pesquisa de Ficheiros nativa da OpenAI
Para uma implementação rápida, a API oferece recuperação integrada. Carrega o ficheiro, cria um arquivo vetorial, anexa o ficheiro ao mesmo e declara a ferramenta file_search na chamada: a fragmentação, a incorporação e a pesquisa são tratadas no lado do servidor. Esta é a escolha certa quando os seus documentos são standard e não lhe importa onde vivem os dados. O pipeline caseiro mantém a vantagem assim que precisar de dominar a fragmentação, alojar o índice você mesmo ou ligar uma reordenação específica.
# Upload file
file = client.files.create(
file=open("documentation.pdf", "rb"),
purpose="assistants"
)
# Create a vector store
vector_store = client.vector_stores.create(
name="Technical Documentation"
)
client.vector_stores.files.create(
vector_store_id=vector_store.id,
file_id=file.id
)
# Query with File Search
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Answer based on the provided documentation.",
input="How do I configure authentication?",
tools=[{
"type": "file_search",
"vector_store_ids": [vector_store.id]
}]
)
Estabelecer uma linha de base
Pegue em cinco a dez páginas de documentação técnica e implemente o pipeline completo, desde a fragmentação até à geração. Escreva dez perguntas cujas respostas estejam nos documentos, execute o pipeline em cada uma e repita com a reordenação ativada: é ao observar em quais perguntas a classificação muda que compreende o que a pesquisa vetorial por si só perde. Termine medindo a percentagem de respostas corretamente ancoradas, aquelas em que cada afirmação se refere efetivamente a uma passagem fornecida. Este valor é o seu ponto de partida; todas as otimizações subsequentes serão julgadas em relação a ele, e não à impressão deixada por duas ou três respostas lidas aleatoriamente.
Pontos-chave
- O RAP automatiza a injeção de contexto relevante no prompt
- A fragmentação é crítica: experimente diferentes tamanhos
- A reordenação com o LLM melhora significativamente a relevância
- O HyDE é útil quando a pergunta difere muito do vocabulário dos documentos
- A Pesquisa de Ficheiros da OpenAI simplifica a implementação para casos standard