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

Unifuncs DeepSearch API 使用指南

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

---

1. 概述

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

核心能力

• 自然语言输入 → AI 自动生成搜索策略
• 多轮迭代搜索（最大深度可配置）
• 自动阅读网页内容并提取关键信息
• 返回结构化结果 + 综合报告

API 基础信息

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

---

2. 网站覆盖能力（2026-02-22 实测）

2.1 测试条件

• 查询：他汀类药物预防心血管疾病的随机对照试验和Meta分析，近5年高质量研究
• 配置：max_depth=5，异步模式（create_task + query_task）
• ClinicalTrials.gov 专项：4 种策略对比测试，max_depth=5~15

2.2 可用性分级

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

站点	域名	类型	站内链接数	搜索/阅读	最佳策略
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	搜索活跃（41次），内容丰富但链接跳转
万方数据	www.wanfangdata.com.cn	中文	7	搜索活跃（42次），链接可能转跳
中国临床试验注册中心	www.chictr.org.cn	中文	7	有内容产出，链接指向其他站
中国中医药数据库	cintmed.cintcm.cn	中文	22	内容最丰富（8631字），链接非直达
Scopus	www.scopus.com	英文	15	付费墙限制，内容来自外部引用
Embase	www.embase.com	英文	14	需机构登录
Web of Science	www.webofscience.com	英文	6	付费墙限制

三级：不可用或受限

站点	域名	说明
Ovid	ovidsp.ovid.com	仅搜索未读取内容，需机构登录
NSTL	www.nstl.gov.cn	搜索到但无有效内容和链接

2.3 关键发现

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

2. ClinicalTrials.gov 必须用英文：该站点为纯英文网站，中文查询效率极低。使用英文查询 + max_depth≥10 时，可稳定返回 30+ 个 NCT 编号和链接。

3. 中文库表现不一：CNKI 和 SinoMed 效果较好，能直接返回站内链接；万方和中华医学期刊网可到达但链接不直达。

---

3. 两种调用模式

3.1 OpenAI 兼容协议（流式，适合实时展示）

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.unifuncs.com/deepsearch/v1',
  apiKey: process.env.UNIFUNCS_API_KEY,
});

const stream = await client.chat.completions.create({
  model: 's2',
  messages: [{ role: 'user', content: query }],
  stream: true,
  introduction: '你是一名专业的临床研究文献检索专家',
  max_depth: 15,
  domain_scope: ['https://pubmed.ncbi.nlm.nih.gov/'],
  domain_blacklist: [],
  reference_style: 'link',
} as any);

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  if ((delta as any)?.reasoning_content) {
    // AI 思考过程（逐字流式）
  }
  if (delta?.content) {
    // 最终结果内容（逐字流式）
  }
}

优点： 实时展示 AI 思考过程，用户体验好
缺点： 连接不稳定，离开页面任务丢失，长任务容易超时

3.2 异步模式（推荐用于 V2.0）

创建任务

const payload = {
  model: 's2',
  messages: [{ role: 'user', content: query }],
  introduction: '你是一名专业的临床研究文献检索专家',
  max_depth: 15,
  domain_scope: ['https://pubmed.ncbi.nlm.nih.gov/'],
  domain_blacklist: [],
  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 → 保存到数据库

轮询任务

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 / processing / completed / failed
// data.result.content: 最终结果
// data.result.reasoning_content: AI 思考过程（增量）
// data.progress: { current, total, message }
// data.statistics: { iterations, search_count, read_count, token_usage }

优点： 任务持久化，离开页面不中断，可恢复，适合长任务
缺点： 非实时，需要轮询获取进度

---

4. 关键参数说明

参数	类型	推荐值	说明
model	string	"s2"	固定值
max_depth	number	10~25	搜索深度。测试用 5，生产用 15~25。越大越全但越慢
domain_scope	string[]	按需配置	限定搜索范围。留空则不限
domain_blacklist	string[]	[]	排除特定站点
introduction	string	见下方	设定 AI 角色和搜索指导
reference_style	string	"link"	引用格式，link 或 character
output_prompt	string	可选	自定义输出格式提示词
generate_summary	boolean	true	异步模式完成后自动生成摘要

推荐的 introduction 模板

你是一名专业的临床研究文献检索专家。
请根据用户的研究需求，在指定数据库中系统性地检索相关文献。

检索要求：
1. 优先检索高质量研究：系统综述、Meta分析、RCT
2. 关注 PICOS 要素（人群、干预、对照、结局、研究设计）
3. 优先近 5 年的研究
4. 返回每篇文献的完整元数据（标题、作者、期刊、年份、链接）

输出要求：
1. 按研究类型分组
2. 每篇文献附带直接链接
3. 最后给出综合性研究概述

---

5. 最佳策略指南

5.1 针对不同站点的策略

目标站点	查询语言	max_depth	特殊说明
PubMed / NCBI	中文或英文均可	15~25	效果最好，核心数据源
ClinicalTrials.gov	必须英文	10~15	中文查询极慢甚至超时
Cochrane Library	英文优先	10~15	系统综述专用
Google Scholar	中文或英文	10~15	跨库聚合，可能有重复
CNKI / SinoMed	中文	10~15	中文文献首选
GeenMedical	英文优先	5~10	聚合搜索，速度快

5.2 多站点组合搜索

// V2.0 推荐：用户选择多个数据源，合并到 domain_scope
const domainScope = [
  'https://pubmed.ncbi.nlm.nih.gov/',
  'https://www.cochranelibrary.com/',
  'https://scholar.google.com/',
];

// 如果包含 ClinicalTrials.gov，需求扩写时自动翻译为英文

5.3 性能预期

max_depth	预计耗时	搜索/阅读量	适用场景
5	1~3 分钟	1040 / 020	快速探索
10	2~5 分钟	2050 / 1030	常规检索
15	3~8 分钟	3080 / 2050	深度检索
25	5~15 分钟	50150 / 3080	全面研究

5.4 成本估算

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

---

6. 平台集成方式

当前使用（V1.x - ASL 模块）

researchService.ts → OpenAI SDK → SSE 流式
researchWorker.ts → pg-boss → 异步执行

计划升级（V2.0 - ASL Deep Research）

requirementExpansionService.ts → DeepSeek-V3 需求扩写
unifuncsAsyncClient.ts → create_task / query_task 异步模式
deepResearchV2Worker.ts → pg-boss Worker → 轮询 + 日志解析

其他模块可复用场景

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

---

7. 测试脚本

项目中已提供两个测试脚本：

脚本	路径	用途
全站覆盖测试	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 流式快速测试

cd backend
npx tsx scripts/test-unifuncs-site-coverage.ts
npx tsx scripts/test-unifuncs-clinicaltrials.ts

---

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