alibaba-nlp--deepresearch/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

---

🤗 HuggingFace ｜ ModelScope | 💬 WeChat(微信) | 📰 Blog | 📑 Paper

👏 欢迎通过 ModelScope 在线演示 或 🤗 HuggingFace 在线演示 或 百炼服务! 体验 Tongyi DeepResearch。

Note

本演示仅供快速体验。由于模型延迟与工具 QPS 限制，响应时间可能波动或间歇性失败。如需稳定体验，建议本地部署；如需可用于生产的服务，请访问 百炼 并按引导完成配置。

简介

我们推出 Tongyi DeepResearch，这是一款智能体（agentic）大语言模型，总参数量 305 亿，每个 token 仅激活 33 亿参数。该模型由通义实验室（Tongyi Lab）开发，专为长程、深度信息检索任务而设计。Tongyi DeepResearch 在多项智能体搜索基准测试中展现出业界领先（state-of-the-art）性能，包括 Humanity's Last Exam、BrowseComp、BrowseComp-ZH、WebWalkerQA、xbench-DeepSearch、FRAMES 和 SimpleQA。

Tongyi DeepResearch 基于我们此前在 WebAgent 项目上的工作构建。

更多详情请参阅我们的 📰 技术博客。

特性

• ⚙️ 全自动合成数据生成流水线：我们设计了一套高度可扩展的数据合成流水线，全程自动化，支撑智能体预训练、监督微调（supervised fine-tuning）与强化学习。
• 🔄 面向智能体数据的大规模持续预训练：利用多样化、高质量的智能体交互数据扩展模型能力、保持时效性并增强推理性能。
• 🔁 端到端强化学习：我们采用基于定制 Group Relative Policy Optimization 框架的严格同策略（on-policy）强化学习方法，结合 token 级策略梯度、留一法（leave-one-out）优势估计，以及对负样本的选择性过滤，以在非平稳环境中稳定训练。
• 🤖 智能体推理范式兼容性：推理时，Tongyi DeepResearch 兼容两种推理范式：ReAct（用于严格评估模型核心内在能力），以及基于 IterResearch 的「Heavy」模式（采用测试时扩展策略以释放模型的最大性能上限）。

模型下载

你可以通过以下链接直接下载模型。

Model	Download Links	Model Size	Context Length
Tongyi-DeepResearch-30B-A3B	🤗 HuggingFace 🤖 ModelScope	30B-A3B	128K

动态

[2025/09/20]🚀 Tongyi-DeepResearch-30B-A3B 现已上线 OpenRouter! 请参阅 快速入门 指南。

[2025/09/17]🔥 我们已发布 Tongyi-DeepResearch-30B-A3B。

Deep Research 基准测试结果

快速入门

本指南介绍如何配置环境，并运行位于 inference 目录下的推理脚本。

1. 环境配置

• 推荐 Python 版本：3.10.0（使用其他版本可能导致依赖问题）。
• 强烈建议使用 conda 或 virtualenv 创建隔离环境。

# Example with Conda
conda create -n react_infer_env python=3.10.0
conda activate react_infer_env

2. 安装

安装所需依赖：

pip install -r requirements.txt

3. 环境配置与准备评估数据

环境配置

通过复制示例环境文件来配置 API 密钥与相关设置：

# Copy the example environment file
cp .env.example .env

编辑 .env 文件，填入实际的 API 密钥与配置值：

• SERPER_KEY_ID：从 Serper.dev 获取密钥，用于网页搜索与 Google Scholar
• JINA_API_KEYS：从 Jina.ai 获取密钥，用于网页阅读
• API_KEY/API_BASE：用于页面摘要的 OpenAI 兼容 API，来自 OpenAI
• DASHSCOPE_API_KEY：从 Dashscope 获取密钥，用于文件解析
• SANDBOX_FUSION_ENDPOINT：Python 解释器沙箱端点（参见 SandboxFusion)
• MODEL_PATH：模型权重路径
• DATASET：评估数据集名称
• OUTPUT_PATH：结果保存目录

Note

：.env 文件已被 gitignore，因此你的密钥不会被提交到仓库。

准备评估数据

系统支持两种输入文件格式：JSON 与 JSONL。

支持的文件格式：

选项 1：JSONL 格式（推荐）

• 创建扩展名为 .jsonl 的数据文件（例如 my_questions.jsonl）
• 每行必须是一个有效的 JSON 对象，包含 question 与 answer 键：

  {"question": "What is the capital of France?", "answer": "Paris"}
  {"question": "Explain quantum computing", "answer": ""}
  

选项 2：JSON 格式

• 使用 .json 扩展名创建数据文件（例如 my_questions.json）
• 文件必须包含一个 JSON 对象数组，每个对象都包含 question 和 answer 键：

  [
    { "question": "What is the capital of France?", "answer": "Paris" },
    { "question": "Explain quantum computing", "answer": "" }
  ]
  

