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

Configurar e controlar resultados da Web

Aula 6 de 20 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Configurar e controlar resultados da Web
  2. O parâmetro search_context_size
  3. Orientar consultas de pesquisa através do prompt
  4. Extrair e estruturar citações
  5. Padrão: pesquisa com validação cruzada
  6. Gerir a ausência de resultados
  7. Pesquisa na Web com streaming
  8. Filtrar domínios e listar fontes
  9. Pontos-chave

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 tipo input_text e a pesquisa na Web utiliza a ferramenta web_search (web_search_preview é agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados através das funções fichiers_generes e telecharger da 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.

TamanhoTokens de contextoLatênciaCustoUtilização
lowMínimoRápidaBaixoFactos simples, valores
mediumModeradoPadrãoMédioResumos, comparações
highMáximoMais lentaElevadoAná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_size controla o volume de dados da Web injetados
  • filters restringe ou exclui domínios (máx. 100); include lista todas as fontes consultadas
  • O prompt do sistema orienta o modelo para as fontes certas
  • Extraia as anotações url_citation para rastrear as fontes
  • Implemente validação cruzada para informações críticas
  • Trate a ausência de resultados com reformulação automática