Búsqueda web

La búsqueda web permite que los modelos recuperen y basen respuestas con información en tiempo real de la web pública antes de generar la salida. Cuando se habilita, el modelo puede devolver respuestas actualizadas con citas insertadas. La búsqueda web está disponible a través de la web_search herramienta en la API de respuestas.

Nota

web_search es ahora la herramienta recomendada para la búsqueda web en la API de respuestas de OpenAI de Azure. No se recomienda la versión preliminar de la herramienta de búsqueda en la web (web_search_preview), aunque esté soportada.

Importante

Requisitos previos

  • Un modelo de OpenAI Azure implementado.
  • Un método de autenticación:
    • Clave de API o
    • Microsoft Entra ID.
  • Para obtener Python ejemplos:
    • Instale el openai paquete.
    • Instale azure-identity para la autenticación de Microsoft Entra ID.
  • Para obtener ejemplos de REST:
    • Establezca AZURE_OPENAI_API_KEY (flujo de claves de API) o AZURE_OPENAI_AUTH_TOKEN (flujo de Microsoft Entra ID).

La búsqueda web admite tres modos. Elija el modo en función de la profundidad y la velocidad que necesite.

Búsqueda web sin razonamiento

El modelo reenvía la consulta del usuario directamente a la herramienta de búsqueda web y usa orígenes de clasificación superior para establecer la respuesta. No hay ningún planeamiento de varios pasos. Este modo es rápido y mejor para búsquedas rápidas y hechos oportunos.

Búsqueda agente con modelos de razonamiento

El modelo administra activamente el proceso de búsqueda y puede realizar búsquedas web como parte de su cadena de pensamiento, analizar resultados y decidir si desea seguir buscando. Esta flexibilidad hace que la búsqueda agente sea adecuada para flujos de trabajo complejos, pero también significa que las búsquedas tardan más que búsquedas rápidas.

Investigación profunda

Deep Research es un modo controlado por agentes diseñado para investigaciones extendidas. El modelo realiza el razonamiento en varios pasos, puede abrir y leer muchas páginas y sintetiza los resultados en una respuesta completa y enriquecida a citas. Use este modo con o3-deep-research cuando necesite:

  • Investigación jurídica o científica
  • Análisis de mercado y competitivo
  • Informes sobre grandes cuerpos de datos internos o públicos

La investigación profunda se puede ejecutar durante varios minutos y es mejor para las cargas de trabajo de estilo de segundo plano que priorizan la integridad con respecto a la velocidad.

Cómo funciona

Usa la búsqueda en la web mediante la declaración de la herramienta en su solicitud. El modelo puede decidir si se debe llamar a la herramienta en función del mensaje del usuario y la configuración.

Nota

Web Search en la API de respuestas funciona con modelos GPT-4 y versiones posteriores.

Uso de la búsqueda web con un modelo sin razonamiento

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-4.1",
     "tools": [{"type": "web_search"}],
     "input": "Please perform a web search on the latest trends in renewable energy"
    }'

API REST: clave de acceso

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: clave de 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-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 respuesta

Una respuesta correcta que usó la búsqueda web normalmente contiene dos partes:

  • Elemento web_search_call de salida que registra la acción realizada:
    • search: una acción de búsqueda web, incluida la consulta (y, opcionalmente, los dominios buscados). Las acciones de búsqueda incurren en costos de llamadas de herramientas (consulte precios).
    • open_page: (solo Deep Research) indica que el agente abrió una página.
    • find_in_page: (solo para Deep Research) indica que el agente busca dentro de una página que ya está abierta.
  • Elemento de salida de mensaje que contiene:
    • El texto anclado en message.content[0].text
    • Citas de direcciones URL en message.content[0].annotations, uno o varios url_citation objetos que incluyen la dirección URL, el título y los intervalos de caracteres

Ejemplo

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

Controlar los resultados por ubicación del usuario

Puede refinar los resultados de búsqueda especificando un código de país o región.

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-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: clave de acceso

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: clave de 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-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)

Uso con el modelo de investigación profunda

Establezca el modelo en o3-deep-research para realizar investigación en múltiples pasos a través de múltiples fuentes. Debe incluir al menos un origen de datos (por ejemplo, búsqueda web o un servidor remoto de Protocolo de contexto de modelo (MCP). También puede incluir la herramienta de intérprete de código para permitir que el modelo escriba y ejecute código para su análisis.

Dado que Deep Research puede ejecutar muchos pasos de exploración, las solicitudes pueden tardar más tiempo y pueden incurrir en varias llamadas a herramientas. Para los análisis de larga duración, considere la posibilidad de usar patrones de ejecución en segundo plano en la aplicación.

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": "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: clave de acceso

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: clave de 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="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)

Filtrado de dominios

Puede limitar los resultados a un conjunto específico de dominios mediante el filtrado de dominios. Puede enumerar hasta 100 direcciones URL. Puede omitir el prefijo HTTP o HTTPS al dar formato a las direcciones URL. Por ejemplo, use microsoft.com en lugar de https://www.microsoft.com/. Los subdominios también se incluyen en la búsqueda. El filtrado de dominios solo funciona en web_search_tool con la API de respuestas.

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: clave

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: clave de 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

No se admite el acceso directo a Internet. Si se pasa, el parámetro external_web_access será ignorado.

Administración de la herramienta de búsqueda web

Puede habilitar o deshabilitar la herramienta web_search en la API de respuestas en el nivel de suscripción mediante CLI de Azure. Esta configuración se aplica a todas las cuentas de la suscripción especificada.

Requisitos previos

Antes de ejecutar los comandos siguientes, asegúrese de lo siguiente:

  • CLI de Azure está instalado.
  • Ha iniciado sesión en Azure con az login
  • Tiene acceso de propietario o colaborador a la suscripción.

Para deshabilitar la web_search herramienta para todas las cuentas de una suscripción:

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

Este comando deshabilita la búsqueda web en todas las cuentas de la suscripción especificada.

Para habilitar la web_search herramienta:

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

Este comando habilita la funcionalidad de búsqueda web de Bing para todas las cuentas de la suscripción.

Solución de problemas

  • Sin citas devueltas: confirme que la solicitud incluye tools: [{"type": "web_search"}]. Si el modelo no llama a la herramienta, indique más explícitamente que navegue por la web o que solicite citas.
  • Herramienta bloqueada: pida al administrador de la suscripción que compruebe la configuración de características de suscripción para las herramientas bloqueadas. Consulte Administración de la herramienta de búsqueda web.
  • Errores de autenticación: en el caso de las claves de API, compruebe que establece AZURE_OPENAI_API_KEY. Para Microsoft Entra ID, compruebe que el ámbito del token es https://ai.azure.com/.default.
  • Last updated on