重要说明： answer 字段包含用于评估的标准答案/参考答案（ground truth/reference answer）。系统会自行生成对问题的回答，这些参考答案会在基准评估过程中用于自动评判生成回答的质量。

文档处理的文件引用：

• 如果使用 file parser 工具，请将文件名前置到 question 字段
• 将引用的文件放在 eval_data/file_corpus/ 目录中
• 示例：{"question": "(Uploaded 1 file: ['report.pdf'])\n\nWhat are the key findings?", "answer": "..."}

文件组织：

project_root/
├── eval_data/
│   ├── my_questions.jsonl          # Your evaluation data
│   └── file_corpus/                # Referenced documents
│       ├── report.pdf
│       └── data.xlsx

4. 配置推理脚本

• 打开 run_react_infer.sh，并按注释说明修改以下变量：
  • MODEL_PATH - 本地或远程模型权重的路径。
  • DATASET - 评估文件的完整路径，例如 eval_data/my_questions.jsonl 或 /path/to/my_questions.json。
  • OUTPUT_PATH - 保存预测结果的路径，例如 ./outputs。
• 根据你启用的工具（检索、计算器、网页搜索等），提供所需的 API_KEY、BASE_URL 或其他凭据。每个键在 bash 脚本中都有行内说明。

5. 运行推理脚本

bash run_react_infer.sh

---

完成以上步骤后，你就可以完整准备环境、配置数据集并运行模型。更多细节请参阅各脚本中的行内注释，或提交 issue。

6. 可使用 OpenRouter 的 API 调用我们的模型

Tongyi-DeepResearch-30B-A3B 现已在 OpenRouter. 上线，你可以在不使用任何 GPU 的情况下运行推理。

你需要在文件 inference/react_agent.py: 中修改以下内容：

• 在 call_server 函数中：将 API 密钥和 URL 设置为你的 OpenRouter 账户的 API 与 URL。
• 将模型名称改为 alibaba/tongyi-deepresearch-30b-a3b。
• 按照第 88–90 行注释中的说明，调整内容拼接方式。

基准评估

我们为各类数据集提供了基准评估脚本。更多详情请参阅 evaluation scripts 目录。

常见问题

更多详情请参阅 FAQ。

Deep Research Agent 系列

通义 DeepResearch 还拥有丰富的深度研究智能体（deep research agent）系列。你可以在以下论文中了解更多信息：

[1] WebWalker: Benchmarking LLMs in Web Traversal (ACL 2025)
[2] WebDancer: Towards Autonomous Information Seeking Agency (NeurIPS 2025)
[3] WebSailor: Navigating Super-human Reasoning for Web Agent
[4] WebShaper: Agentically Data Synthesizing via Information-Seeking Formalization
[5] WebWatcher: Breaking New Frontier of Vision-Language Deep Research Agent
[6] WebResearcher: Unleashing unbounded reasoning capability in Long-Horizon Agents
[7] ReSum: Unlocking Long-Horizon Search Intelligence via Context Summarization
[8] WebWeaver: Structuring Web-Scale Evidence with Dynamic Outlines for Open-Ended Deep Research
[9] WebSailor-V2: Bridging the Chasm to Proprietary Agents via Synthetic Data and Scalable Reinforcement Learning
[10] Scaling Agents via Continual Pre-training
[11] Towards General Agentic Intelligence via Environment Scaling
[12] AgentFold: Long-Horizon Web Agents with Proactive Context Management
[13] WebLeaper: Empowering Efficient, Info-Rich Seeking for Web Agents
[14] BrowseConf: Confidence-Guided Test-Time Scaling for Web Agents
[15] Repurposing Synthetic Data for Fine-grained Search Agent Supervision
[16] ParallelMuse: Agentic Parallel Thinking for Deep Information Seeking
[17] AgentFrontier: Expanding the Capability Frontier of LLM Agents with ZPD-Guided Data Synthesis
[18] Nested Browser-Use Learning for Agentic Information Seeking

🌟 其他

🚩 人才招聘

🔥🔥🔥 我们正在招聘！研究实习生岗位开放（工作地点：杭州、北京、上海）

📚 研究方向：Web Agent、Search Agent、Agent RL、MultiAgent RL、Agentic RAG

☎️ 联系方式：yongjiang.jy@alibaba-inc.com

联系信息

如需沟通，请联系 Yong Jiang（yongjiang.jy@alibaba-inc.com）。

引用

@article{tongyidr,
  title={Tongyi DeepResearch Technical Report},
  author={Team, Tongyi DeepResearch and Li, Baixuan and Zhang, Bo and Zhang, Dingchu and Huang, Fei and Li, Guangyu and Chen, Guoxin and Yin, Huifeng and Wu, Jialong and Zhou, Jingren and others},
  journal={arXiv preprint arXiv:2510.24701},
  year={2025}
}