bioc-fulltext-fetch

Files (4)

• SKILL.md
• bioc-format-spec.md · references/
• chunking-strategies.md · references/
• rag-integration.md · references/

SKILL.md (first lines)

# BioC Fulltext Fetch

封装 NLM BioC API，把 PubMed / PMC 文献转成 RAG 友好的结构化全文 chunk。**只做全文抽取与切片，不做检索、不做实体标注、不做向量化。**

## 1. 何时使用

触发场景：
- "把这批 PMID 的全文取下来准备入 ChromaDB / 我有 PMCID 列表要按章节切分做 RAG"
- "提取 Methods 章节段落 / 找出表格周围的语义文本"
- "Build vector index from PMC open access papers"
- "PMC1234567 的全文段落 + 章节标签"
- "把 100 篇血液 IFI PMID 入向量库"

不要使用本 skill：
- 用户只要标题/摘要纯文本 → 用 `pubmed-eutils` efetch
- 用户要做语义检索找文献 → 用 `pubmed-search` / `europepmc-search`
- 用户要实体标注（基因/疾病/化合物）→ 用 `pubtator-entity-search`（可在本 skill 输出之上叠加，不替代）
- 用户要做证据等级评分 → 用 `medical-evidence-grading`（其内部会调用本 skill 抽 Methods 段落）

## 2. 跨 skill 协作（显式）

| 上游 / 下游 skill | 协作方式 |
|------------------|----------|
| `pubmed-eutils.elink_pubmed_to_pmc()` | **上游**，把 PMID 列表转换成 PMCID 列表，喂给本 skill |
| `europepmc-search.get_full_text_links()` | **替代源**，当 PMC OA 不可用时回退到 Europe PMC 的开放获取链接 |
| `pubtator-entity-search` | **后置叠加**，在本 skill 产的 chunk 上做实体标注，不替代本 skill |
| `medical-evidence-grading` | **下游**，调 `extract_paragraphs` 取 Methods 段落做 sample size / study design 检测 |

典型 pipeline：
```
europepmc-search ──► PMID list ──► pubmed-eutils.elink ──► PMCID list
                                                              │
                                                              ▼
                                            bioc-fulltext-fetch (本 skill)
                                                              │
                                                              ├─► [可选] pubtator-entity-search 实体叠加
                                                              ├─► [可选] medical-evidence-grading 证据评分
                                                              └─► LangChain / LlamaIndex 入库
```

## 3. 两个 BioC 端点

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

```
摘要级:  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
```

格式细节、`section_type` 取值、字符 offset 一致性见 [`references/bioc-format-spec.md`](references/bioc-format-spec.md)。

## 4. 推荐工作流

```
PMID list
  │
  ▼
[可选] elink PMID→PMCID  (调 pubmed-eutils)
  │
  ├─ PMCID 存在且 OA ──► fetch_fulltext_bioc(pmcid) ──► extract_paragraphs / extract_tables_context ──► to_rag_chunks
  │
  └─ 不可用/非 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，调用方应回退到 fetch_abstract_bioc
```

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

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

```python
paragraphs = extract_paragraphs(doc)
# [{"section_label": "METHODS", "text": "Flow cytometry was performed...",
#   "offset_start": 2890, "offset_end": 3401}, ...]
```

要点：跳过 `REF` / `FIG_LABEL` 纯标签段；合并同 section 内 < 50 字符短 passage；offset 来自 BioC `passage.offset`。

### 5.4 `extract_tables_context(doc: BioCDocument, window: int = 200) -> list[TableContext]`

提取每个表格的上下文（前后 200 字），帮 RAG 给表打语义标签。

```python
tables = extract_tables_context(doc, window=200)
# [{"table_id": "T1", "caption": "Patient baseline characteristics",
#   "before_context": "...", "after_context": "...", "section": "RESULTS"}, ...]
```

表格本体（cell 数据）不解析；只取 caption + 周围文本。

### 5.5 `to_rag_chunks(doc: BioCDocument, chunk_size: int = 512, overlap: int = 50) -> list[Chunk]`

把 BioC 文档切成 RAG 入库 chunk。token 单位、不跨章节、段落优先、可追溯 `chunk_id`。

```python
chunks = to_rag_chunks(doc, chunk_size=512, overlap=50)

From EthanYoQ/Skill-hub, MIT.

More from EthanYoQ/Skill-hub