FreedomIntelligence/openPangu-Embedded-7B-DeepDiver

开源盘古 Embedded-7B-DeepDiver

中文 | English
📑技术报告

1. 简介

DeepDiver是openPangu系列中定位深度信息获取与处理的Agent，支持原生 Multi-Agent System（MAS），用于复杂知识问答与长文调研报告写作。

特性

• 🔍 支持QA模式：回答100步+复杂知识性问题
• ✍️ 支持长文写作模式：撰写3w+字文章与报告
• 🔄 支持自适应模式：根据用户问题自动选择知识问答模式或长文写作模式

2. 评测结果

测评集	测评指标	openPangu-7B-DeepDiver
BrowseComp-zh	Acc	18.3
BrowseComp-en	Acc	8.3
XBench-DeepSearch	Acc	39.0

注：上表仅展示复杂问答的结果，长文调研的评测结果请参考技术报告

3. 快速部署

3.1 环境准备

# 克隆并安装
git clone <repository-url>
cd deepdiver_v2
pip install -r requirements.txt

3.2 部署推理服务

拉取镜像

docker pull quay.io/ascend/vllm-ascend:v0.9.2rc1

或按照官方文档手动构建 docker 容器。

运行容器

docker run -itd --name vllm-deepdiver \
    --network host \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --device /dev/davinci4 \
    --device /dev/davinci5 \
    --device /dev/davinci6 \
    --device /dev/davinci7 \
    -u root \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi:ro \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool:ro \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi:ro \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/:ro \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info:ro \
    -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
    -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware:ro \
    -v /data:/data:ro \
    -v /home/work:/home/work \ # 配置一个可读写的工作目录
    quay.io/ascend/vllm-ascend:v0.9.2rc1

进入容器

docker exec -itu root vllm-deepdiver bash

注意：必须使用 -itu root。

复制 Pangu 的 modeling 文件

open_pangu.py 和 __init__.py 可以在这里找到。

cp ./vllm_ascend/open_pangu.py /vllm-workspace/vllm-ascend/vllm_ascend/models/
cp ./vllm_ascend/__init__.py /vllm-workspace/vllm-ascend/vllm_ascend/models/

启动部署

PRECHECKPOINT_PATH="path/to/deepdiver_model"

export VLLM_USE_V1=1

export VLLM_WORKER_MULTIPROC_METHOD=fork
# export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

vllm serve $PRECHECKPOINT_PATH \
    --served-model-name ${SERVED_MODEL_NAME:=pangu_auto} \
    --tensor-parallel-size ${tensor_parallel_size:=8} \
    --trust-remote-code \
    --host 127.0.0.1 \
    --port 8888 \
    --max-num-seqs 256 \
    --max-model-len ${MAX_MODEL_LEN:=131072} \
    --max-num-batched-tokens ${MAX_NUM_BATCHED_TOKENS:=4096} \
    --tokenizer-mode "slow" \
    --dtype bfloat16 \
    --distributed-executor-backend mp \
    --gpu-memory-utilization 0.93 \

测试部署

curl -X POST http://127.0.0.1:8888/v1/completions -H "Content-Type: application/json" -d '{
"model": "pangu_auto",
"prompt": ["Tell me who you are?"],
"max_tokens": 50
}'

3.3 实现所需工具

在启动服务器前，你需要为 web search 与 URL 抓取工具实现自定义逻辑。

Web Search（_generic_search）

位置：src/tools/mcp_tools.py - _generic_search 方法

将 NotImplementedError 替换为你的搜索工具实现：

def _generic_search(self, query: str, max_results: int, config: Dict[str, Any]) -> MCPToolResult:
    """Your custom search implementation - based on the commented code example"""
    try:
        # Example implementation for search API:
        url = config.get('base_url', 'https://api.search-provider.com/search')
        payload = json.dumps({"q": query, "num": max_results})
        api_keys = config.get('api_keys', [])
        headers = {
            'X-API-KEY': random.choice(api_keys),
            'Content-Type': 'application/json'
        }
        
        response = requests.post(url, data=payload, headers=headers)
        response.raise_for_status()
        
        # Transform your API response to required format
        search_results = {
            "organic": [
                {
                    "title": result["title"],
                    "link": result["link"], 
                    "snippet": result["snippet"],
                    "date": result.get("date", "unknown")
                } 
                for result in response.json().get("organic", [])
            ]
        }
        
        return MCPToolResult(success=True, data=search_results)
        
    except Exception as e:
        return MCPToolResult(success=False, error=f"Generic search failed: {e}")

