Índice

TL;DR: A integração da pesquisa na web com a API OpenAI permite que os modelos de linguagem acessem informações atualizadas da internet para gerar respostas mais precisas e relevantes. O artigo apresenta uma implementação detalhada desta funcionalidade, incluindo configurações, personalizações e considerações importantes para diferentes casos de uso.

Takeaways:

A pesquisa na web é habilitada através do parâmetro “tools” nas requisições à API, possibilitando consultas que necessitam de dados recentes ou específicos.
É possível personalizar os resultados com base na localização geográfica do usuário, usando parâmetros como país, cidade e região.
O parâmetro “search_context_size” (high, medium, low) permite equilibrar custo, qualidade e latência na recuperação de informações.
As respostas incluem citações com URLs, que devem ser apresentadas de forma clara e clicável na interface do usuário.
Existem limitações importantes, como incompatibilidade com certos modelos e considerações sobre privacidade e segurança ao implementar essa funcionalidade.

Dominando a Integração da Pesquisa na Web com a API OpenAI: Um Guia Completo

Você já imaginou como seria ter suas aplicações de IA acessando informações atualizadas da internet em tempo real? A integração da pesquisa na web com a API OpenAI representa um avanço significativo na forma como os modelos de linguagem podem interagir com o mundo exterior, fornecendo respostas mais precisas e atualizadas. Neste artigo, vamos explorar detalhadamente como implementar essa funcionalidade poderosa em seus projetos.

Como Habilitar a Pesquisa na Web em Suas Aplicações

A funcionalidade de pesquisa na web permite que os modelos da OpenAI acessem informações atualizadas da internet antes de gerar uma resposta. Essa capacidade é fundamental para consultas que exigem dados recentes ou específicos que podem não estar presentes no conhecimento base do modelo.

Para habilitar essa funcionalidade, você precisa configurar a propriedade tools em sua requisição à API. O modelo então decidirá, com base no conteúdo do prompt, se deve ou não utilizar a pesquisa na web para enriquecer sua resposta.

Veja como implementar isso em diferentes linguagens:

JavaScript

import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
  model: "gpt-4.1",
  tools: [
    {
      type: "web_search_preview"
    }
  ],
  input: "What was a positive news story from today?",
});
console.log(response.output_text);

Python

from openai import OpenAI
client = OpenAI()
response = client.responses.create(
  model="gpt-4.1",
  tools=[{"type": "web_search_preview"}],
  input="What was a positive news story from today?"
)
print(response.output_text)

cURL

curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{ "model": "gpt-4.1", "tools": [{"type": "web_search_preview"}], "input": "what was a positive news story from today?" }'

Entendendo as Versões da Ferramenta de Pesquisa na Web

A ferramenta de pesquisa na web está em constante evolução, com diferentes versões disponíveis. Atualmente, a versão padrão é web_search_preview, que na verdade aponta para uma versão datada específica, como web_search_preview_2025_03_11.

Para garantir menor latência e resultados mais consistentes, você pode forçar o uso de uma versão específica utilizando o parâmetro tool_choice. Isso é particularmente útil em ambientes de produção onde a previsibilidade é crucial.

É importante verificar regularmente a documentação da API para se manter atualizado sobre as versões mais recentes e suas funcionalidades específicas.

Interpretando a Saída e Trabalhando com Citações

Quando um modelo utiliza a pesquisa na web para formular uma resposta, a saída incluirá dois elementos principais:

Um item web_search_call contendo o ID da chamada de pesquisa
Um item message contendo o texto resultante e anotações para as URLs citadas

Veja um exemplo simplificado da estrutura de resposta:

