Pesquisa na Web

Respostas de modelos em tempo real em dados da web

Os dados de treinamento para modelos de linguagem grande têm uma data de corte de conhecimento, impedindo-os de responder perguntas em tempo real. Ativar busca na web permite que um modelo recupere dados em tempo real da internet e responda com precisão a perguntas sensíveis ao tempo, como preços de ações, previsões meteorológicas e notícias de última hora.

[Pegue uma chave API] (/api-reference/preparation/api-keyE o define como uma variável de ambiente./api-reference/preparation/export-api-key-env).

Activar a pesquisa na Web

OpenAI compatible

 Preparar. `enable_search: true` e opcionalmente passar `search_options` para escolher uma estratégia.



  O terminal de conclusão de chat compatível com OpenAI não retorna fontes de busca. Use a API de respostas ou DashScope se precisar de citações.





  ```python Python {15}
  import os
  from openai import OpenAI

  client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
  )
  completion = client.chat.completions.create(
    model="qwen3.7-max",
    messages=[
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "How is Alibaba's stock price?"},
    ],
    extra_body={
      "enable_search": True,
      "search_options": {
        "search_strategy": "agent"
      }
    }
  )
  print(completion.choices[0].message.content)
  ```

  ```javascript Node.js {14}
  import OpenAI from "openai";

  const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
  });

  async function main() {
    const completion = await openai.chat.completions.create({
      model: "qwen3.7-max",
      messages: [
        { role: "user", content: "How is Alibaba's stock price?" }
      ],
      enable_search: true,
      search_options: {
        search_strategy: "agent"
      }
    });
    console.log(completion.choices[0].message.content);
  }

  main();
  ```

  ```bash curl {12}
  curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "messages": [
      {
        "role": "user",
        "content": "How is Alibaba'\''s stock price?"
      }
    ],
    "enable_search": true,
    "search_options": {
      "search_strategy": "agent"
    }
  }'
  ```

Responses API

 Adicionar `web_search` - Para o... `tools` Array.



   Apoiado pelo Qwen3.8 Max, Flash, e série de código aberto, e `qwen3.8-omni-flash`; o Qwen3.7 e Qwen3.5  série (incluindo modelos de código aberto, mas não modelos Omni), o Qwen3.6-Plus e Qwen3.6-Flash  série, e qwen3.6-35b-a3b; deepseek-v4.1-flash, deepseek-v4-flash-0731, deepseek-v4-pro, deepseek-v4-pro-0813; glm-5.2E eu não sei. kimi-k3. Para modelos que suportam essas ferramentas, habilitar `web_search`, `web_extractor`, e `code_interpreter`  Juntos. Por `qwen3.8-omni-flash`A única ferramenta suportada é `web_search`.





   Quando habilitado através do `web_search` O modelo faz uma recuperação multi-voltas estilo agente. `web_search` (e opcionalmente `web_extractor` / `code_interpreter`) várias vezes dentro de uma única resposta.

  `qwen3.8-max`, `qwen3.8-max-0902`, `qwen3.8-flash`, `qwen3.8-2.4t-a95b`, e `qwen3.8-27b`  Não, não, não, não. `agent` valor de `search_strategy` na API de Completação de Chat. Para usar o agente de recuperação multi-volta com Qwen3.8Use a API de Respostas. `web_search`  ferramenta documentada nesta aba.

  A API de Respostas não usa o `search_strategy`  parâmetro. Se a busca na web é acionada - e se o modelo realiza várias buscas - é determinado unicamente pela anexação do `web_search`  ferramenta e pelas próprias decisões do modelo. A `search_options.search_strategy` O valor passado para a API Responses é ignorado silenciosamente e não desencadeia uma busca.





  ```python Python {12}
  from openai import OpenAI
  import os

  client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qwencloudapi.com/compatible-mode/v1"
  )

  response = client.responses.create(
    model="qwen3.7-max",
    input="Singapore weather",
    tools=[{"type": "web_search"}],
    extra_body={"enable_thinking": True}
  )

  print(response.output_text)

  usage = response.usage
  if hasattr(usage, 'x_tools') and usage.x_tools:
    print(f"Web search count: {usage.x_tools.get('web_search', {}).get('count', 0)}")
  ```

  ```javascript Node.js {12}
  import OpenAI from "openai";

  const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
  });

  async function main() {
    const response = await openai.responses.create({
      model: "qwen3.7-max",
      input: "Singapore weather",
      tools: [{ type: "web_search" }],
      enable_thinking: true
    });

    console.log(response.output_text);
    console.log(`Web search count: ${response.usage.x_tools.web_search?.count || 0}`);
  }

  main();
  ```

  ```bash curl {7}
  curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "input": "Singapore weather",
    "tools": [{"type": "web_search"}],
    "enable_thinking": true
  }'
  ```