URL Crawler（url_crawler 与 _content_extractor）

位置：src/tools/mcp_tools.py - _content_extractor

将 NotImplementedError 部分替换为你的网页抓取工具实现：

# Example implementation for content extractor:
    crawler_url = f"{crawler_config.get('base_url', 'https://api.content-extractor.com')}/{url}"
    response = requests.get(crawler_url, headers=headers, timeout=crawler_config.get('timeout', 30))
    response.raise_for_status()

    content = response.text

    # Truncate if needed
    if max_tokens and len(content.split()) > max_tokens:
        words = content.split()[:max_tokens]
        content = ' '.join(words) + '...'

    return MCPToolResult(success=True, data=content)

⚠️ 第三方服务提示

重要：搜索与抓取工具使用外部 API 由用户自行选择和实现。我们不对以下情况负责：

• 与第三方服务相关的隐私/安全问题
• 搜索/抓取活动的合规性
• 内容准确性或版权问题
• API 停机或变更

使用这些服务需自担风险。请查看其条款与隐私政策。

3.4 必要配置

配置 .env 文件

复制 env.template 到 config/.env 并配置如下选项：

# LLM Service
MODEL_REQUEST_URL=http://localhost:8888/v1/chat/completions       # 你的 LLM endpoint

# Agent 限制
PLANNER_MODE=auto                            # 在 auto、writing 或 qa 模式间切换

# 外部 API（先实现函数）
SEARCH_ENGINE_BASE_URL=                      # 搜索 API endpoint
SEARCH_ENGINE_API_KEYS=                      # 搜索 API keys
URL_CRAWLER_BASE_URL=                        # URL Crawler API endpoint
URL_CRAWLER_API_KEYS=                        # URL Crawler API keys

⚠️ 注意：

• 请将上一步部署的推理服务 URL 配置到 MODEL_REQUEST_URL
• 在 PLANNER_MODE 中指定模式。auto 会自动决策回答复杂问题或生成长文；若希望优先长文写作，可设置为 writing；若希望专注解决高难度问题，可设置为 qa

3.5 启动工具服务

python src/tools/mcp_server_standard.py

3.6 运行Demo

# 交互模式
python cli/demo.py

# 单次查询
python cli/demo.py -q "$your_query"

基于上述步骤可以快速运行DeepDiver，如果需要二次开发，可以参考章节4和5

4. 自定义工具开发指南

当前工具主要分为内置工具和外部MCP工具，内部工具主要包括分发任务，思考/反思等，外部MCP工具则是一些延伸LLM能力的工具，如搜索互联网，爬取链接，下载和读写文件等。

4.1 已实现的工具类别

A. 外部MCP工具

Web Search 与数据采集：

• batch_web_search：多查询 web 搜索
• url_crawler：从 URL 抽取内容
• download_files：从 URL 下载文件

文件操作：

• file_read、file_write：基础文件 I/O
• list_workspace：目录列表

文档处理与内容创作：

• document_qa：针对特定文档问答
• document_extract：多格式文本抽取
• section_writer：结构化内容生成

B. 内置工具

• think、reflect：推理与规划
• task_done：任务完成汇报
• assign_task_xxx: 分发任务并创建子智能体

4.2 开发并集成新的外部MCP工具

A. 实现新的MCP工具

位置：src/tools/mcp_tools.py - 在 MCPTools 类中添加方法

def your_new_tool(self, param1: str, param2: int) -> MCPToolResult:
    """
    Description of what your tool does.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2 
    
    Returns:
        MCPToolResult: Standardized result format
    """
    try:
        # Your tool implementation here
        result_data = {
            "output": "Tool result",
            "processed_items": param2
        }
        
        return MCPToolResult(
            success=True,
            data=result_data,
            metadata={"tool_name": "your_new_tool"}
        )
        
    except Exception as e:
        logger.error(f"Tool execution failed: {e}")
        return MCPToolResult(
            success=False,
            error=f"Tool failed: {str(e)}"
        )

B. 在服务器中注册工具

添加工具 Schema

位置：src/tools/mcp_tools.py - 添加到 MCP_TOOL_SCHEMAS 字典

