europepmc-search
Europe PMC RESTful Web Service 的薄封装。一次请求 = 多源召回:PubMed(MED)、PubMed Central(PMC)、AGRICOLA(AGR)、CABI(CBA)、预印本(PPR,涵盖 bioRxiv/medRxiv/ChemRxiv/arXiv 生命科学子集)、专利(PAT)、ETHOS 论文集等。
1. 何时使用本 skill
| 场景 | 用本 skill | 不用本 skill |
|---|
| RAG 知识库构建,需"撒网"式广召回 | ✅ | |
| 同时要 PubMed + 预印本 | ✅ | |
| 只要 PubMed 官方源 + Clinical Queries | | ❌ → pubmed-eutils |
| 拿 DOI 反查全文 OA 链接 | ✅ | |
| 找特定基金(NIH/NSFC/Wellcome)资助的研究 | ✅(grant_id 检索) | |
| 抽取已知 PMCID 的全文 XML | | ❌ → bioc-fulltext-fetch |
| 临床试验注册号检索 | | ❌ → clinical-trials-v2 |
| 实体(基因/疾病/化合物)关联 | | ❌ → pubtator-entity-search |
与 pubmed-eutils 的差异化(必读):
- pubmed-eutils:PubMed 单源、Clinical Queries 过滤、PubDate 精确范围 → 高精准
- europepmc-search:多源聚合 + 自动去重 + 全文链接 + citations metadata → 高召回
- 推荐编排:RAG 知识库构建用本 skill 广召回 → 拿 PMID 列表喂给 pubmed-eutils 做精准复核
2. 前置准备 / 配置加载
Europe PMC RESTful 是完全开放 API,无需 API key,但服务条款要求传 email 联系方式(礼貌请求,便于 EBI 在大流量异常时联系到使用者)。
配置加载顺序(优先级从高到低):
- 项目级:
.config/europepmc.local.yaml(可选,优先于全局)
- 用户级:
~/.config/europepmc.yaml
- 环境变量:
EUROPEPMC_EMAIL
- 都没有 → 退化为
anonymous@example.org 并打印 ⚠️ 警告(建议用户配置)
配置文件示例(~/.config/europepmc.yaml):
email: your-email@example.com
default_page_size: 100 # 单页条数,1-1000
default_result_type: core # lite | core | idlist
default_format: json # json | xml | dc
timeout_seconds: 30
max_retries: 3
3. API 端点速查
基础 URL:https://www.ebi.ac.uk/europepmc/webservices/rest/
| 端点 | 用途 | 关键参数 |
|---|
search | 通用检索(本 skill 主力) | query, resultType, pageSize, cursorMark, format, sort |
article/{source}/{id} | 单篇详情 | source∈{MED,PMC,PPR,AGR,CBA,PAT,CTX,ETH,HIR,NBK} |
{source}/{id}/fullTextXML | 全文 XML(仅 OA) | 仅 PMC 子集 |
{source}/{id}/references | 参考文献 | 分页 |
{source}/{id}/citations | 被引列表 | 分页 |
{source}/{id}/supplementaryFiles | 补充材料 | |
grant/search | 资助检索 | query=GR:"R01..." |
4. 核心检索能力(5 个原子函数)
4.1 search_articles(query, source_filter=None, max_results=200, sort=None)
通用多源检索,自动分页(cursorMark)拉满到 max_results。
query:Europe PMC 查询语法(支持字段限定,见 §5)source_filter:["MED","PMC","PPR"] 限定来源;None = 全部sort:"date"(出版日期降序)/ "cited"(被引降序)/ None(默认相关性)
返回:List[Article],每条含 pmid / pmcid / doi / title / authors / journal / pub_year / abstract / source / is_preprint / preprint_server / has_full_text / oa_status / cited_by_count。
4.2 get_article_details(identifier)
单篇完整元数据。identifier 自动识别:
- 纯数字 → PMID(查 MED 源)
PMC 前缀 → PMCID(查 PMC 源)10. 开头 → DOI(用 query=DOI:"..." 反查)PPR 开头 → 预印本 ID(查 PPR 源)
4.3 get_full_text_links(pmid_or_pmcid)
返回所有可用全文链接,按类型分类:
{
"oa_xml": "https://.../fullTextXML", # OA 子集才有
"oa_pdf": "https://europepmc.org/...pdf",
"publisher_html": "https://...",
"subscription": [...], # SUBSCRIPTION 类型
"text_mining": [...], # TM 类型(NLM 等)
"preprint_server": "https://www.biorxiv.org/..."
}
4.4 search_with_grants(query, grant_id=None, funder=None)
资助检索。Europe PMC 有专门的 GRANT_ID / FUNDER 字段。
# 找 NIH R01-CA123456 资助的所有 paper
search_with_grants(query="cancer", grant_id="R01-CA123456")
# 找 Wellcome Trust 资助的全部 cardiology paper
search_with_grants(query="cardiology", funder="Wellcome Trust")
4.5 find_similar_articles(pmid_or_pmcid, limit=20)
调用 Europe PMC 内置的 "Similar Articles" 算法(基于 MeSH + 文本相似度)。比 PubMed elink neighbor 召回略广,适合做 RAG "扩展邻域"。
5. 查询语法核心字段
Europe PMC 查询语法兼容 Lucene 风格,字段大写。常用字段:
| 字段 | 含义 | 示例 |
|---|
TITLE | 标题 | TITLE:"CAR-T" |
ABSTRACT | 摘要 | ABSTRACT:cytokine |
AUTH | 作者 | AUTH:"Smith J" |
JOURNAL | 期刊 | JOURNAL:"Nature" |
PUB_YEAR | 年份 | PUB_YEAR:[2020 TO 2024] |
PUB_TYPE | 文献类型 | PUB_TYPE:"Review" |
SRC | 来源数据库 | SRC:MED, SRC:PPR, SRC:PMC |
HAS_FT | 有全文 | HAS_FT:Y |
OPEN_ACCESS | OA | OPEN_ACCESS:Y |
MESH | MeSH 主题词 | MESH:"Hematologic Neoplasms" |
GRANT_ID | 资助号 | GRANT_ID:"R01CA12345" |
DOI | DOI | DOI:"10.1038/s41586-020-2196-x" |
LANG | 语种 | LANG:eng |
预印本筛选示例:(SRC:PPR) AND (TITLE:"acute myeloid leukemia") AND (PUB_YEAR:2024)
6. 多源去重逻辑(本 skill 强制内置)
同一篇文章常在 MED + PMC + PPR 同时出现。去重规则按以下优先级合并:
- 第一级:PMID 相同 → 合并,保留 MED 版本(PubMed 元数据最权威)
- 第二级:PMCID 相同 → 合并,保留 PMC 版本(因含全文)
- 第三级:DOI 相同 → 合并,优先 MED > PMC > PPR
- 预印本特殊处理:若同一 DOI 既有预印本(PPR)又有正式发表(MED),两条都保留,但预印本条目标记
superseded_by_pmid: <发表版 PMID>,下游(medical-evidence-grading)据此决定是否丢弃预印本。
返回的合并条目结构:
{
"primary_id": "PMID:38123456",
"all_ids": {"pmid": "38123456", "pmcid": "PMC10987654", "doi": "10.1038/..."},
"sources": ["MED", "PMC"], # 出现的所有源
"is_preprint": False,
"preprint_server": None,
"superseded_by_pmid": None,
...其他元数据
}
7. 预印本处理(医学证据特别注意)
预印本 = source == "PPR"。本 skill 在每条结果中显式标注:
{
"source": "PPR",
"is_preprint": True,
"preprint_server": "bioRxiv", # 或 medRxiv / ChemRxiv / Research Square / SSRN ...
"preprint_doi": "10.1101/2024.03.15.123456",
"posted_date": "2024-03-15",
"version": 2 # 预印本版本号
}
下游约定:medical-evidence-grading skill 看到 is_preprint=True 会自动降权(GRADE 中作为 "very low" 起点),且若同 DOI 已有正式发表版,直接丢弃预印本。本 skill 自身不做证据分级,只如实标注。
8. 分页与流量
- Europe PMC 单页上限:
pageSize=1000
- 分页方式:强制使用
cursorMark(从 * 起,响应里的 nextCursorMark 拿来下一页);不要用 page= 偏移分页(>1000 条时官方明确不保证一致性)
- 流量礼貌:全局并发 ≤ 5,每秒 ≤ 8 请求(自动 sleep)
- 429 / 5xx 退避:指数退避
2^n 秒,最多重试 max_retries(默认 3)
9. 错误处理与边界情况
| 状态 | 处理 |
|---|
HTTP 200 + hitCount=0 | 返回空列表 + warning"无命中,建议放宽 query" |
| HTTP 400 | 多半是查询语法错误 → 抛 EuropePMCQueryError,附原始 errMsg |
| HTTP 429 | 指数退避重试 |
| HTTP 5xx | 指数退避重试 |
cursorMark 与上一次相同 | 已到末页,正常终止 |
同 query 已超过 max_results | 截断并返回 truncated=True 标志 |
致命错误一律抛异常,不静默吞(遵循全局 coding-style.md 错误处理原则)。
10. 调用示例
from europepmc_search import EuropePMCClient
cli = EuropePMCClient() # 自动加载 ~/.config/europepmc.yaml
# 1) 广召回:急性髓系白血病近 5 年 PubMed + 预印本
hits = cli.search_articles(
query='(TITLE:"acute myeloid leukemia" OR ABSTRACT:"AML") AND PUB_YEAR:[2020 TO 2025]',
source_filter=["MED", "PPR"],
max_results=500,
sort="date",
)
print(f"去重后 {len(hits)} 条,其中预印本 {sum(h['is_preprint'] for h in hits)} 条")
# 2) DOI 反查全文链接
links = cli.get_full_text_links("10.1056/NEJMoa2024850")
# 3) 找 NIH R01 资助的 CAR-T 研究
ft = cli.search_with_grants(query="CAR-T", grant_id="R01CA255621")
# 4) 邻域扩展
similar = cli.find_similar_articles("38123456", limit=30)
11. 与同体系其他 skill 的协作
[用户问题]
│
├─→ europepmc-search ← 本 skill,广召回 200~1000 条
│ │
│ └─→ pubmed-eutils ← 拿 PMID 子集精准复核 + Clinical Queries 过滤
│ │
│ └─→ bioc-fulltext-fetch ← 对 OA PMC 取全文 XML
│ │
│ └─→ pubtator-entity-search ← 实体识别
│ │
│ └─→ medical-evidence-grading ← GRADE 分级
│ (在此处依据 is_preprint 自动降权)
│
└─→ clinical-trials-v2 / aact-bulk-trials ← 试验注册号另走专线
12. 输出契约(下游 skill 依赖)
每篇文章返回的标准 schema(本 skill 是契约源):
{
"primary_id": "PMID:38123456" | "PMCID:PMC10987654" | "DOI:10.xxx/...",
"all_ids": {"pmid": str|None, "pmcid": str|None, "doi": str|None, "ppr_id": str|None},
"title": str,
"authors": [{"full_name": str, "affiliation": str|None, "orcid": str|None}],
"journal": {"name": str, "iso_abbr": str|None, "issn": str|None},
"pub_year": int,
"pub_date": "YYYY-MM-DD",
"abstract": str|None,
"mesh_terms": [str],
"keywords": [str],
"source": "MED" | "PMC" | "PPR" | "AGR" | "CBA" | "PAT",
"sources_merged": ["MED","PMC"], # 去重前出现的所有源
"is_preprint": bool,
"preprint_server": str|None,
"preprint_doi": str|None,
"version": int|None,
"superseded_by_pmid": str|None,
"has_full_text": bool,
"oa_status": "OA" | "SUBSCRIPTION" | "UNKNOWN",
"full_text_links": {"oa_xml": str|None, "oa_pdf": str|None, "publisher_html": str|None},
"cited_by_count": int,
"grants": [{"grant_id": str, "agency": str, "country": str|None}],
"fetched_at": "ISO-8601 UTC",
"europepmc_url": "https://europepmc.org/article/MED/38123456"
}
下游 skill(medical-evidence-grading / bioc-fulltext-fetch / pubtator-entity-search)按此契约消费,字段缺失用 None,不省略 key。
参考链接