工具调用

网页抓取

抓取 URL 内容作为上下文

涉及数学计算或数据分析的任务，建议同时启用 code_interpreter 和 Web extractor，以提升准确性。

快速开始

通过 Responses API 调用 Web extractor 来摘要网页内容。以下示例使用 web_search 和 web_extractor，搭配 qwen3-max-2026-01-23 的思考模式。

Python
Node.js
curl

import os
from openai import OpenAI

client = OpenAI(
  # 如果未配置环境变量，请替换为：api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1"
)

response = client.responses.create(
  model="qwen3-max-2026-01-23",
  input="请访问千问云官方文档，找到代码解释器主题并进行总结",
  tools=[
    {"type": "web_search"},
    {"type": "web_extractor"}
  ],
  extra_body={
    "enable_thinking": True
  }
)

# 取消注释可查看中间输出
# print(response.output)
print("=" * 20 + "Response" + "=" * 20)
print(response.output_text)

# 打印工具调用次数
usage = response.usage
print("=" * 20 + "Tool Invocation Count" + "=" * 20)
if hasattr(usage, 'x_tools') and usage.x_tools:
  print(f"Web Extractor invocations: {usage.x_tools.get('web_extractor', {}).get('count', 0)}")

import OpenAI from "openai";
import process from 'process';

const openai = new OpenAI({
  // 如果未配置环境变量，请替换为：apiKey: "sk-xxx"
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1"
});

async function main() {
  const response = await openai.responses.create({
    model: "qwen3-max-2026-01-23",
    input: "请访问千问云官方文档，找到代码解释器主题并进行总结",
    tools: [
      { type: "web_search" },
      { type: "web_extractor" }
    ],
    enable_thinking: true
  });

  console.log("====================Response====================");
  console.log(response.output_text);

  // 打印工具调用次数
  console.log("====================Tool Invocation Count====================");
  if (response.usage && response.usage.x_tools) {
    console.log(`Web Extractor invocations: ${response.usage.x_tools.web_extractor?.count || 0}`);
    console.log(`Web Search invocations: ${response.usage.x_tools.web_search?.count || 0}`);
  }
  // 取消注释可查看中间输出
  // console.log(JSON.stringify(response.output[0], null, 2));
}

main();

curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "qwen3-max-2026-01-23",
  "input": "请访问千问云官方文档，找到代码解释器主题并进行总结",
  "tools": [
    {"type": "web_search"},
    {"type": "web_extractor"}
  ],
  "enable_thinking": true
}'

响应结构

响应包含模型生成的文本及工具使用的元数据。

字段	说明
`output_text`	模型基于提取的网页内容生成的最终文本响应
`output[]`	中间结果数组，包含 `web_extractor_call` 对象（每个对象含 `goal` 和 `output` 字段，分别表示抓取的 URL 和提取的内容）
`usage.x_tools.web_extractor.count`	本次请求中 Web extractor 的调用次数
`usage.x_tools.web_search.count`	本次请求中 Web search 的调用次数

工作原理

在 API 请求的 tools 数组中添加 web_extractor（通常同时添加 web_search），并在 prompt 中引用 URL 或主题。
模型自动判断需要抓取的页面，获取页面内容，并将其作为额外的输入 token 追加到上下文中。
模型基于获取的内容生成响应。

提取的网页内容会增加输入 token 数，影响计费。详见计费。

使用场景

场景	工具配置	原因
回答关于特定 URL 的问题	`web_extractor`（可选搭配 `web_search`）	模型抓取并阅读完整页面内容，而非仅搜索摘要
主题研究，搜索多个网页	`web_search` + `web_extractor`	`web_search` 查找相关页面；`web_extractor` 读取完整内容
快速事实查询（无特定 URL）	仅 `web_search`	搜索摘要通常足够，更经济高效

当需要模型阅读页面的实际内容（而非搜索结果摘要）时，使用 web_extractor。

调用方式

Web extractor 支持三种 API。Responses API 提供最精细的工具控制能力，建议新项目优先使用。

API	工具配置	是否必须流式	备注
Responses API（推荐）	在 `tools` 中添加 `web_search` 和 `web_extractor`	否	支持中间工具执行状态
Chat Completions API	设置 `enable_search: true`，`search_strategy: "agent_max"`	是	不支持非流式
DashScope API	设置 `enable_search: true`，`search_strategy: "agent_max"`	是	不支持 Java SDK

使用 qwen3-max-2026-01-23 时，需将 enable_thinking 设为 true。

Responses API
Chat Completions API
DashScope API

response = client.responses.create(
  model="qwen3-max-2026-01-23",
  input="总结 https://example.com/article 的内容",
  tools=[
    {"type": "web_search"},
    {"type": "web_extractor"}
  ],
  extra_body={
    "enable_thinking": True
  }
)

函数调用的唯一标识符。仅当 type 为 function_call 时存在此字段。返回函数调用结果时，必须使用此 ID 关联请求与响应。

"qwen3-max-2026-01-23",
  messages=[{"role": "user", "content": "总结 https://example.com/article 的内容"}],
  extra_body={
    "enable_thinking": True,
    "enable_search": True,
    "search_options": {"search_strategy": "agent_max"}
  },
  stream=True
)

消息内容数组。仅当 type 为 message 时存在此字段。

显示子属性

from dashscope import Generation

