Pesquisa na Web

A pesquisa na web permite que os modelos recuperem e fundamentem respostas com informação em tempo real da web pública antes de gerarem a saída. Quando estiver ativado, o modelo pode devolver respostas atualizadas com citações inline. Pode aceder à pesquisa na Web através da ferramenta web_search na Responses API.

Nota

Na API Azure OpenAI Responses, utilize a ferramenta web_search para pesquisa web. A versão de pré-visualização da ferramenta de pesquisa web (web_search_preview) é suportada, mas não recomendada. Tem limitações.

Importante

Pré-requisitos

  • Um modelo Azure OpenAI implementado.
  • Um método de autenticação:
    • Chave API, ou
    • Microsoft Entra ID.
  • Instale a biblioteca cliente para a sua linguagem:
    • Python:pip install openai azure-identity
    • .NET: dotnet add package OpenAI e dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java: Adicione com.openai:openai-java e com.azure:azure-identity ao seu projeto.
  • Para exemplos REST, defina AZURE_OPENAI_API_KEY (fluxo de chaves API) ou AZURE_OPENAI_AUTH_TOKEN (fluxo Microsoft Entra ID).

A pesquisa na web suporta três modos. Escolhe o modo com base na profundidade e velocidade que precisas.

Pesquisa na web sem raciocínio

O modelo encaminha a consulta do utilizador diretamente para a ferramenta de pesquisa web e utiliza as fontes mais bem classificadas para fundamentar a resposta. Não há planeamento em várias etapas. Este modo é rápido e ideal para pesquisas rápidas e factos oportunos.

Pesquisa agente com modelos de raciocínio

O modelo gere ativamente o processo de pesquisa e pode realizar pesquisas na web como parte da sua cadeia de pensamento, analisar resultados e decidir se continua a pesquisar. Esta flexibilidade torna a pesquisa agential bem adequada para fluxos de trabalho complexos, mas também significa que as pesquisas demoram mais do que as consultas rápidas. Por exemplo, use gpt-5.5 com reasoning.effort definido como medium ou high para equilibrar a profundidade da pesquisa e a latência.

Investigação aprofundada

Deep Research é um modo orientado por agentes, concebido para investigações prolongadas. O modelo realiza raciocínio em vários passos, abre e lê muitas páginas, e sintetiza os resultados numa resposta abrangente e rica em citações. Use este modo com o3-deep-research, ou com gpt-5.5 e reasoning.effort definidos como high ou xhigh.

Deep Research pode durar vários minutos e é ideal para cargas de trabalho em segundo plano que priorizam a completude em detrimento da velocidade.

Como funciona

Utiliza a pesquisa na web declarando a ferramenta {"type": "web_search"} no seu pedido. O modelo decide se deve chamar a ferramenta com base no prompt do utilizador e na sua configuração.

Nota

A pesquisa na Web da API de Respostas funciona com modelos GPT-4 e posteriores.

Nos exemplos que se seguem, substitua gpt-5.5 pelo nome do seu próprio modelo de implementação. O mesmo padrão assert mostrado nos excertos básicos de Microsoft Entra ID aplica-se aos excertos de chave API e aos exemplos de localização do utilizador e filtragem de domínio.

Microsoft Entra ID:

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

# Use the OpenAI client with the Azure v1 endpoint.
openai = OpenAI(
    base_url=endpoint,
    api_key=token_provider,
)

response = openai.responses.create(
    model="gpt-5.5",
    tools=[{"type": "web_search"}],
    input="Please perform a web search on the latest trends in renewable energy",
)

print(response.output_text)

# Verify the call succeeded.
assert response.output_text, "Empty output_text"
assert any(item.type == "web_search_call" for item in response.output), \
    "No web_search_call in response"

Chave da API:

import os
from openai import OpenAI

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"

openai = OpenAI(
    base_url=endpoint,
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
)

response = openai.responses.create(
    model="gpt-5.5",
    tools=[{"type": "web_search"}],
    input="Please perform a web search on the latest trends in renewable energy",
)

print(response.output_text)

Forma de resposta

