最强DeepResearch！通义DeepResearch-30B开源实战：模型部署+LangGraph+A2A全攻略

DeepResearch（深度研究）是很多专业研究者最依赖的Agent应用之一，不过目前很多DeepResearch或成本较高（Token杀手/高级会员/次数限制），或效果欠佳。

阿里在上个月发布的全开源项目-通义DeepResearch，在多项高难度的研究任务评测中几乎超越了目前所有开源/闭源DeepResearch智能体，包括通用LLM-Based的ReAct智能体，及OpenAI等基于专用LLM的DeepResearch智能体：

最重要的是它底层为一个仅30B的MoE专用DeepResearch推理模型（每次激活3B）— 极小的尺寸取得了极佳的性能，这意味着你只需很低的资源就可以免费部署它！本文将演示如何借助该项目构建一个全本地化的端到端DeepResearch助理。

使用的主要原料：

LLM：Tongyi-DeepResearch-30B-A3B模型
Agent：参考通义DeepResearch开源项目，LangGraph实现
API：FastAPI + A2A协议
前端：CLI工具，Streamlit

【本文源码地址在文末】

快速了解通义DeepResearch项目

通义DeepResearch开源项目既不是一个简单的专用LLM，也不是一个基于通用LLM的Agent范式与实现（大部分开源DeepResearch项目）。其包含两个主要部分：

一个针对研究任务训练与调优的LLM（Tongyi-DeepResearch-30B-A3B）
基于该DeepResearch LLM优化实现的Agent

组成结构如下：

【LLM部分】

即名为Tongyi-DeepResearch-30B-A3B的MoE模型，在Huggingface与Modelscope已经开放权重下载。

该模型是在Qwen开源模型上通过一套新的训练范式与技术，针对长程、深入的信息检索与研究任务进行调优与强化的推理语言模型，最大上下文128K。如果你想深入了解其训练细节，可以阅读其官方技术博客。不过现在你只需要知道，它是一个专门训练用来满足DeepResearch Agent需要的模型：

更擅长生成深度研究的计划，以及更合理的工具（Tools）调用
针对长程任务推理优化，特别是在超长上下文环境中不容易跑偏
针对特殊的Agent范式训练优化，如ReAct；使用定制的tokenizer。

【Agent部分】

Tongyi-DeepResearch模型主要针对两种DeepResearch的Agent范式而训练优化：

ReAct范式

这是广为所知的Agent推理范式，通过执行“思考-行动-观察”的循环来搜集到足够的信息直到完成任务。阿里目前在开源项目中提供了该范式的评测代码，但并未提供可直接调用的Agent API或完整应用代码。

IterResearch范式

也叫Heavy范式。这是该项目中独有的用于处理极端复杂的多步骤、长距离研究任务的模式。其核心思想是引入上下文重构和多 Agent 并行机制：将长任务拆解为一系列连续的“研究回合”，在每回合结束时自动摘要并重组关键信息到下一个回合的上下文中，再决定下一步行动；还可以启动多个 Agent 并行探索不同信息源，最后由一个汇总 Agent 将它们的报告融合得到最终答案。

<图片来自官方>

不过阿里目前还没有在开源项目中放出该范式的实现代码。

IterResearch范式有点类似Google的TTD-DR。参考：谷歌DeepResearch新方法TTD-DR原理与实现 | 原理篇。

模型部署与测试

在开始实现Agent之前，我们首先需要有可以调用的Tongyi-DeepResearch模型推理接口。有以下几种途径：

下载模型权重本地部署

可以在魔搭社区或Huggingface下载模型文件（60G+）

如果资源有限，也可以搜索并选择合适的量化版本下载。模型下载后，使用推理工具启动推理服务（官方推荐vLLM）。

调用OpenRouter API