response = Generation.call(
  model="qwen3-max-2026-01-23",
  messages=[{"role": "user", "content": "总结 https://example.com/article 的内容"}],
  enable_search=True,
  search_options={"search_strategy": "agent_max"},
  enable_thinking=True,
  result_format="message"enum<string>

内容类型。值为 output_text。

可选值：output_text

string

模型生成的文本内容。

,
  stream=True,
  incremental_output=True
)

流式输出 Web extractor 事件

流式输出的通用概念（SSE 协议、启用方式、token 用量）请参阅流式输出。本节仅介绍 Web extractor 特有的事件类型。

网页抓取可能需要一定时间。使用流式输出可以实时接收推理步骤、工具调用和响应文本。Responses API 支持暴露每个工具调用的中间执行状态，是流式场景的最佳选择。使用 Responses API 进行流式输出时，以下事件类型表示提取和生成流程的各个阶段：

object[]

文本注释数组。通常为空数组。

object[]

事件类型	说明
`response.reasoning_summary_text.delta`	模型思考过程的增量推理文本
`response.output_item.done`	工具调用已完成。检查 `item.type` 是否为 `web_extractor_call` 以获取提取结果
`response.output_text.delta`	增量响应文本
`response.completed`	响应完成。`usage` 字段包含工具调用次数

处理流中的 web_extractor_call 事件时，检查事件类型并读取其 goal 和 output 字段：

for chunk in stream:
  if chunk.type == 'response.output_item.done':
推理摘要数组。仅当 type 为 reasoning 时存在此字段。每个元素包含 type 字段（值为 summary_text）和 text 字段（包含摘要文本）。

显示子属性

enum<string>

    if hasattr(chunk, 'item') and chunk.item.type == 'web_extractor_call':
      print(f"已抓取: {chunk.item.goal}")
      print(f"内容: {chunk.item.output}")
  elif chunk.type == 'response.output_text.delta':
    print(chunk.delta, end='', flush=True)
  elif chunk.type == 'response.completed':
    usage = chunk.response.usage
    if hasattr(usage, 'x_tools') and usage.x_tools:
      print(f可选值：summary_text

string

{usage.x_tools.get('web_extractor', {}).get('count', 0)}")

支持的模型

模型系列	模型 ID
Qwen-Max	`qwen3-max`、`qwen3-max-2026-01-23`（思考模式）
Qwen-Plus	`qwen3.6-plus`、`qwen3.6-plus-2026-04-02`、`qwen3.5-plus`、`qwen3.5-plus-2026-02-15`
Qwen-Flash	`qwen3.5-flash`、`qwen3.5-flash-2026-02-23`
Qwen 开源系列	`qwen3.5-397b-a17b`、`qwen3.5-122b-a10b`、`qwen3.5-27b`、`qwen3.5-35b-a3b`

object

搜索动作信息。仅当 type 为 web_search_call 时存在此字段。

显示子属性

使用限制

Web extractor 仅能获取公开可访问的页面。需要登录认证或付费的页面返回空内容。
过大的页面可能在添加到上下文窗口前被截断。
纯 JavaScript 渲染的动态内容可能无法完整获取。
提取的内容作为输入 token 计算，大页面会增加延迟和成本。

错误处理

提取失败时，模型不会抛出错误。响应输出中的 web_extractor_call 项会返回空或部分内容，模型基于已有上下文生成响应。常见的失败场景：

场景	行为
URL 不可达（404、500、DNS 解析失败）	提取返回空内容；模型使用其他可用上下文生成响应
页面加载超时	返回部分或空内容
非 HTML 内容（PDF、图片）	可能无法提取内容；模型回退到其他工具或通用知识

要验证提取是否成功�ight" data-component-part="field-name" type="button">output.action.query

string

搜索查询关键词。

enum<string>

搜索类型。值为 search。

可选值：search

计费 Web extractor 的费用包含两部分：

组成部分	详情
模型费用	提取的网页内容追加到 prompt 中，增加输入 token 数，按模型标准 token 价格计费。详见定价。
联网搜索费用	每 1,000 次调用 4 元。使用网页抓取需同时开启联网搜索，联网搜索会独立计费。
Web extractor 费用	限时免费。

搜索来源列表。每个元素包含 type 字段和 url 字段。

显示子属性

本页目录

快速开始
响应结构
工作原理
使用场景

string

调用方式

流式输出 Web extractor 事件

string

模型生成并执行的代码。仅当 type 为 code_interpreter_call 时存在此字段。

文档

代码执行输出数组。仅当 type 为 code_interpreter_call 时存在此字段。每个元素包含 type 字段（值为 logs）和 logs 字段（包含代码执行日志）。

显示子属性

可选值：logs

string

模型

string

代码解释器容器的标识符。仅当 type 为 code_interpreter_call 时存在此字段。用于在同一会话中关联多次代码执行。

提取目标的描述，说明需要从网页中提取哪些信息。仅当 type 为 web_extractor_call 时存在此字段。

string

工具调用的输出结果，为字符串格式。

当 type 为 web_extractor_call 时，为提取的网页内容摘要。
当 type 为 web_search_image_call 或 image_search_call 时，为包含图片搜索结果数组的 JSON 字符串。每个元素包含 title 字段（图片标题）、url 字段（图片 URL）和 index 字段（序号）。
当 type 为 mcp_call 时，为 MCP 服务返回的 JSON 字符串结果。