Pubtator Entity Search

PubTator3 Entity & Relation Search

封装 NLM PubTator3 RESTful API,做实体级标注 + 关系挖掘。聚焦"疾病 — 药物 — 基因 — 化学品 — 突变 — 物种 — 细胞系"的联动检索。

---

1. 何时使用本技能

适合 (✅ 自动触发):

| 用户问题 | 路由 | |---|---| | "找 BTK 与肺曲霉病的关联文献" | ✅ 本技能 (find_co_mentions) | | "BTK 抑制剂 (MeSH D000077180) 在哪些研究被讨论" | ✅ 本技能 (search_by_entity) | | "标注这些 PMID 中提到的所有疾病/药物/基因实体" | ✅ 本技能 (annotate_pmid) | | "ibrutinib 在文献中映射到哪个 MeSH/DrugBank" | ✅ 本技能 (entity_normalize) | | "voriconazole 与 CYP2C19 相互作用" | ✅ 本技能 (search_by_relation) | | "BRAF V600E / rs113488022 突变文献" | ✅ 本技能 (search_by_entity concept=variant) |

不适合 (❌ 路由到其他 skill):

| 用户问题 | 路由 | |---|---| | "查 PubMed 上近 5 年所有 X 的 RCT" | ❌ → pubmed-eutils + Clinical Queries | | "MeSH 树 / 出版类型 / PubDate 综合检索" | ❌ → pubmed-eutils | | "Europe PMC 综合检索 + 引文" | ❌ → europepmc-search | | "全文段落抽取 / BioC 全文" | ❌ → bioc-fulltext-fetch | | "证据等级 / GRADE / 推荐级别" | ❌ → medical-evidence-grading | | "正在招募的 X 临床试验" | ❌ → clinical-trials-v2 |

---

2. API 概览 (无需 Key)

Base URL: https://www.ncbi.nlm.nih.gov/research/pubtator3-api/

PubTator3 是 NLM 开放服务,无需 API key,但请遵守速率限制 (≤ 5 req/s,失败时指数退避)。

| 端点 | 用途 | |------|------| | GET /search/?text= | 自由文本 / 实体检索文献 | | GET /publications/export/biocjson?pmids= | 拉取 PMID 的实体标注 BioC-JSON | | GET /entity/autocomplete/?query=&concept= | 实体规范化 (text → ID) | | GET /relations?e1=&e2= | 关系/共现挖掘 |

文档:

---

3. 5 个原子函数 (跨平台签名)

每个签名命名稳定,可在 Python / TS / Go / Rust 任意语言实现。

3.1 search_by_entity(entity_text, entity_type=None, max_results=50) -> list[PMID]

GET /search/?text=@_  或  ?text=

示例: text=@DISEASE_MESH:D055744 → 返回 {pmids:[...], score:[...]}。

3.2 search_by_relation(entity1_id, relation_type, entity2_id) -> list[Relation]

GET /relations?e1=&e2=&type=

关系类型见 references/relation-types.md。返回涉及关系的 PMID + score + 句级证据。

3.3 annotate_pmid(pmid_list) -> list[Annotation]

GET /publications/export/biocjson?pmids=12345,67890&full=false

解析 BioC-JSON documents[].passages[].annotations[]。一次最多 100 PMID,超出自动分批。

3.4 entity_normalize(free_text, concept=None) -> list[EntityCandidate]

GET /entity/autocomplete/?query=BTK%20inhibitor&concept=chemical

返回 [{name, id, type, score}, ...],例如 BTK inhibitor → MESH:D000077180。

3.5 find_co_mentions(entity1_id, entity2_id, top_n=20, recent_years=None) -> list[CoMention]

组合 search + annotate 验证两实体在同一文献被标注。可按近 N 年过滤。

---

4. 实体类型 & 关系类型 (Reference)

主文档不嵌入完整定义,按需展开:

• 实体类型 (7 种 + identifier 格式 + 查询前缀): 见 [references/entity-types.md](references/entity-types.md)
• gene / disease / chemical / variant / mutation / species / cellline
• 关系类型 (8 种 + 主-宾语典型组合 + score 阈值): 见 [references/relation-types.md](references/relation-types.md)
• treat / cause / inhibit / interact_with / regulate / associate / compare / co-occur

---

5. 输出格式 (标准 schema)

每条标注:

{
    "pmid": "12345",
    "entity_text": "BTK",
    "entity_type": "Gene",          # Gene/Disease/Chemical/Variant/Species/CellLine
    "identifier": "695",            # NCBI Gene / MESH / rs# / Taxonomy / CVCL
    "section": "Title",             # Title / Abstract
    "offset": 23,                   # passage 内字符级起点
    "length": 3,
    "confidence": 0.95,             # 若 API 返回
}

每条关系:

{
    "pmid": "12345",
    "subject":   {"text": "ibrutinib", "type": "Chemical", "id": "MESH:D000077594"},
    "predicate": "inhibits",
    "object":    {"text": "BTK",       "type": "Gene",     "id": "695"},
    "score": 0.92,
    "evidence_sentence": "Ibrutinib irreversibly inhibits BTK ...",
    "section": "Abstract",
}

---

6. 典型工作流

用例 A — 疾病 + 药物联动

> "找近 5 年讨论 BTK 抑制剂与侵袭性肺曲霉病关系的文献"

1. entity_normalize("BTK inhibitor", "chemical") → MESH:D000077180
2. entity_normalize("invasive pulmonary aspergillosis", "disease") → MESH:D055744
3. find_co_mentions(e1, e2, top_n=30, recent_years=5)
4. 对返回 PMID 用 annotate_pmid() 提取上下文 → 三元组表
5. 需要证据等级 → 输出喂给 medical-evidence-grading

用例 B — 批量标注

> "把这 20 个 PMID 里所有疾病/药物/基因列出来"

1. annotate_pmid([...20 PMIDs...])
2. 按 entity_type ∈ {Gene, Disease, Chemical} 过滤 → 去重计数 → 频次表

用例 C — 实体规范化

> "ibrutinib 的 MeSH 是什么?"

1. entity_normalize("ibrutinib", "chemical") → 取首条 hit 的 id

用例 D — 上下游链接

> 本技能产出 PMID 集合后,可直接喂给:

• pubmed-eutils → 拿元数据 / 出版类型
• bioc-fulltext-fetch → 拿全文段落
• medical-evidence-grading → 实体级证据排序

---

7. 失败模式 (≥ 5 条)

| # | 失败模式 | 检测 | 处理 | |---|---|---|---| | 1 | 实体未识别 — PubTator 不支持的术语 / 拼写 / 罕见同义词 | autocomplete 返回空 | 退化用 pubmed-eutils 自由文本检索;同时建议规范同义词或换 concept | | 2 | 实体规范化多义词 — BTK 既是基因 (NCBI 695) 也是缩写 / 化学品 | autocomplete 返回多 hit,score 接近 | 让用户确认 concept;必要时用 ID 而非 symbol | | 3 | **关系置信度低 (score

• PubTator3 标注属机器抽取,**置信度 · @DISEASEMESH: · @CHEMICALMESH: · @VARIANT · @SPECIES · @CELLLINE_`

---

版本: v1.1 · 维护: 跟随 NLM PubTator3 API 文档更新 (关注 endpoints 变更与新增 concept)。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EthanYoQ
• Source: EthanYoQ/Skill-hub
• License: MIT

Install and usage instructions live in the source repository linked above.