AIclinicalresearch/docs/02-通用能力层/04-DeepResearch引擎/01-Unifuncs DeepSearch API 使用指南.md

# Unifuncs DeepSearch API 使用指南

> **文档版本：** v2.0  
> **创建日期：** 2026-02-22  
> **最后更新：** 2026-02-23  
> **维护者：** 开发团队  
> **文档目的：** 指导业务模块正确使用 Unifuncs DeepSearch API，明确可用网站、调用模式与最佳策略

---

## 1. 概述

Unifuncs DeepSearch 是一个 AI 驱动的深度搜索引擎，可以在指定的网站范围内自动搜索、阅读和汇总信息。在本平台中，它作为通用能力层的一部分，为文献检索、临床试验查找等场景提供底层搜索能力。

### 核心能力
- 自然语言输入 → AI 自动生成搜索策略
- 多轮迭代搜索（最大深度可配置）
- 自动阅读网页内容并提取关键信息
- 返回结构化结果 + 综合报告
- 支持 SSE 实时流式 + 异步轮询两种调用模式

### API 基础信息

| 项目 | 值 |
|------|---|
| 基础 URL | `https://api.unifuncs.com/deepsearch/v1` |
| 模型 | `s2` |
| 认证 | `Authorization: Bearer {UNIFUNCS_API_KEY}` |
| 环境变量 | `UNIFUNCS_API_KEY`（已配置在 `backend/.env`） |

---

## 2. 两种调用模式

### 2.1 SSE 流式模式（V2.0 采用，推荐）

通过 OpenAI 兼容协议的 `POST /chat/completions` 端点，设置 `stream: true`，以 SSE 事件流实时返回 AI 思考过程和最终结果。

```typescript
const response = await fetch('https://api.unifuncs.com/deepsearch/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${UNIFUNCS_API_KEY}`,
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify({
    model: 's2',
    messages: [{ role: 'user', content: query }],
    stream: true,
    introduction: '你是一名专业的临床研究文献检索专家',
    max_depth: 25,
    domain_scope: ['https://pubmed.ncbi.nlm.nih.gov/'],
    reference_style: 'link',
    output_prompt: '请输出结构化报告和文献列表',
  }),
});

// 解析 SSE 事件流
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop() || '';

  for (const line of lines) {
    const trimmed = line.trim();
    if (trimmed.startsWith('data: ')) {
      const data = trimmed.slice(6);
      if (data === '[DONE]') return;
      const json = JSON.parse(data);
      const delta = json.choices?.[0]?.delta;
      if (delta?.reasoning_content) {
        // AI 思考过程（逐字流式，实时展示）
      }
      if (delta?.content) {
        // 最终结果内容（逐字流式）
      }
    }
  }
}
```

**SSE 流的数据特征（2026-02-23 实测）：**

| 指标 | 典型值 |
|------|--------|
| reasoning chunks | 2000~4000+ 个（实时逐条返回） |
| content chunks | 500~1600+ 个 |
| reasoning 总字符数 | 10000~13000 字符 |
| content 总字符数 | 8000~14000 字符 |
| 总耗时 | 4~6 分钟（max_depth=25） |

**优点：**
- reasoning_content 实时逐 chunk 返回，可立即展示 AI 思考过程
- 用户体验优秀：搜索、阅读、分析过程实时可见
- 无需轮询，数据推送式

**缺点：**
- 长连接可能因网络中断而失败
- 不返回 statistics（iterations、search_count 等）

### 2.2 异步模式（V1.x 曾使用，仅用于备选）

#### 创建任务 POST /v1/create_task

```typescript
const payload = {
  model: 's2',
  messages: [{ role: 'user', content: query }],
  introduction: '你是一名专业的临床研究文献检索专家',
  max_depth: 25,
  domain_scope: ['https://pubmed.ncbi.nlm.nih.gov/'],
  reference_style: 'link',
  generate_summary: true,
  output_prompt: '请输出结构化报告和文献列表',
};

const res = await fetch('https://api.unifuncs.com/deepsearch/v1/create_task', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${UNIFUNCS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});

