跳转到主要内容
工具调用

联网搜索

让模型响应基于实时网络数据——查询天气、股票价格、近期新闻等训练数据截止日期后的内容。

由于训练数据的时效性限制,大模型无法准确回答股票价格、明日天气等实时问题,启用联网搜索后,模型将基于实时检索数据回复。
调用 API 前,请先获取 API Key将其设置为环境变量

快速开始

  • OpenAI 兼容 - Chat Completions
  • OpenAI 兼容 - Responses API
  • DashScope
通过 enable_search: true 参数启用联网搜索。Python SDK 通过 extra_body 传入,Node.js SDK 作为顶层参数传入。
import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
  model="qwen3-max",
  messages=[{"role": "user", "content": "杭州明天天气如何"}],
  extra_body={"enable_search": True}
)
print(completion.choices[0].message.content)

支持的模型

中国内地

千问系列
模型系列可用模型
Qwen3.6 Maxqwen3.6-max-preview
Qwen3 Maxqwen3-max、qwen3-max-2025-09-23 及之后版本、qwen3-max-preview
Qwen3.6 Plusqwen3.6-plus、qwen3.6-plus-2026-04-02 及之后版本(仅 Responses API)
Qwen3.5 Plusqwen3.5-plus、qwen3.5-plus-2026-02-15 及之后版本
Qwen3.6 Flashqwen3.6-flash、qwen3.6-flash-2026-04-16 及之后版本(仅 Responses API)
Qwen3.5 Flashqwen3.5-flash、qwen3.5-flash-2026-02-23 及之后版本
Qwen Maxqwen-max、qwen-max-latest、qwen-max-2024-09-19 及之后版本
Qwen Plusqwen-plus、qwen-plus-latest、qwen-plus-2025-07-14 及之后版本
Qwen Flashqwen-flash、qwen-flash-2025-07-28 及之后版本
Qwen Turboqwen-turbo、qwen-turbo-latest、qwen-turbo-2025-07-15
QwQqwq-plus
Qwen Omniqwen3.5-omni-plus、qwen3.5-omni-plus-2026-03-15、qwen3.5-omni-flash、qwen3.5-omni-flash-2026-03-15
Qwen Omni Realtimeqwen3.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
角色扮演qwen-plus-character、qwen-flash-character、qwen-flash-character-2026-02-26
2025 年 7 月后发布的 Qwen Max、Qwen Plus、Qwen Flash 模型自动支持联网搜索。第三方模型
提供商可用模型
DeepSeekdeepseek-v4-pro、deepseek-v4-flash、deepseek-v3.2、deepseek-v3.2-exp、deepseek-v3.1、deepseek-r1-0528、deepseek-r1、deepseek-v3
KimiMoonshot-Kimi-K2-Instruct
MiniMaxMiniMax-M2.1
Qwen Plus:qwen3.6-plus、qwen3.6-plus-2026-04-02 及之后版本(仅 Responses API);qwen3.5-plus、qwen3.5-plus-2026-02-15 及之后版本Qwen Flash:qwen3.5-flash、qwen3.5-flash-2026-02-23 及之后版本;qwen3.6-flash、qwen3.6-flash-2026-04-16 及之后版本(仅 Responses API)国际站 qwen3-max 和 qwen3-max-2026-01-23 需将 search_strategy 设为 agent(非思考模式)或 agent_max(思考模式)。

核心能力

除基础搜索外,联网搜索还支持以下高级功能。DashScope 协议支持所有功能;OpenAI 兼容协议(Chat Completions)不支持返回搜索来源、角标标注等功能。
功能DashScopeOpenAI 兼容-ChatOpenAI 兼容-Responses
基础联网搜索支持支持支持
强制联网搜索支持支持不支持
设置搜索量级策略支持支持不支持
垂域搜索支持支持不支持
搜索时效性支持支持不支持
限定来源站点支持支持不支持
自然语言控制检索范围支持支持不支持
返回搜索来源支持不支持不支持
角标引用标注支持不支持不支持
提前返回搜索来源支持不支持不支持
图文混合输出支持支持不支持

搜索量级策略

