Qwen-Deep-Research API 参考

POST

/api/v1/services/aigc/text-generation/generation

import os
import dashscope

# 第一步：模型反问确认
messages = [{'role': 'user', 'content': '研究一下人工智能在教育中的应用'}]

responses = dashscope.Generation.call(
  api_key=os.getenv('DASHSCOPE_API_KEY'),
  model='qwen-deep-research',
  messages=messages,
  stream=True
)

# 获取模型反问内容
step1_content = ''
for response in responses:
  if hasattr(response, 'output') and response.output:
    message = response.output.get('message', {})
    content = message.get('content', '')
    if content:
      step1_content += content
      print(content, end='', flush=True)

# 第二步：深入研究
messages = [
  {'role': 'user', 'content': '研究一下人工智能在教育中的应用'},
  {'role': 'assistant', 'content': step1_content},
  {'role': 'user', 'content': '我主要关注个性化学习和智能评估这两个方面'}
]

responses = dashscope.Generation.call(
  api_key=os.getenv('DASHSCOPE_API_KEY'),
  model='qwen-deep-research',
  messages=messages,
  stream=True
)

for response in responses:
  if hasattr(response, 'output') and response.output:
    message = response.output.get('message', {})
    content = message.get('content', '')
    if content:
      print(content, end='', flush=True)

{
  "status_code": 200,
  "request_id": "2a6187f0-7e7b-40bb-a87e-xxx",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": null,
    "message": {
      "phase": "answer",
      "role": "assistant",
      "content": "根据研究分析，人工智能在教育领域的应用主要体现在以下几个方面...",
      "extra": {
        "deep_research": {
          "references": [
            {
              "icon": "",
              "index_number": 1,
              "description": "AI 在个性化学习中的应用研究",
              "title": "人工智能与教育变革",
              "url": "https://example.com/ai-education"
            }
          ]
        }
      },
      "status": "typing"
    },
    "fininshed": false,
    "fininshed_reason": "null"
  },
  "usage": {
    "input_tokens": 694,
    "output_tokens": 128
  }
}

模型当前仅支持通过 DashScope SDK（Python）和 HTTP API 调用，暂不支持 Java SDK 与 OpenAI 兼容接口。
如需通过 HTTP 实现流式输出，请添加 X-DashScope-SSE: enable 请求头。

调用流程

Qwen-Deep-Research 采用两步式调用流程：

反问确认：发送用户研究主题，模型返回澄清式问题帮助聚焦方向。
深入研究：将原始问题、模型反问、用户回答作为多轮对话发送，模型执行深度搜索并生成研究报告。

设置 parameters.enable_feedback 为 false 可跳过第一步，直接进入研究流程。

流式响应阶段

通过 X-DashScope-SSE: enable 请求头启用流式输出后，响应按以下阶段依次返回：

{
  "output": {
    "message": {
      "phase": "ResearchPlanning",
      "role": "assistant",
      "content": "",
      "extra": { "deep_research": {} },
      "status": "typing"
    },
    "fininshed": false,
    "fininshed_reason": "null"
  },
  "usage": { "input_tokens": 694, "output_tokens": 0 }
}

模型版本差异

特性	qwen-deep-research	qwen-deep-research-2025-12-15
`enable_feedback`	支持	支持
`research_tools`（MCP）	不支持	支持
WebResearch 阶段 status	`streamingQueries` / `streamingWebResult`	`streamingThinking`（合并了前两者）

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

请求体

application/json

enum<string>

必填

模型名称。

可选值：qwen-deep-research,qwen-deep-research-2025-12-15

object

必填

输入信息。

显示子属性

(用户消息 · object | 助手消息 · object)[]

必填

传递给大模型的上下文，按对话顺序排列。

用户消息，用于向模型传递研究主题或回答模型的澄清式问题。

用户消息
助手消息

显示子属性

enum<string>

必填

固定为 user。

可选值：user

文本输入

必填

消息内容。支持两种格式：

文本输入：直接传入字符串。
图片输入：使用数组格式，包含 {"image": "图片URL或Base64编码"} 和 {"text": "文本描述"} 对象。支持 JPEG、PNG、BMP、WEBP 格式，单张不超过 10MB，单次请求最多 5 张图片。

enum<string>

默认值"model_detailed_report"

指定输出研究报告的格式和详细程度。

model_detailed_report（默认）：结构完整、内容详尽的深度研究报告，篇幅约 6000 Token。
model_summary_report：核心观点突出、内容精炼的摘要式研究报告，篇幅约 1500-2000 Token。