const { data } = await res.json();
// data.task_id → 保存到数据库
```

#### 轮询任务 GET /v1/query_task

```typescript
const params = new URLSearchParams({ task_id: taskId });
const res = await fetch(
  `https://api.unifuncs.com/deepsearch/v1/query_task?${params}`,
  { headers: { 'Authorization': `Bearer ${UNIFUNCS_API_KEY}` } }
);

const { data } = await res.json();
// data.status: pending / running / completed / failed
// data.result.content: 最终结果
// data.result.reasoning_content: AI 思考过程（仅在接近完成时才有数据）
// data.progress: { current, total, message }
// data.statistics: { iterations, search_count, read_count, token_usage }
```

**优点：** 任务持久化，离开页面不中断，返回 statistics  
**缺点：** reasoning_content 不实时 — 实测中在 12 分钟内仅返回 25%/50%/90% 进度，最后才一次性返回全部思考内容，用户体验差

### 2.3 模式选择建议

| 场景 | 推荐模式 | 原因 |
|------|---------|------|
| 用户在线等待、需要实时反馈 | SSE 流式 | reasoning 实时展示 |
| 后台批量任务、无人值守 | 异步 | 任务持久化、可恢复 |
| V2.0 Deep Research | SSE 流式 | Worker 消费 SSE 流 + DB 持久化 |

---

## 3. 网站覆盖能力

### 3.1 V2.0 精选数据源（前端可选）

| 站点 | 域名 | 类型 | 默认 | 搜索效果 |
|------|------|------|------|----------|
| PubMed | pubmed.ncbi.nlm.nih.gov | 英文 | 默认勾选 | 效果最佳，核心数据源 |
| ClinicalTrials.gov | clinicaltrials.gov | 英文 | 可选 | 英文查询效果好 |
| Cochrane Library | www.cochranelibrary.com | 英文 | 可选 | 系统综述金标准 |
| 中国知网 CNKI | www.cnki.net | 中文 | 可选 | 中文核心期刊 |
| 中华医学期刊网 | medjournals.cn | 中文 | 可选 | 中文医学期刊，效果优秀 |

### 3.2 中文数据源专项测试（2026-02-23 实测）

测试条件：SSE 流式模式，max_depth=10，domain_scope 仅包含 CNKI + 中华医学期刊网

**测试 1：2型糖尿病患者SGLT2抑制剂的肾脏保护作用**

| 指标 | 结果 |
|------|------|
| 耗时 | 268.3s |
| reasoning chunks | 4071 个（12555 字符） |
| content chunks | 1671 个（8055 字符） |
| 中文字符数 | 2398 |
| 中华医学期刊网链接 | 46 个 |
| CNKI 链接 | 有 |
| PubMed 链接 | 0 个 |

**测试 2：非小细胞肺癌免疫治疗的中国临床研究进展**

| 指标 | 结果 |
|------|------|
| 耗时 | 316.4s |
| reasoning chunks | 2675 个（9985 字符） |
| content chunks | 3151 个（14291 字符） |
| 中文字符数 | 3536 |
| 中华医学期刊网链接 | 94 个 |
| PubMed 链接 | 0 个 |

**测试 3：他汀类药物一级预防（混合源：PubMed + CNKI + 中华医学期刊网）**

| 指标 | 结果 |
|------|------|
| 中文字符数 | 3676 |
| PubMed 链接 | 96 个 |
| 中文源链接 | 0 个 |

### 3.3 关键发现

1. 纯中文 domain_scope 效果好：当仅限定 CNKI + 中华医学期刊网时，API 能有效检索中文文献，返回的链接全部指向中文站点。中华医学期刊网效果尤其突出。

2. 混合模式存在偏向性：同时包含 PubMed + 中文源时，AI 明显倾向于 PubMed，中文文献被忽略。如果用户需要中文文献，建议仅选择中文数据库，或在 Prompt 中强调中文检索需求。

3. 付费库无法穿透：Unifuncs 只能访问公开可达的网页内容，不支持传入用户名密码。Web of Science、Embase、Scopus 等需要机构登录的库无法直接搜索。

4. SSE 模式实时性优于异步模式：SSE 流的 reasoning_content 真正逐 chunk 实时返回，而异步模式的 query_task 轮询中 reasoning_content 直到接近完成才有数据。

### 3.4 全站覆盖测试（2026-02-22 实测，异步模式）

#### 一级：确认可搜索（返回站内直接链接）

| 站点 | 域名 | 类型 | 站内链接数 | 搜索/阅读 | 最佳策略 |
|------|------|------|-----------|-----------|---------|
| PubMed | pubmed.ncbi.nlm.nih.gov | 英文 | 28 | 9/29 | 中/英文查询均可 |
| NCBI/PMC | www.ncbi.nlm.nih.gov | 英文 | 18 | 24/19 | 含 PMC 全文链接 |
| ClinicalTrials.gov | clinicaltrials.gov | 英文 | 38 | 6/24 | 英文查询，max_depth≥10 |
| Google Scholar | scholar.google.com | 英文 | 10 | 22/26 | 跨库聚合搜索 |
| CBM/SinoMed | www.sinomed.ac.cn | 中文 | 9 | 17/12 | 中文生物医学文献 |
| 中国知网 CNKI | www.cnki.net | 中文 | 7 | 40/6 | 中文核心期刊 |
| GeenMedical | www.geenmedical.com | 英文 | 5 | 38/3 | 医学搜索聚合引擎 |
| Cochrane Library | www.cochranelibrary.com | 英文 | 4 | 38/12 | 系统综述金标准 |
| 维普 VIP | www.cqvip.com | 中文 | 1 | 33/3 | 可用但链接较少 |

#### 二级：可到达但链接间接

| 站点 | 域名 | 类型 | 其他链接数 | 说明 |
|------|------|------|-----------|------|
| 中华医学期刊网 | medjournals.cn | 中文 | 12 | 搜索活跃，专项测试效果优秀 |
| 万方数据 | www.wanfangdata.com.cn | 中文 | 7 | 搜索活跃，链接可能转跳 |
| 中国临床试验注册中心 | www.chictr.org.cn | 中文 | 7 | 有内容产出 |
| 中国中医药数据库 | cintmed.cintcm.cn | 中文 | 22 | 内容丰富 |
| Scopus | www.scopus.com | 英文 | 15 | 付费墙限制 |
| Embase | www.embase.com | 英文 | 14 | 需机构登录 |
| Web of Science | www.webofscience.com | 英文 | 6 | 付费墙限制 |

---

## 4. 关键参数说明

| 参数 | 类型 | 推荐值 | 说明 |
|------|------|--------|------|
| `model` | string | `"s2"` | 固定值 |
| `stream` | boolean | `true` | SSE 流式模式 |
| `max_depth` | number | 10~25 | 搜索深度。测试用 10，生产用 25 |
| `domain_scope` | string[] | 按需配置 | 限定搜索范围，留空则不限 |
| `domain_blacklist` | string[] | `[]` | 排除特定站点 |
| `introduction` | string | 见下方 | 设定 AI 角色和搜索指导 |
| `reference_style` | string | `"link"` | 引用格式，`link` 或 `character` |
| `output_prompt` | string | 可选 | 自定义输出格式提示词 |
| `generate_summary` | boolean | `true` | 仅异步模式有效 |

### 推荐的 introduction 模板

```
你是一名专业的临床研究文献检索专家，擅长从多个学术数据库中检索高质量的医学文献。
请根据用户的检索需求，系统性地搜索并返回相关文献的详细信息。
```

### domain_scope 使用策略

| 场景 | domain_scope 配置 | 说明 |
|------|-------------------|------|
| 英文文献检索 | `["https://pubmed.ncbi.nlm.nih.gov/"]` | 核心数据源 |
| 中文文献检索 | `["https://www.cnki.net/", "https://medjournals.cn/"]` | 仅中文源，避免被英文库稀释 |
| 临床试验检索 | `["https://clinicaltrials.gov/"]` | 必须英文查询 |
| 系统综述 | `["https://www.cochranelibrary.com/"]` | Cochrane 专用 |
| 全面检索 | `["https://pubmed.ncbi.nlm.nih.gov/", "https://www.cochranelibrary.com/"]` | 多英文源组合 |

注意：不建议中英文数据源混合，测试表明混合时 AI 偏向英文源，中文文献会被忽略。如需同时检索中英文，建议分两次独立搜索。

---

## 5. 性能预期

| max_depth | 预计耗时 | 搜索/阅读量 | 适用场景 |
|-----------|---------|------------|---------|
| 5 | 1~3 分钟 | 10~40 / 0~20 | 快速探索 |
| 10 | 2~5 分钟 | 20~50 / 10~30 | 常规检索、中文源测试 |
| 15 | 3~8 分钟 | 30~80 / 20~50 | 深度检索 |
| 25 | 5~15 分钟 | 50~150 / 30~80 | 全面研究（V2.0 生产配置） |

### 成本估算

- 单次搜索 Token 消耗：5万~30万 tokens（取决于深度和站点数量）
- 估算成本：约 ¥0.1~0.5/次（按 unifuncs 定价）

---

## 6. 平台集成架构

### V2.0 SSE + 异步 Worker 混合架构（当前）

```
前端 DeepResearchPage
  → API: PUT /research/tasks/:taskId/execute
    → pg-boss Job Queue: asl_deep_research_v2
      → deepResearchV2Worker.ts
        → unifuncsSseClient.ts (SSE 流式)
          → 实时解析 reasoning_content → executionLogs → 写入 DB（每2s刷写）
          → 累积 content → 完成后解析为 synthesisReport + resultList
  → 前端 3s 轮询 DB → AgentTerminal 实时展示日志