OpenRouter上有收费和免费(带Free标记）版本的API。免费版本不会输出推理过程，且有次数限制（账户余额>=10$则每天可以免费调用1000次）。

调用Modelscope API-Inference

免费。一般仅用于体验模型，存在次数限制，每天单个模型调用最多500次。

选择哪种方式取决于自己的条件，在调用侧并无太大区别，都是OpenAI-like的API模式，一般修改API_KEY与BASE_URL即可。

由于笔者环境为MacOS，因此选择了LM Studio + 量化版本的本地部署（有条件还是建议使用vLLM+非量化，官方的评测代码中有一键启动脚本）。大致过程为：

下载LMStudio安装->搜索tongyi-deepresearch模型->下载合适量化版本（建议Q5以上）->加载模型并开启Developer Server。API调用说明如下：

用一个cURL命令测试模型是否连通：

如果收到了正确的响应，恭喜你，你的DeepResearch模型已经就绪！

一个重要提醒：即使选择在线API或LMStudio，也需要把官方模型中的tokenizer文件下载到本地，后续Agent需要它来计算上下文大小。

官方模型下载：

modelscope.cn/models/iic/…

ReAct Agent实现与测试

现在准备与Tongyi-DeepResearch模型配合的Agent引擎。

目前阿里放出的开源项目中有ReAct范式的Agent参考实现（qwen_agent框架开发）、及批量测试与评估代码。我们首先需要来理解这个ReAct范式的Agent，特别是其与普通ReAct Agent（通用LLM-Based）的区别。

【下载开源项目】

从Github克隆项目到本地，注意本项目最相关的两个目录是：

inference：ReAct Agent实现、批量测试、启动脚本、输入输出文件格式等
evaluation：各种benchmarks的评估代码，用来评估inference中的测试结果

其中最核心的ReAct Agent代码实现在react_agent.py及tool_xx.py。

【理解ReAct Agent引擎】

研究react_agent.py，可以看到这是一个典型的ReAct推理范式的Agent引擎：通过Tongyi-DeepResearch模型进行工具调用的推理循环，最终完成输入任务。

核心流程

项目中的ReAct Agent使用qwen_agent框架开发。流程如下：

任务结束的条件是以下任意一个：

任务超时：任务失败
超出最大LLM call次数：任务失败
上下文超出设定大小：强制输出答案
LLM输出：输出答案内容

工具集

目前支持的研究工具主要有5个（tool_xxx.py）：

相信这也是Tongyi-DeepResearch在训练中重点学习使用的工具集。其中parse_file只有当输入了供研究的本地文件时才会用到。各工具的实现机制大致为：

search/scholar：调用serper的google搜索/学术搜索API实现
visit：调用jina的Web页面访问API实现，并用LLM总结后返回
PythonInterpreter：借助字节跳动的开源SandboxFusion项目实现
parse_file：根据不同文件类型使用Python库或者多模态模型解析

提示词（Prompt）

系统提示词在prompt.py文件。这是与Tongyi-DeepResearch模型配合的指令，注意到没有类似“Thought...Action...Action Input"这样的ReAct提示。从提示词能看出模型最重要的几个标记Token：

：包含模型推理思考过程
<tool_call/>: 模型推理出的工具调用请求
<tool_response/>：输入模型的工具调用结果
: 当搜集到足够信息后，输出的最终答案

这里的提示显然更简洁，因为推理能力已被内化到模型权重中。

【实现ReAct Agent引擎】

由于我们的目的并非批量评测，因此需要将开源项目中的react_agent简单改造以更适合单次任务调用。不过笔者选择了重新实现一个LangGraph版本的Agent引擎。

注意不要用LangGraph预置的create_react_agent，因为预置模式借助的是Function Calling，而这里不需要。工作流（Graph）编排如下：

为了客户端调用更简洁（并考虑后面A2A Server的使用），我们包装了一个更简洁的调用方法：

async def stream(self, query: str, context_id: str) -> AsyncIterable[Dict[str, Any]]:        """        流式调用工作流。并在不同执行阶段输出中间状态与响应。                参数:            query (str): 用户的深度研究任务            context_id (str): 对话上下文ID，用于保持会话连续性                    返回:            AsyncIterable[Dict[str, Any]]: 异步迭代器，产生包含状态和内容的字典            可能的状态包括:                - "working": Agent 正在思考或执行工具调用                - "completed": 处理完成，包含最终答案                - "failed": 处理失败        """......

详细实现请参考本文附带的源代码（langgraph_react_agent.py）。

【配置ReAct Agent环境】

为了运行测试这个Agent，我们还需要修改与配置必要的环境。包括：

修改Tongyi-DeepResearch模型调用URL

由于采用了本地模型，只需要修改Agent代码中的openai_base_url参数，将其指向你的推理API端点，如http://127.0.0.1:{端口}/v1。

以下配置在.env中修改：

search工具配置

申请serper搜索API Key（serper.dev），配置SERPER_KEY_ID
visit工具配置

申请jina网页访问API Key（jina.ai），配置JINA_API_KEY；另外选择一个用于网页内容总结的通用LLM，配置API_KEY/API_BASE/SUMMARY_MODEL_NAME
file_parse工具配置

申请阿里百炼的API Key，配置DASHSCOPE_API_KEY；文件解析的多模态模型等可保留默认值
python interpreter工具

启动一个SandboxFusion的Docker容器（参考Github的SandboxFusion项目），将Docker调用的API地址配置到SANDBOX_FUSION_ENDPOINT
本地模型的Tokenizer路径

配置MODEL_PATH，指向下载到本地的模型权重目录（如果使用在线API或LLMStudio推理，只需要有tokenizer相关文件即可）

其他的.env中参数可以保留默认值。

【测试ReAct Agent引擎】

现在让AI编写个简单的Agent测试命令行程序。启动测试客户端（test_agent.py）：

观察输出的调试信息，可以看到模型的推理过程，比如调用Search工具：

调用visit工具：

经过若干次推理循环与工具执行，模型输出了最终结果：

可以看到，相对于简单“Web搜索+LLM总结”模式，这里的答案要详细与准确的多。

A2A Server与客户端实现

【实现A2A Server与客户端】

有了测试成功的ReAct范式的Agent引擎，我们希望把这个Agent通过接口给前端调用。这里你有几种选择：

Restful HTTP API：直接调用Agent并发布服务端点
MCP协议：将Agent包装成MCP Tool给客户端调用
A2A协议：将Agent通过A2A Server暴露给客户端

对于这样运行时间较长的Agent，这里选择使用A2A协议：可以利用它天然具备的多任务异步、流输出、服务端通知等能力。

客户端使用CLI程序快速测试，并用Streamlit来构建演示UI应用：

详细实现请参考本文附带的源代码（a2a_xxx.py）。

现在我们可以启动Server与UI来测试这个端到端的深度研究助手。

【端到端测试】

现在已经完整的实现了UI-API-Agent-LLM调用链，让我们做最终的测试。

启动A2A Server

在一个终端执行：

python a2a_server.py

访问http://localhost:10002/.well-known/agent.json查看Agent卡片，验证连通性。

CLI客户端测试

python a2a_client.py

进入交互式程序，输入一个研究任务：

等待任务运行，直到出现完成的状态更新：

Streamlit UI客户端测试：

streamlit run a2a_streamlit_ui.py --server.port 8501

访问http://localhost:8501，进入用户界面。输入一个任务：

可以看到Agent工作过程，借助A2A协议可以轻松的实现任务异步运行（前端退出不影响任务执行），也可以持续观察任务处理过程：

任务完成后，可以看到最终输出的研究结果：

结束语

通义 DeepResearch是一个“专用 LLM + Agent 一体化”的深度研究项目。它不仅以 30B 规模 MoE 架构 实现了超预期的推理性能，更重要的是让我们能够以极低成本，在本地即可部署并运行一个真正可用的 DeepResearch 智能体。

本文完整展示了如何基于该项目构建一套可复现、可扩展、可本地运行的 DeepResearch Agent 系统（ReAct范式）。由于官方未放出IterResearch的代码，这将是更值得期待的版本 — 能显著提升长链式研究与报告生成能力。

根据官方说明，通义DeepResearch仍在快速演进。未来将聚焦：

扩展上下文长度：128K 的上下文仍不足以覆盖最复杂的长周期研究任务
验证模型可扩展性：尝试在更大规模的模型上验证该项目的训练方法
优化强化学习框架：通过部分Rollout等策略提升训练效率等

最后，我们在实际测试中遇到的一些问题供参考：

部分量化版本在推理时不输出标记导致无法识别终止条件
**ReAct模式应该仍偏向Q/A场景，**长篇研究报告还要期待 IterResearch范式
在某些任务中，模型仍可能陷入重复思考或冗余查询，可考虑设置循环上限
OpenRouter AP线上推理接口，需注意输出处理略有差异，参考官方说明
评测程序中使用了多次Rollout来获取最优解，本文未演示与测试

大家在测试时如果有问题，欢迎加入我们一起讨论！