MCP_TOOL_SCHEMAS = {
    # ... existing tools ...
    
    "your_new_tool": {
        "name": "your_new_tool",
        "description": "Brief description of what your tool does",
        "inputSchema": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Description of parameter 1"
                },
                "param2": {
                    "type": "integer", 
                    "default": 10,
                    "description": "Description of parameter 2"
                }
            },
            "required": ["param1"]
        }
    }
}

注册工具函数

位置：src/tools/mcp_server_standard.py - 添加到 get_tool_function()

def get_tool_function(tool_name: str):
    """Get the actual function for a tool"""
    tool_map = {
        # ... existing tools ...
        "your_new_tool": lambda tools, **kwargs: tools.your_new_tool(**kwargs),
    }
    return tool_map.get(tool_name)

C. 让特定智能体可使用工具

工具对各智能体的可见性由 MCP client 中的预定义工具集控制。

位置：src/tools/mcp_client.py - 修改各智能体的工具集

# Define which MCP server tools each agent can access
PLANNER_AGENT_TOOLS = [
    "download_files",
    "document_qa",
    "file_read",
    "file_write", 
    "str_replace_based_edit_tool",
    "list_workspace",
    "file_find_by_name",
    "your_new_tool",  # Add your new tool here
]

INFORMATION_SEEKER_TOOLS = [
    "batch_web_search",
    "url_crawler",
    "document_extract", 
    "document_qa",
    "download_files",
    "file_read",
    "file_write",
    "str_replace_based_edit_tool",
    "list_workspace",
    "file_find_by_name",
    "your_new_tool",  # Add your new tool here if needed
]

WRITER_AGENT_TOOLS = [
    "file_read",
    "list_workspace", 
    "file_find_by_name",
    "search_result_classifier",
    "section_writer",
    "concat_section_files",
    # Add your tool if the writer agent needs it
]

4.3 添加内置智能体工具/函数

A. 带有真实返回的工具/函数

DeepDiver中的agent，如planner，集成了assign_subjective_task_to_writer, assign_multi_objective_tasks_to_info_seeker 等内置函数作为工具， 这类函数除了具体实现之外，还需要使用_build_agent_specific_tool_schemas() 添加专属的tool schema。

位置：src/agents/your_agent.py

def _build_agent_specific_tool_schemas(self) -> List[Dict[str, Any]]:
    """Add built-in agent functions (not MCP server tools)"""
    
    # Get base schemas from MCP server via client
    schemas = super()._build_agent_specific_tool_schemas()
    
    # Add agent-specific built-in functions like task assignment, completion reporting
    builtin_functions = [
        {
            "type": "function", 
            "function": {
                "name": "agent_specific_task_done",
                "description": "Report task completion for this agent",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "result": {"type": "string", "description": "Task result"},
                        "status": {"type": "string", "description": "Completion status"}
                    },
                    "required": ["result", "status"]
                }
            }
        }
    ]
    
    schemas.extend(builtin_functions)
    return schemas

B. 带有伪返回的内置工具

DeepDiver中的cognitive tools，比如think和reflect等，这些工具实际没有具体实现，agent在调用这些工具时通过生成工具入参，就已经完成了工具的调用。可以直接在模型生成完入参后，使用类似以下方法进行返回，继续让模型完成后续工作 (参考planner_agent.py 中_execute_react_loop()的实现)：

if tool_call["name"] in ["think", "reflect"]:
    tool_result = {"tool_results": "You can proceed to invoke other tools if needed. "}

同理，这种内置工具也需要使用_build_agent_specific_tool_schemas() 添加专属的tool schema。

5. 个性化配置

5.1 Client 配置

复制 env.template 到 config/.env 并配置如下选项：

# LLM Service
MODEL_REQUEST_URL=http://localhost:8000      # 你的 LLM endpoint
MODEL_REQUEST_TOKEN=your-token               # LLM auth token
MODEL_NAME=pangu_auto                        # 模型名
MODEL_TEMPERATURE=0.3                        # 随机度（0.0-1.0）
MODEL_MAX_TOKENS=8192                        # 最大回复长度
MODEL_REQUEST_TIMEOUT=60                     # 请求超时（秒）