可选值：model_detailed_report,model_summary_report

object

模型调用参数。

显示子属性

boolean

默认值true

是否启用反问确认。设为 false 可跳过反问确认阶段，模型将直接进入研究流程。默认为 true。两个模型均支持此参数。

object[]

MCP（Model Context Protocol）工具配置。通过此参数可接入外部 MCP Server，使模型在研究过程中调用指定工具进行信息检索。仅 qwen-deep-research-2025-12-15 模型支持。

显示子属性

enum<string>

必填

工具类型，当前仅支持 mcp。

可选值：mcp

string

必填

MCP Server 标签，用于标识不同的 MCP 服务。

string

必填

MCP Server 的服务地址。

string[]

必填

允许调用的工具列表，如 ["search", "fetch"]。

boolean

是否开启鉴权。

object

鉴权参数，支持 bearer 和 oauth 两种方式。

显示子属性

string

Bearer Token（JWT）。

object

OAuth 鉴权参数。

响应

200-application/json

integer

请求状态码。200 表示请求成功，否则表示请求失败。调用失败会抛出异常，异常信息为 status_code 和 message 的内容。

string

本次调用的唯一标识符。

string

错误码，调用成功时为空值。仅 Python SDK 返回该参数。

string

错误提示信息，调用成功时为空值。

object

调用结果信息。

显示子属性

string | null

当前固定为 null。

enum<string> | null

模型结束生成的原因。正在生成时为 null；模型输出自然结束为 stop；因生成长度过长而结束为 length。

可选值：stop,length

object[] | null

模型的输出信息。

显示子属性

enum<string> | null

正在生成时为 null；模型输出自然结束为 stop；因生成长度过长而结束为 length。

可选值：stop,length

object

模型输出的消息对象。

显示子属性

enum<string>

当前所处阶段。

ResearchPlanning：研究规划阶段
WebResearch：网络搜索阶段
KeepAlive：连接保持阶段
answer：反问确认与回答阶段

可选值：ResearchPlanning,WebResearch,KeepAlive,answer

enum<string>

输出消息的角色，固定为 assistant。

可选值：assistant

string

模型的输出内容。

object

模型获取的网络搜索与参考信息。

显示子属性

object

仅在 answer 与 WebResearch 阶段包含获取的网络搜索与参考信息，其余阶段均为空对象。

显示子属性

object

模型的研究过程与内容信息（仅 WebResearch 阶段）。

显示子属性

string

研究目标。

string

研究过程中的搜索内容。

integer

搜索的轮数，取值范围 [1-15]。

取值范围：1 <= x <= 15

object

从调用工具总结获取到的内容，和调用工具相关联。

object[]

模型生成答案所引用的内容（仅 answer 阶段）。

显示子属性

string

参考内容 URL 的网页图标链接。

integer

参考内容的索引。

string

参考内容的简介。

string

参考内容的网页标题。

string

参考内容的网页 URL。

object[]

模型研究过程中所参考的内容（仅 WebResearch 阶段）。

显示子属性

string

参考内容 URL 的网页图标链接。

integer

参考内容的索引。

string

参考内容的简介。

string

参考内容的网页标题。

string

参考内容的网页 URL。

enum<string>

模型输出过程中不同阶段的状态。

typing：正在生成该阶段内容
finished：阶段已完成
streamingThinking：正在拆解研究任务并总结网页内容（仅 qwen-deep-research-2025-12-15，替代 streamingQueries 和 streamingWebResult）
streamingQueries：正在生成研究目标和搜索查询（仅 qwen-deep-research）
streamingWebResult：正在执行搜索、网页阅读和代码执行（仅 qwen-deep-research）
WebResultFinished：单轮搜索结束

可选值：typing,finished,streamingThinking,streamingQueries,streamingWebResult,WebResultFinished

boolean

标识模型的内容流式输出是否已全部完成。输出中为 false，全部完成时为 true。注意：字段名为 fininshed，这是 API 返回的实际拼写。

string | null

标识模型的内容流式输出结束的原因。正在生成时为 null；自然结束为 stop。注意：字段名为 fininshed_reason，这是 API 返回的实际拼写。

object

本次请求使用的 Token 信息。

显示子属性

integer

输入 Token 数。

integer

输出 Token 数。

​调用流程

​流式响应阶段

​模型版本差异

鉴权

请求体

响应

调用流程

流式响应阶段

模型版本差异