Sample response output (agent-style multi-turn retrieval)

  Para uma pergunta como "Qual é o clima em Cingapura amanhã?", o modelo realiza várias rodadas de recuperação em uma única resposta. O `output` O array contém múltiplos `web_search_call` (e opcionalmente `web_extractor_call`) itens entrelaçados com `reasoning` e o final `message`:

  ```json
  {
      "output": [
          { "type": "reasoning", "..." : "..." },
          { "type": "web_search_call", "action": { "query": "Singapore weather tomorrow" } },
          { "type": "reasoning", "..." : "..." },
          { "type": "web_extractor_call", "..." : "..." },
          { "type": "web_search_call", "action": { "query": "Singapore 7-day forecast" } },
          { "type": "reasoning", "..." : "..." },
          { "type": "message", "content": [ /* final answer with url_citation annotations */ ] }
      ],
      "usage": {
          "x_tools": { "web_search": { "count": 2 } }
      }
  }
  ```

  A presença de múltiplos `web_search_call`  itens e `x_tools.web_search.count > 1`  confirma a recuperação de várias voltas do tipo agente, o modelo decidiu por si só refinar a consulta e procurar novamente.

DashScope

 Preparar. `enable_search=True` e passar `search_options` com `enable_source: true` para incluir fontes de busca na resposta.



  ```python Python {9}
  import os
  import dashscope
  dashscope.base_http_api_url = "https://maas.qwencloudapi.com/api/v1"

  response = dashscope.Generation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen3.7-max",
    messages=[{"role": "user", "content": "Alibaba stock price"}],
    enable_search=True,
    search_options={
      "search_strategy": "agent",
      "enable_source": True
    },
    result_format="message",
  )
  for web in response.output.search_info["search_results"]:
    print(f"[{web['index']}]: [{web['title']}]({web['url']})")
  print(response.output.choices[0].message.content)
  ```

  ```java Java {29}
  import com.alibaba.dashscope.aigc.generation.Generation;
  import com.alibaba.dashscope.aigc.generation.GenerationParam;
  import com.alibaba.dashscope.aigc.generation.GenerationResult;
  import com.alibaba.dashscope.aigc.generation.SearchOptions;
  import com.alibaba.dashscope.common.Message;
  import com.alibaba.dashscope.utils.Constants;
  import com.alibaba.dashscope.common.Role;
  import java.util.Arrays;

  public class Main {
    static {Constants.baseHttpApiUrl="https://maas.qwencloudapi.com/api/v1";}
    public static void main(String[] args) {
      Generation gen = new Generation();
      Message userMsg = Message.builder()
        .role(Role.USER.getValue())
        .content("Alibaba stock price")
        .build();

      SearchOptions searchOptions = SearchOptions.builder()
        .searchStrategy("agent")
        .enableSource(true)
        .build();

      GenerationParam param = GenerationParam.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .model("qwen3.7-max")
        .messages(Arrays.asList(userMsg))
        .resultFormat(GenerationParam.ResultFormat.MESSAGE)
        .enableSearch(true)
        .searchOptions(searchOptions)
        .build();
      try {
        GenerationResult result = gen.call(param);
        System.out.println(result.getOutput().getSearchInfo().getSearchResults());
        System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
      } catch (Exception e) {
        System.out.println("Error: " + e.getMessage());
      }
    }
  }
  ```

  ```bash curl {15}
  curl -X POST https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "input":{
      "messages":[
        {
          "role": "user",
          "content": "Alibaba stock price"
        }
      ]
    },
    "parameters": {
      "enable_search": true,
      "search_options": {
        "search_strategy": "agent",
        "enable_source": true
      },
      "result_format": "message"
    }
  }'
  ```

Exemplo de resposta.

  ```text
  [1]: [Alibaba (BABA) Stock Price, Quotes, Chart - East Money](https://wap.eastmoney.com/quote/stock/106.BABA.html)
  [2]: [Alibaba (BABA) US Stock Quotes - Sina Finance](https://gu.sina.cn/quotes/us/BABA)
  [3]: [Alibaba (BABA) Latest Stock Price - Investing.com](https://cn.investing.com/equities/alibaba)

  According to the latest market data, Alibaba's stock prices are:
  * US stocks (BABA): ~$160.40
  * HK stocks (09988.HK): ~HK$158.10
  Note that stock prices fluctuate in real time; this information is for reference only.
  ```

Anthropic-compatible

 Adicione a ferramenta de busca na web do lado do servidor Anthropic (`name` - Pronto para... `web_search`) para o `tools`  parâmetro para ativar a busca na web. O ponto final é `https://maas.qwencloudapi.com/apps/anthropic`.

> Este método visa clientes oficiais antrópicos como Claude Code.  Nesses clientes, uma pergunta simples de linguagem natural desencadeia busca na web sem nenhuma configuração extra.

