Skip to main content
Chamada de ferramentas

Web search

Os dados de treinamento de modelos grandes de linguagem possuem uma data limite de conhecimento, o que impede respostas a perguntas em tempo real. Ao ativar a pesquisa na web, o modelo recupera dados atualizados e responde com precisão a questões sensíveis ao tempo, como cotações de ações, previsões do tempo e notícias de última hora.

Uso

É possível ativar a pesquisa na web por meio das três chamadas de API abaixo, cada uma exigindo parâmetros diferentes.
Para realizar pesquisas na web com modelos como qwen3.7-max, utilize a web search feature of the Responses API .
  • OpenAI-compatible: Responses API
  • OpenAI-compatible: Chat Completions API
  • DashScope
Adicione a ferramenta web_search ao parâmetro tools para ativar a pesquisa na web.
A Responses API suporta apenas alguns modelos. Para ver os modelos suportados, consulte Pesquisa na web com a Responses API. 
# Import dependencies and create a client...
response = client.responses.create(
    model="qwen3.8-max",
    input="Hangzhou weather",
    tools=[
        {"type": "web_search"},
        {"type": "web_extractor"},
        {"type": "code_interpreter"}
    ],
    extra_body={"enable_thinking": True}
)

Pesquisa na web com modelos multimodais

A série Qwen3.8, Qwen3.7-Flash, Qwen3.7-Plus, a série Qwen3.6 e a série Qwen3.5 (incluindo qwen3.5-plus, qwen3.5-flash, a série qwen3.5-omni e os modelos open-source Qwen) aceitam entradas multimodais (imagens e vídeo), sendo classificados como modelos multimodais. O suporte à estratégia de pesquisa varia conforme a série: a série qwen3.5-omni suporta apenas a estratégia agent; a série Qwen3.8 não suporta a estratégia agent (use turbo ou max, o padrão); os demais modelos suportam as estratégias turbo, max e agent. Chame esses modelos pela API multimodal (o endpoint multimodal-generation): use MultiModalConversation tanto em Python quanto em Java, e não Generation (o endpoint text-generation), destinado a modelos apenas de texto. Para conceitos básicos sobre chamadas de modelos multimodais, consulte os tópicos Raciocínio visual e Compreensão de imagens e vídeos.
Chamar os modelos multimodais acima com Generation (o endpoint text-generation ) retorna o erro 400 url error, please check url . Utilize MultiModalConversation (o endpoint multimodal-generation ) em vez disso. No SDK Java, MultiModalConversationParam fornece enableSearch(true) para ativar a pesquisa na web, mas não disponibiliza um método searchOptions() . Injete a estratégia de pesquisa e outras opções pelo método genérico parameter("search_options", ...) . Em Python, MultiModalConversation.call aceita search_options diretamente. A pesquisa na web em modelos multimodais exige chamadas em streaming (use streamCall em Java ou defina stream=True em Python); caso contrário, a solicitação retorna o erro Non-streaming mode does not support Web Search .
Python
import os
import dashscope
from dashscope import MultiModalConversation
# The following uses the Singapore region. Replace {WorkspaceId} with your actual workspace ID; the configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
responses = MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Use a multimodal model that supports web search.
    model="qwen3.5-plus",
    messages=[{"role": "user", "content": [{"text": "What is the weather in Hangzhou today?"}]}],
    # The multimodal API accepts enable_search and search_options directly.
    enable_search=True,
    search_options={
        # A série qwen3.5-omni requer agent. A série Qwen3.8 não suporta agent; mantenha o padrão.
        "search_strategy": "agent",
        "enable_source": True,
    },
    # Streaming is required when web search is enabled for multimodal models.
    stream=True,
    incremental_output=True,
)
for response in responses:
    print(response.output.choices[0].message.content)

Modelos compatíveis

Os modelos a seguir suportam pesquisa na web. Modelos com entrada multimodal (série Qwen3.8, Qwen3.7-Flash/Plus, série Qwen3.6, série Qwen3.5 e modelos open-source Qwen) devem ser chamados pela API multimodal. Consulte Pesquisa na web com modelos multimodais.
  • Singapore
  • China (Beijing)
  • Qwen
    • Qwen3.8 series: qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b (a estratégia agent não é suportada)
    • Qwen3.7 series: qwen3.7-max, qwen3.7-max-preview, qwen3.7-max-2026-05-17 e snapshots posteriores, qwen3.7-plus, qwen3.7-plus-2026-05-26 e snapshots posteriores, qwen3.7-flash, qwen3.7-flash-2026-07-15 e snapshots posteriores
    • Qwen3.6 series: qwen3.6-max-preview, qwen3.6-plus, qwen3.6-plus-2026-04-02 e snapshots posteriores, qwen3.6-flash, qwen3.6-flash-2026-04-16 e snapshots posteriores, qwen3.6-27b, qwen3.6-35b-a3b
    • Qwen3.5 series: qwen3.5-plus, qwen3.5-plus-2026-02-15 e snapshots posteriores, qwen3.5-flash, qwen3.5-flash-2026-02-23 e snapshots posteriores, qwen3.5-27b, qwen3.5-35b-a3b, qwen3.5-122b-a10b, qwen3.5-397b-a17b
    • Qwen3-Max: qwen3-max, qwen3-max-2025-09-23 e snapshots posteriores
    • Qwen-Omni: qwen3.5-omni-plus, qwen3.5-omni-plus-2026-03-15, qwen3.5-omni-flash, qwen3.5-omni-flash-2026-03-15 (a estratégia de pesquisa deve ser definida como agent)
    • Qwen-Omni-Realtime: qwen3.5-omni-plus-realtime, qwen3.5-omni-plus-realtime-2026-03-15, qwen3.5-omni-flash-realtime, qwen3.5-omni-flash-realtime-2026-03-15 (a estratégia de pesquisa deve ser definida como agent)
  • Modelos de terceiros
    • DeepSeek: deepseek-v4-pro, deepseek-v4-pro-0813, deepseek-v4-flash, deepseek-v4-flash-0731, deepseek-v3.2 (a série deepseek-v4 também suporta a Responses API)
    • GLM: glm-5.2 (suportado apenas pela Responses API)
    • Kimi: kimi-k3 (suportado apenas pela Responses API)

