PlantAI-rag/docs/GeneFamily-RAG_Spec_v1.0.md

基因家族 RAG（GeneFamily-RAG）落地规范 v1.0

面向“基因家族研究”场景的 Graph-first + Evidence-second RAG 总体设计与数据规范
生成日期：2026-03-26（America/Los_Angeles）

---

0. 为什么要单独做“基因家族版”RAG

基因家族论文/报告的问答，和“通用植物知识图谱问答”最大的差异在于：

1. 结构化优先：家族成员、系统发育分组、结构域/基序、复制事件、共线性、同源/旁系/直系同源等是主干信息；文本证据是支撑层。
2. 强规范化需求：同一基因会以多种形式出现（symbol / locus / protein / accession / 旧ID / 物种前缀）；不做 alias-first，召回会不稳定。
3. 可追溯是硬门槛：科研写作/审稿需要能落到“哪篇文献/哪一段/哪张图/哪张补表/哪条数据行”。

---

1. 参考 PlantConnectome 的“可借鉴点”与“必须补强点”

1.1 可直接借鉴的工程思想（你现在已有数据能支持）

• 边表（Edges）：一行一条关系，包含 source/type/relationship/target/type + pubmedID + p_source + basis，并额外保存 resolved 版本与 alias 字段。
• Resolve 是独立阶段：同时保存“原始抽取”和“归一化后”字段，便于调试与回溯。
• 关系同义词归并：把大量自然语言关系词归并到少量类别/枚举（例如 activation/induction 类）。

1.2 对基因家族 RAG 必须补强的关键缺口（你在说明文档里已经确认）

• p_source 的格式是 {pmid}_{section}（如 23031218_abstract），但 当前数据库无法用 p_source 直接取到原文 chunk；需要从 p_source 提取 PMID，再通过 PubMed API 在线获取摘要/原文。
• 这意味着：你的系统必须补一层“文献证据库（pmid → chunks）”，否则只能做“弱可追溯”（指到 PMID+section，但没有可复核原句）。

---

2. 总体架构：Graph-first + Evidence-second（强推荐作为默认路由）

2.1 两级检索（默认路由）

1. Graph-first（结构化召回）：
   • 先在图谱/关系表里召回候选实体/边/路径（尤其：member_of / classified_into / has_domain / orthologous_to / syntenic_with / duplicated_to / expressed_in / upregulated_in）。
2. Evidence-second（证据回填）：
   • 用每条候选边的 provenance 去取到证据 chunk（本地 chunk 库优先；没有则在线拉取并缓存）。
3. Cite Gate（引用门控）：
   • 置信度 ≥ medium 的结论必须能回填证据，否则回答自动降级为“可能/提示/需要进一步核查”。

---

3. 数据分层与集合（Collections/Tables）设计

3.1 需要的最小 6 个数据域（强推荐）

1. Edges（关系边表）：核心事实/关系。
2. Entities（实体表）：规范化实体（含 type、species、primary_id）。
3. Alias（别名表）：alias-first 的基础。
4. Documents（文献元数据）：PMID/DOI ↔ title/year/journal。
5. Chunks（证据库）：pmid → section → chunk_id → text + locator。
6. FamilyLayer（家族专用层）：家族成员、分组、结构域架构、复制/共线、orthogroup 等。

---

4. 统一 JSON Schema（你项目的“最终输出格式”）

4.1 顶层

{"entities":[...], "relations":[...]}

4.2 Entity 通用字段

{
  "id": "唯一ID（内部稳定）",
  "name": "展示名",
  "type": "gene|protein|gene_family|protein_domain|treatment|phenotype|...（枚举）",
  "species": "物种（对 gene/protein 强制）",
  "primary_id": "稳定外部ID（AGI/Ensembl/UniProt/NCBI等）",
  "attributes": {},
  "description": "可选",
  "provenance": [ ... ]
}

4.3 Relation 通用字段（核心）

{
  "id": "关系ID",
  "source": "源实体ID",
  "target": "目标实体ID",
  "type": "关系枚举（canonical）",
  "confidence": "high|medium|low",
  "qualifiers": {},
  "provenance": [ ... ],
  "description": "可选"
}

---

5. 基因家族通用实体类型（推荐最小全集）

• Core：gene, protein, gene_family, gene_subfamily/phylo_clade
• 家族鉴定：family_definition, hmm_model, protein_domain, motif, domain_architecture
• 演化：orthogroup, duplication_event, syntenic_block, genomic_region, genome_build
• 表达与表型：tissue, developmental_stage, treatment, phenotype, trait
• 证据：publication, doc_chunk, figure, table, dataset, database, assay, method

---

6. 基因家族通用关系类型（Canonical Enum）

• 家族：member_of, classified_into, defined_by, uses_model, has_domain, has_motif, has_architecture
• 演化：homologous_to, orthologous_to, paralogous_to, belongs_to_orthogroup, syntenic_with, duplicated_to, duplicated_from
• 表达：expressed_in, upregulated_in, downregulated_in, induced_by, repressed_by, temporally_expressed
• 功能/表型：involved_in, affects, controls, associated_with
• 互作/调控（可选）：regulates, activates, inhibits, binds_to, interacts_with, targets

---

7. provenance（证据指针）标准

{
  "source_type": "publication|dataset|database",
  "source_id": "pmid:23031218|doi:...|GSE...|UniProt:...",
  "p_source": "23031218_abstract",
  "doc_chunk_id": "pmid23031218_abs_c03",
  "locator": {
    "section": "abstract|results|figure_legend|table|supp",
    "page_start": null,
    "page_end": null,
    "figure": null,
    "table": null
  },
  "snippet": "可复核原句（尽量原文）",
  "evidence_level": "experiment|omics|prediction|curation",
  "method": "RNA-seq|qRT-PCR|HMMER|MCScanX|..."
}

---

8. Resolve（归一化）流水线（必须独立）

• Entity resolve（alias-first）：优先稳定 ID（AGI/Ensembl/UniProt）> locus > symbol > name
• Relationship resolve（同义词归并）：把自然语言关系统一到 canonical enum，方向固定
• Type resolve：把 gene identifier / gene(s) / protein(s) 等不稳定类型统一到枚举

---

9. 域/值域约束（domain/range constraints）

expressed_in:
  direction: "source->target"
  domain: ["gene","transcript","protein"]
  range:  ["tissue","cell_type","developmental_stage"]

orthologous_to:
  direction: "bidirectional"
  domain: ["gene"]
  range:  ["gene"]
  constraints:
    - "species(source) != species(target)"

---

10. PlantConnectome 边表字段 → 你的 v2 映射

• pubmedID → provenance.source_id = pmid:{pubmedID}
• p_source → provenance.p_source
• basis → provenance.snippet（短期可用；长期建议用原句替换）
• * resolved → 你的 canonical entity/type/relation
• * gene alias → Alias 表的候选 ID 列表

---

11. 最小实现顺序（最优计划）

1. 导入边表到 Edges（保留 raw/resolved + pmid/p_source/basis）
2. alias-first：建 Alias + 统一 entity_id/primary_id/species
3. relationship resolve + domain/range 校验
4. 在线证据回填缓存：pmid → abstract chunks（先把“可追溯”做起来）
5. 家族专用层：member/clade/domain/duplication/synteny（来自你自己的分析）
6. Cite Gate：高置信必须能回填 snippet，否则降级措辞

---

附录：建议补充的 2 个高频关系

• localized_to：protein → subcellular_compartment
• essential_for：gene/protein → process/metabolite/phenotype（或归并到 involved_in + qualifiers.role=essential）