```

### 核心文件

| 文件 | 说明 |
|------|------|
| `unifuncsSseClient.ts` | SSE 流式客户端，AsyncGenerator 逐 chunk 返回 |
| `unifuncsAsyncClient.ts` | 异步客户端（备选），create_task / query_task |
| `deepResearchV2Worker.ts` | pg-boss Worker，消费 SSE 流并实时写 DB |
| `reasoningParser.ts` | 将 reasoning_content 文本解析为结构化日志 |
| `resultParser.ts` | 将 content 解析为 synthesisReport + resultList |

### 其他模块可复用场景

| 模块 | 潜在用途 |
|------|---------|
| AIA 智能问答 | 智能体联网搜索增强 |
| PKB 个人知识库 | 自动补充知识库文献 |
| RVW 稿件审查 | 自动查找参考文献验证 |
| IIT 研究管理 | 自动检索同类临床试验 |

---

## 7. 测试脚本

| 脚本 | 路径 | 用途 |
|------|------|------|
| 中文数据源专项测试 | `backend/src/modules/asl/__tests__/deep-research-chinese-sources.ts` | SSE 流式模式测试 CNKI + 中华医学期刊网 |
| 全站覆盖测试 | `backend/scripts/test-unifuncs-site-coverage.ts` | 并行测试 18 个医学网站的搜索能力 |
| ClinicalTrials 专项 | `backend/scripts/test-unifuncs-clinicaltrials.ts` | 4 种策略对比测试 ClinicalTrials.gov |
| 快速验证 | `backend/scripts/test-unifuncs-deepsearch.ts` | 单站点 SSE 流式快速测试 |
| E2E 集成测试 | `backend/src/modules/asl/__tests__/deep-research-v2-e2e.ts` | V2.0 全流程端到端测试 |
| Smoke 测试 | `backend/src/modules/asl/__tests__/deep-research-v2-smoke.ts` | V2.0 API 连通性快速验证 |

```bash
# 中文数据源专项测试（SSE 流式，约 10~15 分钟）
cd backend
npx tsx src/modules/asl/__tests__/deep-research-chinese-sources.ts

# 全站覆盖测试
npx tsx scripts/test-unifuncs-site-coverage.ts

# E2E 集成测试（需先启动后端服务）
npx tsx src/modules/asl/__tests__/deep-research-v2-e2e.ts
```

---

**维护者：** 开发团队  
**最后更新：** 2026-02-23