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 思考过程和最终结果。

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

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

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 分钟	1040 / 020	快速探索
10	2~5 分钟	2050 / 1030	常规检索、中文源测试
15	3~8 分钟	3080 / 2050	深度检索
25	5~15 分钟	50150 / 3080	全面研究（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 连通性快速验证

# 中文数据源专项测试（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