Ricerca Web

La ricerca Web consente ai modelli di recuperare e integrare le risposte con informazioni aggiornate dal Web pubblico prima di generare l'output. Se abilitato, il modello può restituire risposte aggiornate con citazioni inlinea. La ricerca Web è disponibile tramite lo web_search strumento nell'API Risposte.

Nota

web_search è ora lo strumento consigliato per la ricerca Web nell'API Risposte OpenAI Azure. La versione di anteprima dello strumento di ricerca web (web_search_preview), anche se supportata, non è consigliata.

Importante

  • Ricerca Web usa il grounding con Ricerca Bing e/o con Ricerca personalizzata Bing, che sono Servizi di consumo di prima parte regolati da questi termini di utilizzo di Grounding con Bing e l'Informativa sulla privacy di Microsoft.
  • Il Data Protection Addendum di Microsoft non si applica ai dati inviati a Grounding con Bing Search e/o Grounding con Bing Custom Search. Quando il cliente utilizza il protocollo Grounding con Ricerca Bing e/o con Ricerca Personalizzata Bing, i Dati del Cliente saranno trasferiti al di fuori del limite geografico e di conformità imposto dal cliente.
  • L'uso del grounding con Ricerca Bing e del grounding con Ricerca personalizzata Bing comporta costi; altre informazioni sui prezzi.
  • Altre informazioni su come gli amministratori Azure possono gestire l'accesso all'uso della ricerca Web.

Prerequisiti

  • Modello OpenAI Azure distribuito.
  • Metodo di autenticazione:
    • Chiave API o
    • Microsoft Entra ID.
  • Per esempi di Python:
    • Installare il openai pacchetto.
    • Installare azure-identity per l'autenticazione di Microsoft Entra ID.
  • Per esempi di REST:
    • Impostare AZURE_OPENAI_API_KEY (flusso della chiave API) o AZURE_OPENAI_AUTH_TOKEN (flusso di Microsoft Entra ID).

La ricerca Web supporta tre modalità. Scegliere la modalità in base alla profondità e alla velocità necessarie.

Ricerca Web senza ragionamento

Il modello inoltra la query dell'utente direttamente allo strumento di ricerca web e usa le fonti più rilevanti per supportare la risposta. Non è prevista alcuna pianificazione in più passaggi. Questa modalità è veloce e ottimale per ricerche rapide e fatti tempestivi.

Ricerca agentico con modelli di ragionamento

Il modello gestisce attivamente il processo di ricerca e può eseguire ricerche Web come parte della catena di pensieri, analizzare i risultati e decidere se continuare la ricerca. Questa flessibilità rende la ricerca agenti adatta per flussi di lavoro complessi, ma significa anche che le ricerche richiedono più tempo rispetto alle ricerche rapide.

Ricerca approfondita

Deep Research è una modalità basata su agente progettata per indagini estese. Il modello esegue un ragionamento in più passaggi, può aprire e leggere molte pagine e sintetizza i risultati in una risposta completa e ricca di citazione. Usare questa modalità con o3-deep-research quando è necessario:

  • Ricerca legale o scientifica
  • Analisi del mercato e della concorrenza
  • Creazione di report su grandi corpi di dati interni o pubblici

La ricerca approfondita può essere eseguita per diversi minuti ed è ideale per i carichi di lavoro in background che assegnano priorità alla completezza rispetto alla velocità.

Come funziona

Utilizzi la ricerca web dichiarando lo strumento nella tua richiesta. Il modello può decidere se chiamare lo strumento in base alla richiesta dell'utente e alla configurazione.

Nota

Ricerca Web nell'API Risposte funziona con i modelli GPT-4 e versioni successive.

Usare la ricerca Web con un modello senza ragionamento

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 - Chiave

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 - Chiave 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 della risposta

Una risposta con esito positivo che usa la ricerca Web contiene in genere due parti:

  • Elemento web_search_call di output che registra l'azione eseguita:
    • search: un'azione di ricerca Web, inclusa la query (e facoltativamente i domini di ricerca). Le azioni di ricerca comportano costi di chiamata dello strumento (vedere i prezzi).
    • open_page: (solo Deep Research) indica che l'agente ha aperto una pagina.
    • find_in_page: (solo Deep Research) indica l'agente cercato all'interno di una pagina aperta.
  • Elemento di output del messaggio contenente:
    • Testo collegato a terra in message.content[0].text
    • Citazioni URL in message.content[0].annotations, uno o più url_citation oggetti che contengono l'URL, il titolo e gli intervalli dei caratteri

Esempio

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

Controllare i risultati in base alla posizione dell'utente

È possibile perfezionare i risultati della ricerca specificando un codice paese/area geografica.

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 - Chiave

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 - Chiave 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)

Utilizzare con il modello di ricerca approfondita

Impostare il modello su o3-deep-research per eseguire ricerche in più passaggi su molte fonti. È necessario includere almeno un'origine dati, ad esempio una ricerca Web o un server MCP (Remote Model Context Protocol). È anche possibile includere lo strumento dell'interprete del codice per consentire al modello di scrivere ed eseguire codice per l'analisi.

Poiché Deep Research può eseguire molti passaggi di esplorazione, le richieste possono richiedere più tempo e potrebbero generare più chiamate di strumenti. Per le analisi a esecuzione prolungata, è consigliabile usare modelli di esecuzione in background nell'applicazione.

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 - Chiave

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 - Chiave 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)

Filtro del dominio

È possibile limitare i risultati a un set specifico di domini usando il filtro del dominio. È possibile inserire in lista consentita fino a 100 URL. È possibile omettere il prefisso HTTP o HTTPS durante la formattazione degli URL. Ad esempio, usare microsoft.com anziché https://www.microsoft.com/. I sottodomini sono inclusi anche nella ricerca. Il filtro del dominio funziona solo con l'API delle risposte web_search_tool.

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 - Chiave

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 - Chiave 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

L'accesso a Internet in tempo reale non è supportato. external_web_access Parametro se passato verrà ignorato.

Gestire lo strumento di ricerca Web

È possibile abilitare o disabilitare lo strumento web_search nell'API Risposte a livello di sottoscrizione usando interfaccia della riga di comando di Azure. Questa impostazione si applica a tutti gli account all'interno della sottoscrizione specificata.

Prerequisiti

Prima di eseguire i comandi seguenti, verificare quanto segue:

Per disabilitare lo strumento web_search per tutti gli account in un abbonamento:

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

Questo comando disabilita la ricerca Web in tutti gli account nella sottoscrizione specificata.

Per abilitare lo web_search strumento:

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

Questo comando abilita la funzionalità di ricerca Web Bing per tutti gli account nella sottoscrizione.

Risoluzione dei problemi

  • Nessuna citazione restituita: verificare che la richiesta includa tools: [{"type": "web_search"}]. Se il modello non utilizza lo strumento, incoraggiare esplicitamente a navigare nel web o a chiedere citazioni.
  • Strumento bloccato: chiedere all'amministratore della sottoscrizione di verificare l'impostazione della funzionalità di sottoscrizione per gli strumenti bloccati. Vedere Gestire lo strumento di ricerca Web.
  • Errori di autenticazione: per le chiavi API, assicurarsi di impostare AZURE_OPENAI_API_KEY. Per Microsoft Entra ID, verificare che l'ambito del token sia https://ai.azure.com/.default.
  • Last updated on