通过 search_options 中的 search_strategy 字段控制搜索行为:
  • turbo(默认):兼顾响应速度与搜索效果,适用于大多数场景。
  • max:调用多源搜索引擎,结果更详尽,响应时间更长。
  • agent:多轮信息检索与整合,模型自主决定搜索时机和频次,适合复杂查询和英文场景。启用时仅支持 enable_source,其他联网搜索功能不可用,每次调用额外收费。
  • agent_max:在 agent 基础上支持网页全文阅读。仅 qwen3-max、qwen3-max-2026-01-23 思考模式可用,每次调用额外收费。
  • OpenAI 兼容
  • DashScope
Python
extra_body={
  "enable_search": True,
  "search_options": {
    "search_strategy": "max"  # turbo(默认)/ max / agent / agent_max
  }
}

强制联网搜索

默认情况下,模型会自行判断是否联网。设置 forced_search: true 可强制执行搜索,适用于强依赖实时信息的场景。
  • OpenAI 兼容
  • DashScope
Python
extra_body={
  "enable_search": True,
  "search_options": {"forced_search": True}
}

获取搜索来源与引用标注

仅 DashScope 协议支持返回搜索来源和角标标注。
  1. 返回搜索来源:设置 enable_source: true,响应的 search_info.search_results 包含来源列表,每项含 indextitleurl
  2. 角标标注:在 enable_source: true 的前提下,设置 enable_citation: true,回复正文中出现 [1] 等角标。
  3. 角标样式:通过 citation_format 设置,可选 "[<number>]"(默认)或 "[ref_<number>]"
import os
import dashscope

response = dashscope.Generation.call(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  model="qwen-plus",
  messages=[{"role": "user", "content": "杭州明天天气是什么?"}],
  enable_search=True,
  search_options={
    "enable_source": True,
    "enable_citation": True,
    "citation_format": "[ref_<number>]"
  },
  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)

垂域搜索

设置 enable_search_extension: true 可为天气、股票等结构化查询检索垂直领域数据,比通用搜索结果更精准。DashScope Java SDK 不支持此参数。
领域说明示例
天气实时、未来及历史天气杭州天气
股票A 股、港股、美股实时/历史行情沪指昨天收盘点数
汇率多币种最新汇率人民币与美元的汇率
油价全国各地最新汽柴油价格杭州油价
万年历农历、节气、吉凶宜忌今天是农历几号
金价 / 银价最新及历史行情金价多少钱了
彩票双色球、大乐透等开奖结果最新一期双色球开奖结果
电视剧 / 电影主流平台最新资讯近期热播电视剧
车牌限行根据车牌号查询当日限行浙Axxxxxx,今天是否在杭州限行
足球赛事英超、西甲等赛程与积分榜英超现在哪支球队排名第一
  • OpenAI 兼容
  • DashScope
Python
extra_body={
  "enable_search": True,
  "search_options": {"enable_search_extension": True}
}

搜索时效性

通过 freshness 参数限制搜索来源的时间范围,过滤超出范围的历史网页。仅对 search_strategy: turbo 生效。 可选值730180365(天数);不设置则不限制时间范围。 支持的模型:qwen3-max、qwen3-max-preview、qwen3-max-2025-09-23、qwen-plus、qwen-flash、qwen-plus-character、qwen-flash-character、qwen-flash-character-2026-02-26
  • OpenAI 兼容
  • DashScope
Python
extra_body={
  "enable_search": True,
  "search_options": {
    "search_strategy": "turbo",
    "freshness": 7  # 仅检索最近 7 天内的内容
  }
}

限定来源站点

通过 assigned_site_list 将搜索限定在指定网站列表,最多配置 25 个站点。仅对 search_strategy: turbo 生效。当指定站点内无相关内容时,模型将使用自身知识回答。
DashScope Java SDK 不支持此参数。
支持的模型:qwen3-max、qwen3-max-preview、qwen3-max-2025-09-23、qwen-plus、qwen-flash 及角色扮演模型。
  • OpenAI 兼容
  • DashScope
Python
extra_body={
  "enable_search": True,
  "search_options": {
    "search_strategy": "turbo",
    "assigned_site_list": ["baidu.com", "sina.cn"]
  }
}

自然语言控制检索范围