Início rápido

Os exemplos a seguir mostram como consultar informações sobre ações utilizando a pesquisa na web.
  • OpenAI compatible
  • DashScope
O protocolo compatível com OpenAI não oferece suporte ao retorno de fontes de pesquisa na resposta.
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # If the environment variable is not set, provide your Model Studio API key directly, for example: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following configuration is for the Asia Pacific SE 1 (Singapore) region. Replace {WorkspaceId} with your workspace ID. Configurations differ by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the stock price of Alibaba?"},
    ],
    extra_body={
        "enable_search": True,
        "search_options": {
            # Specify the web search strategy. Only 'agent' is supported.
            "search_strategy": "agent"
        }
    }
)
print(completion.choices[0].message.content)
Resposta de exemplo 
According to the latest market data, Alibaba's stock price in different markets is as follows:

*   US Stock (BABA): The latest price is approximately 159.84 USD.
*   Hong Kong Stock (09988.HK): The latest price is approximately 158.00 HKD.

Please note that stock prices fluctuate in real time, and this information is for reference only.

Pesquisa na web com a Responses API

Para ativar a pesquisa na web, adicione a ferramenta web_search ao array tools do parâmetro tools.
Este recurso é suportado apenas pelos seguintes modelos: modelos das séries Qwen3.8, Qwen3.7 e Qwen3.5 (incluindo modelos open-source, mas não os modelos Omni), séries Qwen3.6-Plus e Qwen3.6-Flash, e qwen3.6-35b-a3b; qwen3-max e qwen3-max-2026-01-23; deepseek-v4-flash, deepseek-v4-flash-0731, deepseek-v4-pro, deepseek-v4-pro-0813; glm-5.2; e kimi-k3.
Para obter melhores resultados, recomendamos ativar conjuntamente as ferramentas web_search , web_extractor e code_interpreter .
Para instruções de uso, exemplos de código e guias de migração da Responses API, consulte OpenAI-compatible - Responses . 
from openai import OpenAI
import os

client = OpenAI(
    # If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. Configurations vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

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

print("="*20 + "Response content" + "="*20)
print(response.output_text)

print("="*20 + "Tool call count" + "="*20)
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)}")
# Uncomment the following lines to view the intermediate output
# for r in response.output:
#     print(r.model_dump_json())

Obter fontes de pesquisa

Após a execução de uma pesquisa na web, as fontes são retornadas na resposta. Elas aparecem no elemento cujo type é web_search_call dentro do array output, e seu campo action.sources contém a lista de links de origem. Extraia esses dados do objeto response no exemplo acima da seguinte forma:
A Responses API não suporta os parâmetros enable_source , enable_citation ou citation_format , e não insere marcadores de citação como [1] no conteúdo da resposta. Para utilizar 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}")

Faturamento

A pesquisa na web descrita neste tópico refere-se ao recurso integrado do modelo, cuja cobrança segue as regras abaixo e não inclui cota gratuita de chamadas. Esse recurso é distinto do serviço Web Search MCP disponível no marketplace MCP do Model Studio, sendo ambos faturados independentemente: o serviço Web Search MCP oferece uma cota gratuita de 2.000 chamadas para todos os usuários e, após esse limite, cobra CNY 29 por 1.000 chamadas. Para mais informações, consulte Add web search MCP.
As cobranças pela pesquisa na web consistem em dois componentes:
  • Taxas de chamada do modelo: O recurso de pesquisa na web anexa o conteúdo web recuperado ao prompt, aumentando o número de tokens de entrada. Esses tokens são cobrados à tarifa padrão do modelo. Para detalhes de preços, consulte o console do Model Studio. Ao usar a Responses API, a ferramenta de pesquisa na web é cobrada à mesma taxa da política agent.
  • Taxas da política de pesquisa:
    • Política agent:
      • A taxa por 1.000 chamadas é a seguinte:
        • Para a região China (Beijing): $0.573411.
        • Para a região Singapore: $10.00.
    • Política agent_max (Oferta por tempo limitado): Esta política abrange tanto a pesquisa na web quanto a ferramenta web extractor.
      • Taxa por 1.000 chamadas para a ferramenta de pesquisa na web:
        • Para o escopo de implantação China (Beijing): $0.573411.
        • Para a região Singapore: $10.00.
      • A ferramenta web extractor é gratuita por tempo limitado.

Mensagens de erro

Para solucionar erros, consulte Error codes.
Começar
Faturamento
Plano de Tokens
Playground de Modelos
Clientes e Ferramentas de Desenvolvedor
Inferência do Modelo
Ajuste fino
Implantação
Avaliação
Compressão de Modelos
Estatísticas e Monitoramento
Segurança e Conformidade
Melhores Práticas
Suporte
Registro de alterações