>  Quando você ligar para a API diretamente com o SDK Antrópico ou mais HTTP, passe o identificador do cliente. `x-anthropic-billing-header: cc_entrypoint=cli;` Em `system`.  Caso contrário, a busca na web não faz efeito.

>  Sobre a versão da ferramenta, o sufixo da data. `type` (por exemplo `web_search_20250305`) é determinado pela versão do cliente oficial Antrópico, e um cliente mais novo pode enviar uma versão diferente datada. QwenCloud  identifica a ferramenta por sua categoria e não valida o sufixo de data, então você não precisa afixar `type` para uma versão específica.  Basta passar o valor que seu cliente realmente envia.

```python
# Import dependencies and create the client...
message = client.messages.create(
    model="qwen3.8-max",
    max_tokens=2048,
    # Pass the client identifier
    system=[{"type": "text", "text": "x-anthropic-billing-header: cc_entrypoint=cli;"}],
    messages=[{"role": "user", "content": "What will the weather in Hangzhou be like tomorrow?"}],
    tools=[
        {
            # The date suffix depends on the client version. The value below is the one current Claude Code sends.
            "type": "web_search_20250305",
            "name": "web_search",
            # Optional. Maximum number of searches per request.
            "max_uses": 8
        }
    ]
)
```

O processo de recuperação é devolvido como `server_tool_use` (Pedido de busca) e `web_search_tool_result`  Blocos de conteúdo. O número de buscas é relatado em `usage.server_tool_use.web_search_requests`.

Pesquisa na web com modelos multimodais

