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. A pesquisa na web está disponível através da ferramenta web_search na API Respostas.

Nota

web_search é agora a ferramenta recomendada para pesquisa na Web na API Azure OpenAI Responses. A versão de pré-visualização da ferramenta de pesquisa web (web_search_preview), embora suportada, não é recomendada.

Importante

  • Web Search utiliza Grounding com Bing Search e/ou Grounding com Bing Custom Search, que são Serviços de Consumo de Primeira Parte regidos por estes termos de uso do Grounding com Bing e pela Declaração de Privacidade da Microsoft.
  • O Adendo Microsoft Proteção de Dados não se aplica a dados enviados para Grounding com Bing Search e/ou Grounding com Bing Custom Search. Quando o Cliente utiliza o Grounding com Bing Search e/ou o Grounding com Bing Custom Search, os dados do Cliente podem fluir para fora dos limites de conformidade e geográficos do Cliente.
  • A utilização de Grounding com Bing Search e Grounding com Bing Custom Search terá custos; Saiba mais sobre preços.
  • Saiba mais sobre como Azure administradores podem gerir o acesso à utilização da pesquisa web.

Pré-requisitos

  • Um modelo Azure OpenAI implementado.
  • Um método de autenticação:
    • Chave API, ou
    • Microsoft Entra ID.
  • Para exemplos de Python:
    • Instala o openai pacote.
    • Instale azure-identity para a autenticação do Microsoft Entra ID.
  • Para exemplos de REST:
    • Defina AZURE_OPENAI_API_KEY (fluxo de chave 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.

Investigação aprofundada

Deep Research é um modo orientado por agentes, concebido para investigações prolongadas. O modelo realiza raciocínio em múltiplos passos, pode abrir e ler muitas páginas, e sintetiza os resultados numa resposta abrangente e rica em citações. Usa este modo com o3-deep-research quando precisares:

  • Investigação jurídica ou científica
  • Análise de mercado e concorrência
  • Relatórios sobre grandes volumes de dados internos ou públicos

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

Para utilizar a pesquisa na web, declare a ferramenta na sua solicitação. O modelo pode decidir se chama 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.

Utilize a pesquisa na web com um modelo sem capacidade de raciocínio

REST API - Entra ID

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4.1",
     "tools": [{"type": "web_search"}],
     "input": "Please perform a web search on the latest trends in renewable energy"
    }'

API REST - Chave

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
     "model": "gpt-4.1",
     "tools": [{"type": "web_search"}],
     "input": "Please perform a web search on the latest trends in renewable energy"
    }'

Python - API Key

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

response = client.responses.create(   
  model="gpt-4.1", # Replace with your model deployment name
  tools=[{"type": "web_search"}], 
  input="Please perform a web search on the latest trends in renewable energy"
)

print(response.output_text)

Python - Entra ID

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

response = client.responses.create(   
  model="gpt-4.1", # Replace with your model deployment name
  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 utilizou pesquisa web normalmente contém duas partes:

  • 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). As ações de pesquisa acarretam custos de chamadas de ferramenta (ver preços).
    • open_page: (Somente para o Deep Research) significa que o agente abriu uma página.
    • find_in_page: (Apenas Pesquisa Profunda) indica que o agente procurou em uma página aberta.
  • Um item de saída de mensagem contendo:
    • O texto fundamentado em message.content[0].text
    • Citações de URL em message.content[0].annotations, um ou mais objetos url_citation que incluem o URL, o título e os intervalos de caracteres

Exemplo

[
    {
      "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....."
        }
      ],
    }
  ]

Resultados de controlo por localização do utilizador

Pode refinar os resultados da pesquisa especificando um código de país/região.

REST API - Entra ID

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "model": "gpt-4.1",
    "tools": [
        {
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "IN"
            }
        }
    ],
    "input": "Give me a positive news story from the web today"
    }'

API REST - Chave

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
     "model": "gpt-4.1",
     "tools": [
        {
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "IN"
            }
        }
    ],
    "input": "Give me a positive news story from the web today"
    }'

Python - API Key

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

response = client.responses.create(   
  model="gpt-4.1", # Replace with your model deployment name
  tools= [
        {
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "IN"
            }
        }
    ],
    input="Give me a positive news story from the web today"
)

print(response.output_text)

Python - Entra ID

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

