bioc-fulltext-fetch

Files (1)

• SKILL.md

SKILL.md (first lines)

# BioC Fulltext Fetch

封装 NLM BioC API,用于将 PubMed / PMC 文献转换为 RAG 友好的结构化全文 chunk。

## 1. 职责边界（单一职责）

**只做**:给定 PMID / PMCID,取结构化全文(BioC XML/JSON 格式),输出段落、章节、表格上下文、RAG chunk。

**不做**:
- 检索文献(交给 `pubmed-eutils` / `europepmc-search`)
- 实体标注(交给 `pubtator3`)
- 向量化(交给下游的 embedding pipeline / LangChain / LlamaIndex)
- ID 转换(可调用 `pubmed-eutils.elink_pubmed_to_pmc`,但本 skill 不实现 elink)

如果需要这些能力,请使用对应的 skill。

## 2. 何时使用

触发场景:
- "把这批 PMID 的全文取下来,准备入 ChromaDB"
- "我有 PMCID 列表,需要按章节切分做 RAG"
- "提取 Methods 章节段落"
- "找出表格周围的语义文本"
- "Build vector index from PMC open access papers"

不要使用本 skill 当:
- 用户只需要标题/摘要的纯文本 → 用 `pubmed-eutils.efetch`
- 用户需要做语义检索 → 用 `europepmc-search` 或 `pubmed-search`
- 用户需要实体标注(基因/疾病/化合物) → 用 PubTator3 类 skill

## 3. 两个 BioC 端点

| 端点 | 输入 | 覆盖 | 内容 |
|------|------|------|------|
| **BioC PubMed** | PMID | 全 PubMed (~37M) | 标题 + 摘要 + MeSH (结构化) |
| **BioC PMC OA** | PMCID | PMC 开放获取子集 (~10M) | 全文(章节、段落、表格、图注) |

端点示例:
```
# 摘要级
https://www.ncbi.nlm.nih.gov/research/bionlp/RESTful/pubmed.cgi/BioC_json/{PMID}/unicode

# 全文级
https://www.ncbi.nlm.nih.gov/research/bionlp/RESTful/pmcoa.cgi/BioC_json/{PMCID}/unicode
```

文档参考:
- BioC PubMed: https://www.ncbi.nlm.nih.gov/research/bionlp/APIs/BioC-PubMed/
- BioC PMC OA: https://www.ncbi.nlm.nih.gov/research/bionlp/APIs/BioC-PMC/

## 4. 推荐工作流

```
用户给 PMID list
  │
  ▼
[可选] elink PMID → PMCID  (调用 pubmed-eutils)
  │
  ├── PMCID 存在 + 是 OA ──► fetch_fulltext_bioc(pmcid)  ← 全文
  │                                  │
  │                                  ▼
  │                          extract_paragraphs / extract_tables_context
  │                                  │
  │                                  ▼
  │                          to_rag_chunks(chunk_size=512, overlap=50)
  │
  └── 不可用 / 非 OA ──────► fetch_abstract_bioc(pmid)   ← 摘要兜底
                                     │
                                     ▼
                              to_rag_chunks (摘要也按段切)
```

## 5. 核心能力(5 个函数)

### 5.1 `fetch_abstract_bioc(pmid: str) → BioCDocument`

取标题 + 摘要 + MeSH 的 BioC 结构化版本。

```python
doc = fetch_abstract_bioc("39523456")
# doc.passages → [{"infons": {"section_type": "TITLE"}, "text": "..."},
#                 {"infons": {"section_type": "ABSTRACT"}, "text": "..."}]
# doc.infons["mesh"] → ["Leukemia, Myeloid, Acute", "FLT3 Mutation", ...]
```

### 5.2 `fetch_fulltext_bioc(pmcid: str) → BioCDocument`

取 PMC OA 全文,按章节切分(`section_type` ∈ {TITLE, ABSTRACT, INTRO, METHODS, RESULTS, DISCUSS, CONCL, REF, FIG, TABLE, ...})。

```python
doc = fetch_fulltext_bioc("PMC10234567")
# 不可用时抛 NotOpenAccessError 或 NotFoundError
```

错误处理:
- `404` → 该 PMCID 不在 PMC OA 子集 → 抛 `NotOpenAccessError`,调用方应回退到 `fetch_abstract_bioc`
- `429` → 限流 → 退避重试(最多 3 次,指数退避)
- 网络错误 → 抛 `BioCFetchError`,记录日志

### 5.3 `extract_paragraphs(doc: BioCDocument) → list[Paragraph]`

按 BioC `passage` 提取段落数组,保留 section 标签 + 字符 offset。

```python
paragraphs = extract_paragraphs(doc)
# [
#   {"section_label": "INTRO", "text": "Acute myeloid leukemia (AML) is...",
#    "offset_start": 1234, "offset_end": 1820},
#   {"section_label": "METHODS", "text": "Flow cytometry was performed...",
#    "offset_start": 2890, "offset_end": 3401},
#   ...
# ]
```

实现要点:
- 跳过 `section_type ∈ {REF, FIG_LABEL}` 的纯标签段
- 合并连续相同 section 的短 passage(< 50 字符)
- offset 来自 BioC `passage.offset` 字段,保持原文索引一致

From EthanYoQ/Skill-hub, MIT.

More from EthanYoQ/Skill-hub