Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,554 @@
+# 开源盘古 Embedded-7B-DeepDiver
+中文 | [English](README_EN.md)  
+📑[技术报告](https://ai.gitcode.com/ascend-tribe/openPangu-Embedded-7B-DeepDiver/blob/main/docs/openpangu-deepdiver-v2-tech-report.pdf)
+
+
+## 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    |
+
+注：上表仅展示复杂问答的结果，长文调研的评测结果请参考[技术报告](https://ai.gitcode.com/ascend-tribe/openPangu-Embedded-7B-DeepDiver/blob/main/docs/openpangu-deepdiver-v2-tech-report.pdf)
+
+## 3. 快速部署
+
+### 3.1 环境准备
+
+```bash
+# 克隆并安装
+git clone <repository-url>
+cd deepdiver_v2
+pip install -r requirements.txt
+```
+
+### 3.2 部署推理服务
+
+#### 拉取镜像
+
+```
+docker pull quay.io/ascend/vllm-ascend:v0.9.2rc1
+```
+
+或按照[官方文档](https://vllm-ascend.readthedocs.io/en/stable/installation.html)手动构建 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` 可以在[这里](https://ai.gitcode.com/ascend-tribe/openpangu-embedded-7b-model/tree/main/inference/vllm_ascend/models)找到。
+
+```
+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` 替换为你的搜索工具实现：
+
+```python
+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` 部分替换为你的网页抓取工具实现：
+
+```python
+# 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` 并配置如下选项：
+
+```bash
+# 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 启动工具服务
+
+```bash
+python src/tools/mcp_server_standard.py
+```
+
+### 3.6 运行Demo
+
+```bash
+# 交互模式
+python cli/demo.py
+
+# 单次查询
+python cli/demo.py -q "$your_query"
+```
+
+基于上述步骤可以快速运行DeepDiver，如果需要二次开发，可以参考[章节4](#4-自定义工具开发指南)和[5](#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` 类中添加方法
+
+```python
+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` 字典
+
+```python
+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()`
+
+```python
+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` - 修改各智能体的工具集
+
+```python
+# 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`
+
+```python
+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()`的实现)：
+
+```python 
+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` 并配置如下选项：
+
+```bash
+# 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` 控制服务器行为、工具限流与运行设置：
+
+#### 核心服务器设置
+
+```yaml
+server:
+  host: "127.0.0.1"              # 服务器绑定地址
+  port: 6274                     # 端口  
+  debug_mode: false              # 调试日志
+  session_ttl_seconds: 21600     # 会话过期（6小时）
+  max_sessions: 1000             # 并发会话上限
+```
+
+#### 工具限流
+
+对所有会话的外部 API 使用进行控制：
+
+```yaml
+tool_rate_limits:
+  batch_web_search:
+    requests_per_minute: 9000    # 每分钟限制
+    burst_limit: 35              # 短时突发
+  
+  url_crawler:
+    requests_per_minute: 9000
+    burst_limit: 60
+```
+
+#### 会话管理
+
+```yaml
+server:
+  cleanup_interval_seconds: 600   # 清理过期会话（5分钟）
+  enable_session_keepalive: true  # 长时操作期间保活
+  keepalive_touch_interval: 300   # 保活触发间隔（秒）
+```
+
+#### 安全与性能
+
+```yaml
+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](LICENSE) 文件。
+
+## 7. 安全提示与免责声明
+由于 openPangu-Embedded-7B-DeepDiver 模型和框架所依赖的技术固有的技术限制，以及人工智能生成的内容是由盘古自动生成的，华为无法对以下事项做出任何保证：
+
+- 尽管该模型的输出由 AI 算法生成，但不能排除某些信息可能存在缺陷、不合理或引起不适的可能性，生成的内容不代表华为的态度或立场；
+- 无法保证该模型 100% 准确、可靠、功能齐全、及时、安全、无错误、不间断、持续稳定或无任何故障；
+- 该模型的输出内容不构成任何建议或决策，也不保证生成的内容的真实性、完整性、准确性、及时性、合法性、功能性或实用性。生成的内容不能替代医疗、法律等领域的专业人士回答您的问题。生成的内容仅供参考，不代表华为的任何态度、立场或观点。您需要根据实际情况做出独立判断，华为不承担任何责任；
+- DeepDiver MAS系统的组件间通信不包含内置的数据加密或认证（如 tokens、签名）。你需要自行评估安全需求并实施相应防护（例如运行在加密网络中、加入 SSL/TLS、强制组件身份校验）；
+- 由于缺乏加密/认证导致的任何安全事件（数据泄露、未授权访问、业务损失）由使用方自行承担。项目开发者不承担责任。
+
+## 8. 反馈
+
+如果有任何意见和建议，请提交issue或联系 openPangu@huawei.com。
+
+---