Uma resposta bem-sucedida que utiliza pesquisa web normalmente contém duas partes:

[
    {
      "id": "ws_68b9d1220b288199bf942a3e48055f3602e3b78a8dbf73ac",
      "type": "web_search_call",
      "status": "completed",
      "action": {
        "type": "search",
        "query": "latest trends in renewable energy 2025"
      }
    },
    {
      "id": "msg_68b9d123f4788199a544b6b97e65673e02e3b78a8dbf73ac",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "annotations": [
            {
                "type": "url_citation",
                "start_index": 1358,
                "end_index": 1462,
                "url": "https://...",
                "title": "Title..."
            }
        ],
          "text": "If you're searching for uplifting....."
        }
      ],
    }
  ]
  • Um web_search_call item de saída que regista a ação realizada:
    • search: uma ação de pesquisa web, incluindo a consulta e, opcionalmente, os domínios pesquisados.
    • open_page: indica que o agente abriu uma página. Disponível com todos os modelos de razão.
    • find_in_page: indica que o agente procurou dentro de uma página aberta. Disponível com todos os modelos de razão.
  • Um item de saída de mensagem contendo:
    • O texto fundamentado em message.content[0].text.
    • Citações de URLs em message.content[0].annotations, um ou mais objetos url_citation que incluam o URL, o título e os intervalos de caracteres.

Quando utiliza um modelo de raciocínio, a matriz output também contém um item reasoning juntamente com web_search_call e message. Analise o array por type em vez de por posição.

Utilização e faturação da pesquisa na Web

As taxas de pesquisa na web baseiam-se no número de pedidos de pesquisa no Bing. Utilize tool_usage.web_search.num_requests no corpo da resposta para identificar esta contagem. A contagem de pedidos está disponível para todos os modelos que suportam pesquisa na web.

Não calcule o uso faturável contando search ações ou web_search_call itens de saída. Estas contagens não representam de forma fiável o número de pedidos de pesquisa no Bing. Para conhecer as tarifas, consulte os preços do Grounding with Bing.

Resultados de controlo por localização do utilizador

Pode refinar os resultados da pesquisa passando a localização aproximada do utilizador. Os seguintes campos são suportados:

Campo Descrição Exemplo
country Código ISO de país/região de duas letras. US
city Nome da cidade em texto livre. Chicago
region Nome da região ou estado em texto livre. Illinois
timezone Identificador de fuso horário IANA. America/Chicago

Nota

Os citycampos , region, e timezone só são suportados quando usas a web_search ferramenta.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

openai = OpenAI(base_url=endpoint, api_key=token_provider)

response = openai.responses.create(
    model="gpt-5.5",
    tools=[
        {
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "US",
                "city": "Chicago",
                "region": "Illinois",
                "timezone": "America/Chicago",
            },
        }
    ],
    input="Give me a positive news story from the web today in my city",
)

print(response.output_text)

Para usar autenticação de chave API, substitua a credencial Microsoft Entra pela sua chave API, conforme mostrado no exemplo basic.

Filtragem de domínio

Pode limitar os resultados a um conjunto específico de domínios usando filtragem de domínio. Use o allowed_domains campo para permitir até 100 URLs, ou o blocked_domains campo para excluir domínios dos resultados. Pode omitir o prefixo HTTP ou HTTPS ao formatar os URLs. Por exemplo, use microsoft.com em vez de https://www.microsoft.com/. Subdomínios também estão incluídos na pesquisa. A filtragem de domínio só funciona com a ferramenta web_search na API de Responses.

Nota

Os SDKs OpenAI .NET e Java ainda não expõem construtores tipados para blocked_domains. Os exemplos de C# e Java aqui usam as escotilhas públicas de escape dos SDKs (JsonPatch.Set para .NET, putAdditionalProperty para Java) para definir o campo. Quando os construtores tipados forem disponibilizados, substitua essas chamadas pelas versões tipadas equivalentes.