[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed"
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

Por padrão, a resposta incluirá citações inline para as URLs encontradas nos resultados da pesquisa. Essas citações devem ser apresentadas de forma clara e clicável na interface do usuário, permitindo que os usuários acessem facilmente as fontes originais.

Personalizando a Localização do Usuário para Resultados Mais Relevantes

Um aspecto poderoso da pesquisa na web é a capacidade de personalizar os resultados com base na localização geográfica do usuário. Isso é especialmente útil para consultas relacionadas a eventos locais, restaurantes, clima ou qualquer informação que varie geograficamente.

Para implementar essa personalização, você pode especificar a localização aproximada do usuário usando os seguintes parâmetros:

country: código ISO de duas letras (ex: “BR” para Brasil)
city: string de texto livre (ex: “São Paulo”)
region: string de texto livre (ex: “SP”)
timezone: fuso horário IANA (ex: “America/Sao_Paulo”)

Veja um exemplo de implementação em Python:

from openai import OpenAI
client = OpenAI()
response = client.responses.create(
  model="gpt-4.1",
  tools=[{
    "type": "web_search_preview",
    "user_location": {
      "type": "approximate",
      "country": "BR",
      "city": "São Paulo",
      "region": "SP"
    }
  }],
  input:"Quais são os melhores restaurantes no Jardins?",
)
print(response.output_text)

Otimizando o Tamanho do Contexto de Pesquisa

O parâmetro search_context_size é uma ferramenta poderosa para controlar a quantidade de contexto recuperado da web. Este parâmetro afeta diretamente três aspectos importantes:

Custo: contextos maiores geralmente custam mais
Qualidade: contextos maiores podem fornecer respostas mais detalhadas
Latência: contextos maiores aumentam o tempo de processamento

Os valores disponíveis para este parâmetro são:

high: maior contexto, maior custo, potencialmente maior qualidade
medium: configuração padrão, equilibrando custo e qualidade
low: menor contexto, menor custo, menor latência

É importante notar que os tokens usados pela ferramenta de pesquisa não afetam a janela de contexto do modelo principal. Isso significa que você pode usar a pesquisa na web sem se preocupar com limitações de contexto do modelo.

from openai import OpenAI
client = OpenAI()
response = client.responses.create(
  model="gpt-4.1",
  tools=[{
    "type": "web_search_preview",
    "search_context_size": "low",
  }],
  input:"Qual filme ganhou o Oscar de melhor filme em 2025?",
)
print(response.output_text)

Limitações e Considerações Importantes

Ao implementar a pesquisa na web em suas aplicações, é importante estar ciente das seguintes limitações:

A funcionalidade não é suportada no modelo gpt-4.1-nano
Os modelos gpt-4o-search-preview e gpt-4o-mini-search-preview suportam apenas um subconjunto de parâmetros da API
A pesquisa na web está sujeita aos mesmos limites de taxa dos modelos quando usada na API Responses
A janela de contexto é limitada a 128000 tokens

Além disso, é fundamental considerar as implicações de privacidade e segurança ao implementar essa funcionalidade, especialmente em aplicações que lidam com dados sensíveis.

Implementando uma Estratégia Eficaz de Pesquisa na Web

Para maximizar os benefícios da integração da pesquisa na web com a API OpenAI, considere as seguintes estratégias:

Identifique os casos de uso adequados: A pesquisa na web é mais valiosa para consultas que exigem informações atualizadas ou específicas.
Otimize os parâmetros de localização: Para consultas geograficamente relevantes, forneça informações de localização precisas.
Ajuste o tamanho do contexto: Comece com a configuração padrão (“medium”) e ajuste com base no equilíbrio desejado entre custo, qualidade e latência.
Apresente as citações de forma clara: Garanta que os usuários possam identificar e acessar facilmente as fontes citadas.
Monitore o uso e os custos: Acompanhe regularmente como a pesquisa na web está afetando seus custos de API e otimize conforme necessário.

Conclusão: O Futuro da IA com Acesso à Web

A integração da pesquisa na web com a API OpenAI representa um passo significativo na evolução dos modelos de linguagem. Ao permitir que os modelos acessem informações atualizadas da internet, essa funcionalidade amplia drasticamente o potencial de aplicações baseadas em IA, tornando-as mais precisas, relevantes e úteis.

À medida que essa tecnologia continua a evoluir, podemos esperar melhorias na precisão, velocidade e eficiência da pesquisa na web, bem como novas formas de integração com outras fontes de dados. As organizações que dominarem essa integração estarão bem posicionadas para criar aplicações de IA mais poderosas e contextualizadas.

Comece a experimentar a pesquisa na web em suas aplicações hoje mesmo e descubra como essa funcionalidade pode transformar a experiência dos seus usuários com respostas mais informadas e atualizadas.

Fonte: OpenAI. “Web Search Integration with OpenAI API”. Disponível em: https://platform.openai.com/docs/guides/web-search.