Configurar e controlar resultados da Web
Nesta página
Lição atualizada em 2 de novembro de 2026 com base na documentação da OpenAI: a ferramenta Code Interpreter requer um parâmetro
container(adicionado a todos os exemplos), as partes de texto de entrada são do tipoinput_texte a pesquisa na Web utiliza a ferramentaweb_search(web_search_previewé agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados através das funçõesfichiers_generesetelechargerda Lição 10. Fontes: Code Interpreter · Web search.
Configurar e controlar resultados da Web
Ativar a Pesquisa na Web requer apenas uma linha; obter respostas fiáveis exige três definições que esta lição detalha. A primeira decide quanto conteúdo da Web é injetado no contexto, impactando diretamente a sua fatura. A segunda orienta as consultas que o próprio modelo formula — porque é ele que as escreve, não você. A terceira diz respeito às citações; sem elas, uma resposta fundamentada é apenas uma afirmação categórica.
O parâmetro search_context_size
O parâmetro search_context_size controla a quantidade de conteúdo da Web injetada no contexto do modelo. Não altera o número de pesquisas nem a sua qualidade: determina quanto texto, uma vez encontradas as páginas, entra efetivamente no prompt. Trata-se de um compromisso entre exaustividade e custo, que deve ajustar conforme o tipo de tarefa, e não definir uma vez por todas.
from openai import OpenAI
client = OpenAI()
# Contexto mínimo: respostas rápidas e concisas
response = client.responses.create(
model="gpt-5.6-terra",
input="What is France's GDP in 2025?",
tools=[{
"type": "web_search",
"search_context_size": "low"
}]
)
# Contexto médio: bom compromisso (padrão)
response = client.responses.create(
model="gpt-5.6-terra",
input="Summarize AI market trends in Europe",
tools=[{
"type": "web_search",
"search_context_size": "medium"
}]
)
# Contexto amplo: análise aprofundada
response = client.responses.create(
model="gpt-5.6-terra",
input="Compare AI strategies in France, Germany, and the Netherlands",
tools=[{
"type": "web_search",
"search_context_size": "high"
}]
)
Impacto nos custos e na latência
A regra é simples: aumente o nível apenas quando a resposta obtida o tiver concretamente dececionado. Uma data, um valor ou uma confirmação factual não precisam de mais do que low; usar high para isso é como pagar por um dossiê completo para ler uma única linha.
| Tamanho | Tokens de contexto | Latência | Custo | Utilização |
|---|---|---|---|---|
low | Mínimo | Rápida | Baixo | Factos simples, valores |
medium | Moderado | Padrão | Médio | Resumos, comparações |
high | Máximo | Mais lenta | Elevado | Análise aprofundada |
Orientar consultas de pesquisa através do prompt
Eis o ponto que a maioria descobre tarde demais: o modelo formula as suas próprias consultas de pesquisa. Você escreve «quais são as recentes alterações regulamentares?» e ele traduz isso em palavras-chave que nunca vê. A qualidade dos resultados depende, portanto, de uma reformulação sobre a qual tem apenas controlo indireto — o prompt do sistema. Nomeie as fontes权威 no seu setor e o período que lhe interessa: é isso que mais faz a diferença.
response = client.responses.create(
model="gpt-5.6-terra",
instructions=(
"You are a market analyst specializing in European technology. "
"When you perform web searches, prioritize institutional sources "
"(European Commission, INSEE, Eurostat) and specialized media "
"(Les Echos, La Tribune, TechCrunch). "
"Ignore personal blogs and forums."
),
input="What is the state of AI startup funding in France?",
tools=[{
"type": "web_search",
"search_context_size": "high"
}]
)
Extrair e estruturar citações
As citações chegam como anotações anexadas à resposta, não no próprio texto. Esta separação é uma boa notícia: permite-lhe apresentar as fontes como quiser, verificá-las ou rejeitar uma resposta que não tenha nenhuma. Em qualquer aplicação onde a resposta tenha peso — jurídico, médico, financeiro — tratar anotações em falta como um erro é mais seguro do que confiar no texto.
def extract_sources(response) -> list[dict]:
"""Extract all URL citations from a Web Search response."""
sources = []
for item in response.output:
if item.type == "message":
for block in item.content:
if hasattr(block, "annotations"):
for ann in block.annotations:
if ann.type == "url_citation":
sources.append({
"url": ann.url,
"title": ann.title,
"excerpt_start": ann.start_index,
"excerpt_end": ann.end_index
})
return sources
# Usage
response = client.responses.create(
model="gpt-5.6-terra",
input="What are the new GDPR rules for AI in 2026?",
tools=[{"type": "web_search"}]
)
sources = extract_sources(response)
for s in sources:
print(f" {s['title']}: {s['url']}")
Padrão: pesquisa com validação cruzada
Uma única fonte continua a ser uma única fonte, mesmo que um modelo a tenha encontrado. Para informações que orientam uma decisão, peça explicitamente confirmação a partir de múltiplas fontes independentes e faça com que o modelo sinalize divergências em vez de as arbitrar silenciosamente: um desacordo entre duas fontes é, em si mesmo, uma informação, muitas vezes mais útil do que fazer a média das duas.
def validated_search(question: str, min_sources: int = 3) -> dict:
"""Web search requiring multiple sources."""
response = client.responses.create(
model="gpt-5.6-terra",
instructions=(
f"To answer this question, you must find at least "
f"{min_sources} independent sources that confirm the information. "
"If sources contradict each other, flag the discrepancies. "
"Cite each source explicitly."
),
input=question,
tools=[{
"type": "web_search",
"search_context_size": "high"
}]
)
sources = extract_sources(response)
return {
"answer": response.output_text,
"sources": sources,
"reliability": "high" if len(sources) >= min_sources else "verify"
}
Gerir a ausência de resultados
Há um caso que as pessoas esquecem de tratar: a pesquisa não devolve nada. O risco não é a falta de resposta — é que, na ausência de resultados, o modelo responda com base no seu conhecimento interno sem o sinalizar, fornecendo-lhe informações plausíveis mas desatualizadas. Peça-lhe que o diga explicitamente e planeie uma reformulação.
def search_with_fallback(question: str) -> dict:
"""Web search with failure detection and reformulation."""
# First attempt
response = client.responses.create(
model="gpt-5.6-terra",
input=question,
tools=[{"type": "web_search"}]
)
sources = extract_sources(response)
if len(sources) == 0:
# Automatic reformulation
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Rephrase this question for a more effective web search, "
f"then search: {question}",
tools=[{"type": "web_search", "search_context_size": "high"}]
)
sources = extract_sources(response)
return {
"answer": response.output_text,
"sources": sources
}
Pesquisa na Web com streaming
Uma pesquisa na Web demora alguns segundos, por vezes mais se o modelo encadear várias consultas. Com o streaming, o utilizador vê a resposta a construir-se em vez de ficar a olhar para um indicador de carregamento — e para este tipo de latência, a diferença de perceção é enorme por um custo de implementação quase nulo.
stream = client.responses.create(
model="gpt-5.6-terra",
input="What are this week's tech news headlines?",
tools=[{"type": "web_search"}],
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
# Extract sources at the end
sources = extract_sources(event.response)
print(f"\n\n--- {len(sources)} sources consulted ---")
Filtrar domínios e listar fontes
A ferramenta web_search aceita um parâmetro filters que restringe a pesquisa a uma lista de domínios permitidos (até 100) ou exclui uma lista (também até 100). Escreva os domínios sem http:// nem https://. A filtragem existe apenas com web_search na API de Respostas: a ferramenta legada web_search_preview ignora-a.
response = client.responses.create(
model="gpt-5.6-terra",
tools=[{
"type": "web_search",
"filters": {"allowed_domains": ["service-public.fr", "legifrance.gouv.fr"]},
}],
include=["web_search_call.action.sources"],
input="What are the price display requirements for retail stores in France?",
)
print(response.output_text)
A opção include=["web_search_call.action.sources"] devolve a lista completa de URLs consultadas, muitas vezes mais longa do que a lista de citações. As próprias citações chegam como anotações url_citation (URL, título, posição no texto): a documentação da OpenAI solicita que as apresente de forma visível e clicável na sua interface.
Pontos-chave
search_context_sizecontrola o volume de dados da Web injetadosfiltersrestringe ou exclui domínios (máx. 100);includelista todas as fontes consultadas- O prompt do sistema orienta o modelo para as fontes certas
- Extraia as anotações
url_citationpara rastrear as fontes - Implemente validação cruzada para informações críticas
- Trate a ausência de resultados com reformulação automática