通过 prompt_intervene 参数用自然语言引导搜索方向,适用于限定主题或地域的场景。 支持的模型:qwen3-max、qwen3-max-preview、qwen3-max-2025-09-23、qwen-plus、qwen-flash 及角色扮演模型。DashScope Java SDK 不支持此参数。
  • OpenAI 兼容
  • DashScope
Python
extra_body={
  "enable_search": True,
  "search_options": {
    "search_strategy": "turbo",
    "intention_options": {
      "prompt_intervene": "仅检索AI技术相关内容"
    }
  }
}

提前返回搜索来源

仅支持 DashScope 流式调用(不支持 OpenAI 兼容协议和 Java SDK)。在流式场景下,从获取搜索结果到生成首个 token 通常有 0.5 秒以上的延迟。设置 prepend_search_result: true 可在获取到搜索结果后立刻将其作为首个数据包返回,降低首包延时。
Python
import os
import dashscope

responses = dashscope.Generation.call(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  model="qwen-plus",
  messages=[{"role": "user", "content": "杭州明天天气是什么?"}],
  enable_search=True,
  search_options={
    "enable_source": True,
    "prepend_search_result": True  # 首包仅包含搜索来源
  },
  result_format="message",
  stream=True,
  incremental_output=True
)

first_chunk = True
for resp in responses:
  if first_chunk:
    search_info = resp.output.get("search_info", {})
    if search_info:
      print(f"已阅读 {len(search_info['search_results'])} 个页面")
      for web in search_info["search_results"]:
        print(f"[{web['index']}]: [{web['title']}]({web['url']})")
      first_chunk = False
  content = resp.output.choices[0].message.content
  print(content, end="")

图文混合输出

设置 enable_text_image_mixed: true 可让模型在回复中嵌入相关图片(以 HTML <img> 标签形式)。此参数与 enable_search 相互独立,无需同时启用。DashScope Java SDK 不支持此参数。 支持的模型:qwen-max、qwen-plus-latest、qwen-flash
  • OpenAI 兼容
  • DashScope
Python
completion = client.chat.completions.create(
  model="qwen-plus-latest",
  messages=[{"role": "user", "content": "介绍一下杭州西湖"}],
  extra_body={"enable_text_image_mixed": True}
)

深度思考 + 联网搜索

联网搜索可与深度思考模式结合使用,适合行业趋势分析、多源信息整合等复杂任务。模型获取检索内容后先推理再生成回复,用户可观察推理路径。 支持联网搜索的深度思考模型
  • 千问:qwen3-max、qwen3-max-2026-01-23、qwen3-max-preview、qwen-plus、qwen-plus-latest、qwen-flash、qwen-turbo、qwq-plus
  • DeepSeek:deepseek-v4-pro、deepseek-v4-flash、deepseek-v3.2、deepseek-v3.2-exp、deepseek-v3.1、deepseek-r1-0528、deepseek-r1
import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
  model="qwen-plus",
  messages=[{"role": "user", "content": "结合近期AI热点新闻,预测AI的发展趋势"}],
  extra_body={
    "enable_thinking": True,
    "enable_search": True,
    "search_options": {
      "forced_search": True,
      "search_strategy": "max"
    }
  },
  stream=True,
  stream_options={"include_usage": True}
)

is_answering = False
for chunk in completion:
  if not chunk.choices:
    print(chunk.usage)
    continue
  delta = chunk.choices[0].delta
  if hasattr(delta, "reasoning_content") and delta.reasoning_content:
    print(delta.reasoning_content, end="", flush=True)
  elif delta.content:
    if not is_answering:
      print("\n--- 回复 ---")
      is_answering = True
    print(delta.content, end="", flush=True)

计费

计费涉及两个方面:
  • 模型调用费用:联网搜索获取的网页内容会追加到 prompt 中,增加输入 token 数量,按模型标准价格计费。详见计费说明
  • 搜索调用费用(每 1,000 次):
    策略(search_strategy功能费用
    turbo(默认)兼顾速度与效果3元
    max多源搜索,结果更全面4元
    agent多轮检索与信息整合4元
    agent_max搜索 + 网页提取器阅读全文搜索 4元;网页抓取限时免费

错误码

如果调用失败,请参阅错误信息