response = client.responses.create(   
  model="gpt-4.1", # Replace with your model deployment name
  tools= [
        {
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "IN"
            }
        }
    ],
    input="Give me a positive news story from the web today"
)

print(response.output_text)

Utilização com o modelo de investigação profunda

Defina o modelo para o3-deep-research realizar investigação em múltiplas etapas em várias fontes. Deve incluir pelo menos uma fonte de dados (por exemplo, pesquisa na web ou um servidor remoto Model Context Protocol (MCP)). Também pode incluir a ferramenta de interpretação de código para permitir que o modelo escreva e execute código para análise.

Como a Deep Research pode executar muitos passos de navegação, os pedidos podem demorar mais tempo e podem envolver múltiplas chamadas de ferramenta. Para análises de longa duração, considere usar padrões de execução em segundo plano na sua aplicação.

REST API - Entra ID

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "o3-deep-research",
     "tools": [
                {"type": "web_search"},
                { "type": "code_interpreter", "container": { "type": "auto" }}
              ],
     "input": "Research the economic impact of semaglutide on global healthcare systems. Include specific figures, trends, statistics, and measurable outcomes. Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports. Include inline citations and return all source metadata. Be analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
    }'

API REST - Chave

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
     "model": "o3-deep-research",
     "tools": [
                {"type": "web_search"},
                { "type": "code_interpreter", "container": { "type": "auto" }}
              ],
     "input": "Research the economic impact of semaglutide on global healthcare systems. Include specific figures, trends, statistics, and measurable outcomes. Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports. Include inline citations and return all source metadata. Be analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
    }'

Python - API Key

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

response = client.responses.create(   
  model="o3-deep-research", # Replace with your model deployment name
  tools=[
            {"type": "web_search"},
            { "type": "code_interpreter", "container": { "type": "auto" }}
        ], 
  input="Research the economic impact of semaglutide on global healthcare systems. Include specific figures, trends, statistics, and measurable outcomes. Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports. Include inline citations and return all source metadata. Be analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
)

print(response.output_text)

Python - Entra ID

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

response = client.responses.create(   
  model="o3-deep-research", # Replace with your model deployment name
  tools=[
            {"type": "web_search"},
            { "type": "code_interpreter", "container": { "type": "auto" }}
        ], 
  input="Research the economic impact of semaglutide on global healthcare systems. Include specific figures, trends, statistics, and measurable outcomes. Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports. Include inline citations and return all source metadata. Be analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
)

print(response.output_text)

Filtragem de domínio

Pode limitar os resultados a um conjunto específico de domínios usando filtragem de domínio. Pode adicionar até 100 URLs à lista de permissões. 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 funciona na web_search_tool apenas com a API de respostas.

API REST - Entra ID

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
	  "model": "gpt-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"
		]
	      }
	    }
	  ],
	  "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."
	}'

API REST - Chave

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
	  "model": "gpt-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"
		]
	      }
	    }
	  ],
	  "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."
	}'

Python - Chave API

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

response = client.responses.create(   
  model="gpt-5", # Replace with your model deployment name
  tools= [
	    {
	      "type": "web_search",
	      "filters": {
		"allowed_domains": [
		  "pubmed.ncbi.nlm.nih.gov",
		  "clinicaltrials.gov",
		  "www.who.int",
		  "www.cdc.gov",
		  "www.fda.gov"
		]
	      }
	    }
	  ],
  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)

Python - Entra ID

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)
response = client.responses.create(   
  model="gpt-5", # Replace with your model deployment name
  tools= [
	    {
	      "type": "web_search",
	      "filters": {
		"allowed_domains": [
		  "pubmed.ncbi.nlm.nih.gov",
		  "clinicaltrials.gov",
		  "www.who.int",
		  "www.cdc.gov",
		  "www.fda.gov"
		]
	      }
	    }
	  ],
  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)

Importante

O acesso à internet ao vivo não é suportado. O parâmetro external_web_access , se for ultrapassado, será ignorado.

Gerir ferramenta de pesquisa web

Pode ativar ou desativar a ferramenta web_search na API 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 comandos abaixo, certifique-se do seguinte:

  • CLI do Azure está instalado.
  • Estás autenticado no Azure usando az login
  • Tem acesso de Proprietário ou Contribuinte à 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.
  • Last updated on