O Qwen3.8 Max, Flash, e séries de código aberto, Qwen3.7-Flash, Qwen3.7-Plus, o Qwen3.6 série, e o Qwen3.5 série (incluindo qwen3.5-plus, qwen3.5-flash, o qwen3.5-omni série, e Qwen Aceitam entradas multimodais (imagens, vídeo) e são modelos multimodais.

O suporte de estratégia de busca varia de acordo com a série: qwen3.5-omni série suporta apenas o agent estratégia; qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, e qwen3.8-27b Não apoiem o agent Estratégia na API multimodal (use o padrão turbo Ou max- Para correr Qwen3.8 com recuperação de agente, use [Busca na Web com a API de Respostas] (#enable-web-search); outros modelos listados nesta seção apoiam o turbo, max, e agent Estratégias. Chame estes modelos através da API multimodal multimodal-generation Endpoint): usar MultiModalConversation em Python e Java, não Generation (o text-generation Endpoint), que é para modelos somente de texto. Para o básico de chamar modelos multimodais, veja o [Raciocínio Visual] (/developer-guides/multimodal/visionE o entendimento de imagens e vídeos./developer-guides/getting-started/vision-models) tópicos.

• Chamando os modelos multimodais acima com Generation (o text-generation Endpoint) retorna 400 url error, please check url. Use MultiModalConversation (o multimodal-generation Endpoint) em vez disso.
• No Java SDK, MultiModalConversationParam Provide enableSearch(true) para permitir a busca na web, mas não fornece uma searchOptions() Método. Injete a estratégia de busca e outras opções através do genérico parameter("search_options", ...) Método. Em Python, MultiModalConversation.call Aceita search_options diretamente.
• Pesquisa na web em modelos multimodais requer **streaming chamadas (use streamCall em Java, ou definido stream=True Em Python); caso contrário, a solicitação retorna um Non-streaming mode does not support Web Search Erro.

import os
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = "https://maas.qwencloudapi.com/api/v1"
responses = MultiModalConversation.call(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  model="qwen3.5-plus",
  messages=[{"role": "user", "content": [{"text": "What is the weather in Hangzhou today?"}]}],
  enable_search=True,
  search_options={
    # The qwen3.5-omni series requires agent. On the multimodal API the Qwen3.8 series does not support agent; keep the default.
    "search_strategy": "agent",
    "enable_source": True,
  },
  stream=True,
  incremental_output=True,
)
for response in responses:
  print(response.output.choices[0].message.content)

// dashscope SDK version >= 2.19.0
import java.util.Arrays;
import java.util.Collections;
import io.reactivex.Flowable;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.aigc.generation.SearchOptions;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;
public class Main {
  static { Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1"; }
  public static void main(String[] args) throws Exception {
    MultiModalConversation conv = new MultiModalConversation();
    MultiModalMessage userMsg = MultiModalMessage.builder()
      .role(Role.USER.getValue())
      .content(Arrays.asList(Collections.singletonMap("text", "What is the weather in Hangzhou today?")))
      .build();
    SearchOptions searchOptions = SearchOptions.builder()
      // The qwen3.5-omni series requires agent. On the multimodal API the Qwen3.8 series does not support agent; keep the default.
      .searchStrategy("agent")
      .enableSource(true)
      .build();
    MultiModalConversationParam param = MultiModalConversationParam.builder()
      .apiKey(System.getenv("DASHSCOPE_API_KEY"))
      .model("qwen3.5-plus")
      .messages(Arrays.asList(userMsg))
      .enableSearch(true)
      .parameter("search_options", searchOptions)
      .incrementalOutput(true)
      .build();
    Flowable<MultiModalConversationResult> result = conv.streamCall(param);
    result.blockingForEach(message ->
      System.out.print(message.getOutput().getChoices().get(0).getMessage().getContent()));
  }
}

Modelos apoiados.

Os seguintes modelos suportam a busca na web. Modelos com entradas multimodais Qwen3.8 série, Qwen3.7-Flash/Plus, o Qwen3.6 série, o Qwen3.5 série, e Qwen Modelos de código aberto) devem ser chamados através da API multimodal. Veja [Busca na web com modelos multimodais] (#web-search-with-multimodal-models).

Qwen

Jogando # qwen-plus-character, qwen-flash-character (o agent Estratégia não é apoiada)

Qwen-Max, Qwen-Plus, e Qwen-Flash Modelos lançados após julho de 2025 automaticamente suportam busca na web.

** Modelos de terceira festa **

Estratégias de busca

Use o search_strategy - Não, não, não. search_options Para equilibrar o custo, qualidade e velocidade de resposta:

• **turboEquilibra a velocidade de resposta e qualidade de busca. Adequado para a maioria dos cenários.

• **max Usa uma estratégia de busca mais abrangente e pode chamar vários motores de busca para resultados mais detalhados, mas o tempo de resposta pode ser mais longo.

• **agent Chama a ferramenta de busca na web e o modelo várias vezes para recuperação e integração de informações multi-redondas. Adequado para consultas complexas e cenários ingleses.

  Aplica-se ao Qwen3.5 série (incluindo modelos de código aberto e a série Omni), o Qwen3.6 série, e o Qwen3.7 Série. Chamadas de transmissão são necessárias quando se liga através do ponto final de texto. O Qwen3.8 série não suporta o agent Estratégia.

  Quando habilitado, apenas enable_source: true (Retornando fontes de busca) é suportado; outras características de busca na web estão indisponíveis. Cada invocação é cobrada adicionalmente, veja [Billing] (#billing).

• agent_max- Suporta ler páginas da web com a ferramenta web extractor em cima da agent Estratégia. Só disponível em qwen3.7-max em modo de pensar. Quando habilitado, apenas enable_source: true é suportado, outros recursos de busca estão indisponível. Cada invocação é cobrada adicionalmente, veja [Billing] (#billing).

Use o padrão turbo estratégia para perguntas diárias. Para pesquisa ou geração de relatórios que requer alta precisão e validação cruzada multi-fonte, escolha max Ou agent. agent é recomendado para cenários ingleses.

Leia os resultados da busca.

Quando você se prepara enable_source: true (DashScope somente), a resposta inclui um search_info.search_results Array. Cada entrada contém:

Use estes campos para fazer citações ou uma lista de referências em sua aplicação. O texto de resposta do modelo pode referenciar fontes por índice (por exemplo, "de acordo com a fonte [1]").

-Pegue fontes de busca.

Depois de uma busca na web, as fontes de busca são devolvidas na resposta. Eles aparecem no elemento de quem type É web_search_call dentro da output Array, e sua action.sources campo é a lista de links de origem. Você pode extraí-los do response no exemplo acima, como segue:

A API Responses não suporta o enable_source, enable_citation, ou citation_format parâmetros, e não insere [1] Marcadores de citações no conteúdo de resposta. Para usar marcadores de citação, use a API DashScope.

# Extract search sources from the response above
print("=" * 20 + "Search sources" + "=" * 20)
for item in response.output:
    if item.type == "web_search_call":
        for i, source in enumerate(item.action.sources, start=1):
            print(f"[{i}] {source.url}")

Contagem

A cobrança envolve dois aspectos:

• O conteúdo da web da pesquisa na web é adicionado ao prompt, o que aumenta o número de fichas de entrada para o modelo. Você é cobrado com base no preço padrão do modelo. Para mais informações sobre preços, veja [Precorando] (/developer-guides/getting-started/pricing).

• -Pesquisa de taxas de chamadas.

  Ao usar a API Responses, a ferramenta de busca da web é faturada na mesma taxa que o agent Estratégia.

  Os preços listados abaixo são os preços de lista. Para promoções atuais e preços com desconto, visite o [Modelo Marketplace] (https://www.qwencloud.com/models).

Códigos de erro.

Se uma ligação falhar, veja [Mensagens de erro] (/api-reference/preparation/error-messages).