Para retornar as fontes consultadas pelo modelo, defina include para ["web_search_call.action.sources"]. Os URLs de origem correspondentes aparecem no action.sources array do web_search_call item de saída. Cada entrada contém um type e um url. Os títulos das páginas não são devolvidos em action.sources; em vez disso, o texto fundamentado do modelo inclui os títulos nas anotações url_citation do item de mensagem.

Para devolver os excertos de resultados de pesquisa consultados pelo modelo, defina include para ["web_search_call.results"]. A web_search_call.results opção só é suportada quando se utiliza um modelo de raciocínio.

No Azure OpenAI, open_page e find_in_page não devolvem os resultados à sua aplicação através de web_search_call.results, mesmo quando solicita esta opção.

O modelo ainda pode aceder a conteúdos em cache quando disponíveis. Este conteúdo não é obtido em direto do site. Resultados em falta não significam necessariamente que o modelo não tinha conteúdo disponível.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

openai = OpenAI(base_url=endpoint, api_key=token_provider)

response = openai.responses.create(
    model="gpt-5.5",
    reasoning={"effort": "low"},
    tools=[
        {
            "type": "web_search",
            "filters": {
                "allowed_domains": [
                    "pubmed.ncbi.nlm.nih.gov",
                    "clinicaltrials.gov",
                    "www.who.int",
                    "www.cdc.gov",
                    "www.fda.gov",
                ],
                "blocked_domains": [
                    "en.wikipedia.org",
                    "www.reddit.com",
                ],
            },
        }
    ],
    tool_choice="auto",
    include=["web_search_call.action.sources"],
    input="Please perform a web search on how semaglutide is used in the treatment of diabetes.",
)

print(response.output_text)

Para usar autenticação de chave API, substitua a credencial Microsoft Entra pela sua chave API, conforme mostrado no exemplo basic.

Limitações

  • O acesso à internet em tempo real não é suportado. Azure a OpenAI trata sempre o parâmetro external_web_access como false.
  • A lista de permissões de domínio suporta até 100 URLs.
  • As taxas de pesquisa na web baseiam-se nos pedidos de pesquisa do Bing reportados em tool_usage.web_search.num_requests, e não no número search de ações. Para mais informações, consulte Utilização e faturação da pesquisa na Web.
  • A versão de pré-visualização da ferramenta de pesquisa web (web_search_preview) é suportada, mas não recomendada.
  • As ações open_page e find_in_page estão disponíveis apenas com modelos de raciocínio. Estas ações não retornam resultados através de web_search_call.results.

Gerir ferramenta de pesquisa web

Pode ativar ou desativar a ferramenta web_search na API de Respostas ao nível da subscrição usando CLI do Azure. Esta definição aplica-se a todas as contas dentro da subscrição especificada.

Pré-requisitos

Antes de executar os seguintes comandos, certifique-se de que tem os seguintes pré-requisitos:

  • CLI do Azure instalado.
  • Está ligado a Azure usando az login.
  • Tem acesso de Proprietário ou de Contribuidor à subscrição.

Para desativar a ferramenta web_search em todas as contas de uma subscrição:

az feature register --name OpenAI.BlockedTools.web_search --namespace Microsoft.CognitiveServices --subscription "<subscription-id>"

Este comando desativa a pesquisa web em todas as contas da subscrição especificada.

Para ativar a web_search ferramenta:

az feature unregister --name OpenAI.BlockedTools.web_search --namespace Microsoft.CognitiveServices --subscription "<subscription-id>"

Este comando permite a funcionalidade de pesquisa web do Bing para todas as contas da subscrição.

Resolução de problemas

  • Nenhuma citação devolvida: Confirme que o seu pedido inclui tools: [{"type": "web_search"}]. Se o modelo não chamar a ferramenta, pede de forma mais explícita para navegar na web ou pedir citações.
  • Ferramenta bloqueada: Peça ao administrador da subscrição para verificar a definição da funcionalidade de subscrição para ferramentas bloqueadas. Consulte a ferramenta de gestão de pesquisa web.
  • Erros de autenticação: Para chaves API, verifique se definiu AZURE_OPENAI_API_KEY. Para Microsoft Entra ID, verifica se o escopo do teu token é https://ai.azure.com/.default.
  • Última atualização a