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. Puede acceder a la búsqueda web con la herramienta web_search de Responses API.

Nota

En la API de respuestas de OpenAI de Azure, use la herramienta web_search para la búsqueda web. Se admite la versión preliminar de la herramienta de búsqueda web (web_search_preview), pero no se recomienda. Tiene limitaciones.

Importante

  • Web Search utiliza Grounding con Bing Search y/o Grounding con Bing Custom Search, que son First Party Consumption Services regidos por los términos de uso de Grounding con Bing y la Declaración de privacidad de Microsoft.
  • El anexo de Protección de datos de Microsoft no se aplica a los datos enviados a Grounding con Bing Search o Grounding con Bing Custom Search. Cuando usa Fundamentación con Bing Search y/o Fundamentación con Bing Custom Search, sus datos salen de su perímetro de cumplimiento y geográfico.
  • El uso de Grounding con Bing Search y Grounding con Bing Custom Search conlleva costes. Para más información, consulte precios.
  • Más información sobre cómo los administradores de Azure pueden gestionar el acceso a la utilización de la búsqueda web.

Requisitos previos

  • Un modelo de OpenAI Azure implementado.
  • Un método de autenticación:
    • Clave de API o
    • Microsoft Entra ID.
  • Instale la biblioteca cliente para el idioma:
    • Python:pip install openai azure-identity
    • .NET: dotnet add package OpenAI y dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java: agregue com.openai:openai-java y com.azure:azure-identity al proyecto.
  • 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. Por ejemplo, use gpt-5.5 con reasoning.effort establecido en medium o high para equilibrar la profundidad de búsqueda y la latencia.

Investigación profunda

Deep Research es un modo controlado por agentes diseñado para investigaciones extendidas. El modelo realiza el razonamiento en varios pasos, abre y lee muchas páginas y sintetiza los resultados en una respuesta completa enriquecida a citas. Use este modo con o3-deep-research, o con gpt-5.5 y reasoning.effort establecidos en high o xhigh.

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

Usas la búsqueda en la web declarando la herramienta {"type": "web_search"} en tu solicitud. El modelo decide 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.

En los ejemplos siguientes, reemplace por gpt-5.5 el nombre de su propia implementación de modelos. El mismo patrón de assert que se muestra en los fragmentos de código de Microsoft Entra ID básicos se aplica a los fragmentos de código de clave de API y a los ejemplos de ubicación del usuario y filtrado de dominio.

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"

Clave de 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 respuesta

Una respuesta correcta que usa la búsqueda web normalmente contiene dos 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....."
        }
      ],
    }
  ]
  • 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: indica que el agente abrió una página. Disponible con todos los modelos de razonamiento.
    • find_in_page: indica el agente buscado en una página abierta. Disponible con todos los modelos de razonamiento.
  • Elemento de salida de mensaje que contiene:
    • El texto anclado en message.content[0].text.
    • Citas de URL en message.content[0].annotations, uno o varios objetos url_citation que incluyen la URL, el título y los rangos de caracteres.

Cuando se usa un modelo de razonamiento, la output matriz también contiene un reasoning elemento junto con web_search_call y message. Analice el array por type en lugar de por posición.

Controlar los resultados por ubicación del usuario

Puede refinar los resultados de búsqueda pasando la ubicación aproximada del usuario. Se admiten los siguientes campos:

Campo Description Ejemplo
country Código de país o región ISO de dos letras. US
city Nombre de ciudad de texto libre. Chicago
region Región de texto libre o nombre de estado. Illinois
timezone Identificador de zona horaria de IANA. America/Chicago

Nota

Los campos city, region y timezone solo se admiten cuando se utiliza la herramienta web_search.

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 la autenticación de clave de API, reemplace la credencial de Microsoft Entra por la clave de API, como se muestra en el ejemplo basic.

Filtrado de dominios

Puede limitar los resultados a un conjunto específico de dominios mediante el filtrado de dominios. Use el allowed_domains campo para incluir hasta 100 direcciones URL o el blocked_domains campo para excluir dominios de los resultados. Puede omitir el prefijo HTTP o HTTPS al dar formato a las direcciones URL. Por ejemplo, usa 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 con la web_search herramienta en la API de respuestas.

Nota

Los SDK de OpenAI para .NET y Java todavía no exponen constructores tipados para blocked_domains. Los ejemplos de C# y Java aquí usan las tramas de escape públicas de los SDK (JsonPatch.Set para .NET, putAdditionalProperty para Java) para establecer el campo. Cuando se lancen los constructores tipados, sustituye esas llamadas por sus equivalentes tipados.

Para devolver las fuentes consultadas por el modelo, configure include como ["web_search_call.action.sources"]. Las URL de origen coincidentes aparecen en el array action.sources del elemento de salida web_search_call. Cada entrada contiene un type y un url. Los títulos de página no se devuelven en action.sources; en su lugar, el texto fundamentado del modelo incluye los títulos en las anotaciones url_citation del elemento del mensaje.

Para devolver los fragmentos de los resultados de búsqueda que consultó el modelo, establezca include en ["web_search_call.results"]. La web_search_call.results opción solo se admite cuando se usa un modelo de razonamiento.

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 la autenticación de clave de API, reemplace la credencial de Microsoft Entra por la clave de API, como se muestra en el ejemplo basic.

Limitaciones

  • No se admite el acceso directo a Internet. Azure OpenAI siempre trata el parámetro external_web_access como false.
  • La lista de permitidos de dominio admite hasta 100 direcciones URL.
  • Las acciones de las llamadas de búsqueda web generan costes de llamadas a herramientas. Para más información, consulte los precios.
  • Se admite la versión preliminar de la herramienta de búsqueda web (web_search_preview), pero no se recomienda.
  • Las open_page acciones y find_in_page solo están disponibles con modelos de razonamiento.

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 siguientes comandos, asegúrese de que tiene los siguientes requisitos previos:

  • CLI de Azure 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 unregister --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 register --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