# Agent 限制
PLANNER_MAX_ITERATION=40                     # Planner 最大 ReAct 步数
INFORMATION_SEEKER_MAX_ITERATION=30          # 信息搜集最大 ReAct 步数  
WRITER_MAX_ITERATION=40                      # Writer 最大 ReAct 步数
PLANNER_MODE=auto                            # auto / 长文优先 / qa 优先

# MCP Server
MCP_SERVER_URL=http://localhost:6274/mcp     # MCP server endpoint
MCP_USE_STDIO=false                          # 使用 stdio 或 HTTP

# 外部 API（先实现函数）
SEARCH_ENGINE_BASE_URL=                      # 搜索 API endpoint
SEARCH_ENGINE_API_KEYS=                      # 搜索 API keys
URL_CRAWLER_BASE_URL=                        # URL Crawler API endpoint
URL_CRAWLER_API_KEYS=                        # URL Crawler API keys
URL_CRAWLER_MAX_TOKENS=100000                # URL Crawler 内容最大长度

# 存储路径
TRAJECTORY_STORAGE_PATH=./workspace          # Agent工作目录
REPORT_OUTPUT_PATH=./report                  # 报告输出目录
DOCUMENT_ANALYSIS_PATH=./doc_analysis        # 文档分析目录

# 系统
DEBUG_MODE=false                             # 是否开启调试日志
MAX_RETRIES=3                                # API 重试次数
TIMEOUT=30                                   # 通用超时（秒）

5.2 Server 配置（server_config.yaml）

server_config.yaml 控制服务器行为、工具限流与运行设置：

核心服务器设置

server:
  host: "127.0.0.1"              # 服务器绑定地址
  port: 6274                     # 端口  
  debug_mode: false              # 调试日志
  session_ttl_seconds: 21600     # 会话过期（6小时）
  max_sessions: 1000             # 并发会话上限

工具限流

对所有会话的外部 API 使用进行控制：

tool_rate_limits:
  batch_web_search:
    requests_per_minute: 9000    # 每分钟限制
    burst_limit: 35              # 短时突发
  
  url_crawler:
    requests_per_minute: 9000
    burst_limit: 60

会话管理

server:
  cleanup_interval_seconds: 600   # 清理过期会话（5分钟）
  enable_session_keepalive: true  # 长时操作期间保活
  keepalive_touch_interval: 300   # 保活触发间隔（秒）

安全与性能

server:
  request_timeout_seconds: 1800        # 请求超时
  max_request_size_mb: 1000            # 最大请求体
  rate_limit_requests_per_minute: 300000  # 每 IP 限流

配置文件包含对每项设置的详细注释。请根据你的部署需求与外部 API 限额进行调整。

6. 模型许可证

除文件中对开源许可证另有约定外，openPangu-Embedded-7B-DeepDiver 模型根据 OPENPANGU MODEL LICENSE AGREEMENT VERSION 1.0 授权，旨在允许使用并促进人工智能技术的进一步发展。有关详细信息，请参阅模型存储库根目录中的 LICENSE 文件。

7. 安全提示与免责声明

由于 openPangu-Embedded-7B-DeepDiver 模型和框架所依赖的技术固有的技术限制，以及人工智能生成的内容是由盘古自动生成的，华为无法对以下事项做出任何保证：

• 尽管该模型的输出由 AI 算法生成，但不能排除某些信息可能存在缺陷、不合理或引起不适的可能性，生成的内容不代表华为的态度或立场；
• 无法保证该模型 100% 准确、可靠、功能齐全、及时、安全、无错误、不间断、持续稳定或无任何故障；
• 该模型的输出内容不构成任何建议或决策，也不保证生成的内容的真实性、完整性、准确性、及时性、合法性、功能性或实用性。生成的内容不能替代医疗、法律等领域的专业人士回答您的问题。生成的内容仅供参考，不代表华为的任何态度、立场或观点。您需要根据实际情况做出独立判断，华为不承担任何责任；
• DeepDiver MAS系统的组件间通信不包含内置的数据加密或认证（如 tokens、签名）。你需要自行评估安全需求并实施相应防护（例如运行在加密网络中、加入 SSL/TLS、强制组件身份校验）；
• 由于缺乏加密/认证导致的任何安全事件（数据泄露、未授权访问、业务损失）由使用方自行承担。项目开发者不承担责任。

8. 反馈

如果有任何意见和建议，请提交issue或联系 openPangu@huawei.com。

---