admin/PlantAI-rag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
PlantAI-rag/docs/PROJECT_INVENTORY_2026-05-19.md
T
potaser 5bb98a937a 初始提交
2026-07-10 17:59:59 +08:00

18 KiB
Executable File
Raw Permalink Blame History

gene-family-mas-v2 项目框架与文件整理记录

生成日期：2026-05-19
目的：梳理项目主框架、功能边界、工作逻辑和文件归类，为后续代码整理、归档迁移和减冗余提供依据。

1. 项目定位

当前项目已经不是早期 README 所写的单纯“纯净 RAG 系统”。实际代码形态更接近：

  1. 文献提取系统：从基因家族论文 PDF/MinerU 输出中抽取实体、关系、方法学、附表、多组学编号、图像/图注信息。
  2. KG-RAG 服务：将提取结果构造成向量索引、知识图谱、物种索引、方法学索引、family facts，并通过 FastAPI 提供查询。
  3. 分析项目知识后端：为 bbav5/基因家族分析项目提供 Pfam、家族规模基线、物种覆盖、方法学复现参数、结果解读证据。
  4. 实验评估仓库：包含 V2 到 V15 多代抽取器、PlantConnectome 对齐实验、方法学 gold set、RAG 评测、案例 QA 与大量历史输出。

一句话概括：这是一个“基因家族论文知识抽取 + 文献证据 RAG + 分析复现知识服务”的研究型代码库。

2. 主工作逻辑

2.1 文献抽取主线

主线入口：

  • src/rag/extractors/v15/v15_extractor.py

主要阶段：

  1. Phase 1 文档解析

    • phase1_document_parser.py
    • phase1_document_parser_mineru.py
    • 输入 PDF 或 MinerU 结果，输出 sections/full_text/mineru_dir。

  2. Phase 2 附表处理

    • phase2_supplementary.py
    • 支持本地附表和下载附表，输出附表关系。

  3. Phase 2.5 多组学编号提取

    • multi_db_extractor.py
    • 从论文中抽取 GEO/SRA/ENA/PRIDE/MetaboLights 等数据集编号。

  4. Phase 3 实体识别

    • phase3_entity_recognition.py
    • 识别基因、基因家族、物种、组织、阶段、复合实体等。

  5. Phase 4 关系抽取

    • phase4_relation_extraction.py
    • phase4_llm_relation_extraction.py
    • relation_block_builder.py
    • 规则 + LLM + relation block，抽取 gene-family paper 中的生物学关系。

  6. Phase 4.5 三元组规范化

    • phase4_5_triple_canonicalization.py
    • 修复端点、关系类型、候选关系，输出 audit CSV。

  7. Phase 4.6 关系语义审核

    • phase4_6_relation_semantic_review.py
    • 区分 paper finding、paper interpretation、cited prior work、background context 等。

  8. Phase 5 后处理

    • phase5_post_processing.py
    • 关系验证、去重、chunk 生成。

  9. Phase 6 图像/VLM/图注

    • phase6_vlm_image_extraction.py
    • phase6_5_figure_caption.py

  10. Phase 7 审核

  • phase5_review.py
  • 对实体/关系/文本覆盖做最终 assessment。

输出：

  • result.json
  • relation_semantic_review_audit.csv
  • relation_claim_scope_audit.csv
  • relation_repair_audit.csv
  • relation_candidates_for_review.csv
  • llm_relation_candidate_audit.csv
  • relation_block_extraction_summary.json

2.2 RAG 索引与结构化事实主线

文本向量索引：

  • scripts/build_index_from_v15_family.py

    • 新通用索引构建器。
    • 支持任意 family、paper config、多 result.json。

  • scripts/build_index_from_v15_spl.py

    • 兼容旧 SPL 命令。
    • 后续应进一步瘦身为纯 wrapper。

结构化 family facts：

  • src/rag/family_facts.py
  • scripts/build_family_fact_cards_from_v15.py
  • data/family_facts/spl.json

当前 family facts 提供：

  • Pfam ID，例如 SPL -> PF03110。
  • 成员数 baseline，例如 SPL per-species baseline 18/25/32。
  • stage-context，例如 identify/phylogeny/expression/motif/miRNA 证据。
  • functional_context。

2.3 API 服务主线

主入口：

  • api/main.py

路由聚合：

  • api/routes.py

当前挂载：

  • /api/v1/rag/*
  • /api/v1/kg/*
  • /api/v1/v10/*
  • /api/v1/advanced/*
  • /api/v1/raptor/*
  • /api/v1/temporal/*
  • /api/v1/kg-rag/*
  • /api/v1/species/*
  • /api/v1/methodology/*

核心 RAG 路由：

  • api/rag_routes.py

关键接口：

  • POST /api/v1/rag/chat
  • GET /api/v1/rag/rag/status
  • POST /api/v1/rag/rag/advanced/search
  • GET /api/v1/rag/family/pfam
  • GET /api/v1/rag/family/baseline
  • GET /api/v1/rag/family/stage-context

2.4 方法学与 bbav5 对齐主线

核心模块：

  • src/rag/unified/methodology.py
  • src/rag/unified/llm_methodology_extractor.py
  • src/rag/unified/bbav5_capability.py
  • src/rag/unified/bbav5_methodology_config.py
  • src/rag/unified/methodology_reviewer.py
  • src/rag/unified/methodology_payload_validator.py

输出/评测目录：

  • methodology_batch_Ft_spl/
  • methodology_batch_pecan_spl/
  • methodology_batch_sunflowers_spl/
  • data/evaluation/methodology_*

作用：

  • 从论文 methods 中抽取 stage、tool、parameter、input、output、evidence_sentence。
  • 对齐 bbav5 可执行阶段。
  • 判断 supported_default/supported_alternative/partially_supported/external_or_manual。
  • 为分析项目自动生成复现方法配置。

2.5 统一 schema / 证据门控主线

核心模块：

  • src/rag/unified/schema.py
  • src/rag/unified/pipeline.py

数据模型：

  • DocumentRecord
  • ChunkRecord
  • Evidence
  • EntityRecord
  • RelationRecord
  • MethodParameter
  • AnalysisTask
  • KnowledgeBase

作用：

  • 给 publication-grade KG-RAG 提供证据约束的骨架。
  • UnifiedRAGEngine 根据 intent 分流到 stats/methodology/relation/analysis/entity。
  • EvidenceGate 会剔除缺证据事实。

目前状态：

  • 设计方向正确。
  • 仍偏骨架/测试态，尚未完全成为 API 主查询路径。

3. 主要目录与整理判断

路径 作用 当前判断 整理建议
api/ FastAPI 服务层 核心保留 清理 .bak、nohup.out、旧独立 app
src/rag/ RAG、抽取、索引、KG 主代码 核心保留 建议拆成 core/ extraction/ retrieval/ storage/ methodology/
src/rag/extractors/v15/ 当前主抽取器 核心保留 作为唯一主线抽取器维护
src/rag/extractors/v14/ 上一代抽取器 兼容/参考 若无生产调用，移到 archive/old_extractors/v14
src/rag/extractors/v13/ PC 覆盖率实验历史 参考保留 可移到 archive，保留 README 与 gold case
src/rag/extractors/ 下 V2-V12 文件 多代实验抽取器 候选归档 统一迁移到 archive/old_extractors
src/rag/unified/ 方法学、schema、bbav5 对齐 核心保留 与 API 方法学路由保持同步
src/rag/advanced/ query expansion、RAPTOR、graph algorithms 部分保留 已挂 API 的保留；未用实验文件转 archive
src/llm/ LLM provider 管理 核心保留 保留
src/db/ SQLite/DB schema 部分保留 确认 data/cases.db、memory 是否仍用
scripts/ 构建、评测、迁移、历史实验脚本 需要重整 拆为 scripts/current/, scripts/evaluation/, scripts/archive/
tests/ 当前与历史测试混合 需要重整 保留当前 pytest；历史测试迁入 tests/archive
docs/ 文档、历史分析、计划 需要索引化 建议保留 DOCS_INDEX，历史文档移 docs/history
data/ 索引、facts、gold、评估数据 核心数据+大量结果混合 建立 data/runtime, data/evaluation, data/archive
paper/ 原始论文和 MinerU 资源 体积最大 原始语料保留但可移到外部 data volume
v15_output/ V15 抽取结果 当前实验输出 保留 selected/gold，批量中间结果归档
v14_output/ V14 输出 历史输出 候选归档
output/ 临时/测试输出 高优先清理 保留必要 case，其余归档或删除
backups/ 修订备份 候选归档 打包转 archive/backups_YYYYMMDD
archive/ 已归档内容 保留 可继续作为冷存储
frontend/ 旧前端/静态页面/可视化 部分保留 保留 methodology review 和 KG viewer；多版本 html/json 归档
static/ FastAPI 首页静态资源 运行保留 保留
config/ 配置与 Docker 核心保留 .env 注意脱敏

4. API 文件清单与判断

文件 作用 判断
api/main.py FastAPI app 主入口 保留
api/routes.py 聚合 rag/case 和预留接口 保留，但预留接口可标注 deprecated
api/rag_routes.py 当前 RAG 主接口 保留，核心
api/species_routes.py family-species 查询 保留
api/methodology_routes.py 方法学批处理/前端审阅接口 保留
api/case_routes.py Ft SPL 确定性 case QA 保留，作为真实案例测试
api/kg_routes.py KG 查询接口 保留，需确认数据源
api/kg_rag_routes.py KG-RAG fusion 保留/观察，若前端不用可降级
api/advanced_rag_routes.py query expansion、entity linking、fusion 等 保留/观察
api/raptor_routes.py RAPTOR 实验接口 实验保留，可后续归档
api/temporal_routes.py temporal KG 实验接口 实验保留，可后续归档
api/reasoning_routes.py reasoning demo 实验保留
api/rag_v10_routes.py V10 RAG 兼容接口 兼容保留，若不再测试 V10 可归档
api/rag_routes_backup.py 旧备份 归档/删除候选
api/rag_routes.py.bak 旧备份 归档/删除候选
api/methodology_api.py 独立 FastAPI app 归档候选
api/methodology_api_v2.py 独立 FastAPI app v2 归档候选
api/nohup.out 运行日志 删除候选
api/websocket.py 未见主 app 挂载 待确认，未用则归档

5. 核心脚本清单

当前建议保留为主线脚本：

文件 作用
scripts/build_index_from_v15_family.py 通用 v15 result.json -> RAG vector index
scripts/build_index_from_v15_spl.py SPL 旧入口兼容；应瘦身为纯 wrapper
scripts/build_family_fact_cards_from_v15.py v15/methodology -> family facts
scripts/build_gene_family_species_index.py family -> species 索引
scripts/build_bbav5_capability_catalog.py bbav5 能力目录
scripts/build_bbav5_methodology_reference.py 方法学参考配置
scripts/run_methodology_batch.py 方法学批处理
scripts/run_v15_extraction.py V15 单/批提取入口
scripts/batch_v15_extraction.py V15 批处理
scripts/evaluate_methodology_gold.py 方法学 gold 评估
scripts/evaluate_ft_spl_case_gold.py Ft SPL case 评估
scripts/run_ft_spl_case_qa.py case QA 验证

建议归档的脚本类别：

  1. build_rag_* 多版本构建脚本

    • build_rag_5.py
    • build_rag_50_30.py
    • build_rag_fast*.py
    • build_rag_test*.py
    • build_rag_v2.py
    • 原因：索引构建主线已迁到 build_index_from_v15_family.py。

  2. extract_v2_*、scripts/extractors/extract_v7_*、extract_v10_*

    • 原因：V15 为当前主线。
    • 建议迁到 archive/old_extractors/scripts/。

  3. Qdrant 迁移/测试多版本

    • migrate_to_qdrant*.py
    • test_qdrant*.py
    • 保留 1 个当前迁移脚本 + 1 个 smoke test，其余归档。

  4. 临时脚本

    • scripts/temp/*
    • 建议整体归档或删除。

  5. 重复处理脚本

    • process_*
    • move_failed*
    • rename_and_process_pdfs.py
    • 需要确认是否仍服务当前论文导入流程；否则归档。

6. 数据目录整理建议

6.1 运行必需数据

建议保留在 data/runtime/ 或继续保留但加索引说明：

  • data/rag_index_final_v15_spl/vector_index.pkl
  • data/rag_index_final_v15_1/vector_index.pkl
  • data/family_facts/spl.json
  • data/gene_family_species_index.json
  • data/cases.db
  • data/bbav5_capability_catalog.json
  • data/ft_spl_reproduction_case_package*.json
  • data/pc/*.json
  • data/test/SPL.hmm
  • data/test/proteins.fasta

6.2 评估数据

保留但应单独分区：

  • data/evaluation/
  • data/evaluation_results/
  • methodology_batch_*
  • evaluation/
  • benchmark_results/

建议形成：

  • data/evaluation/gold/
  • data/evaluation/runs/
  • data/evaluation/reports/

6.3 高体积语料

当前体积：

  • paper/: 约 3.6G
  • data/: 约 1.2G
  • backups/: 约 291M
  • v15_output/: 约 187M
  • frontend/: 约 132M
  • docs/: 约 106M
  • output/: 约 102M
  • src/: 约 101M

建议：

  1. paper/ 移到外部数据卷或 data/raw_papers/，代码库只保留 manifest。
  2. output/ 默认不入版本管理，保留 selected case。
  3. backups/ 打包冷存储，不参与日常搜索。
  4. v15_output/ 仅保留当前 gold/sample；全量运行结果移 data/evaluation/runs/ 或外部卷。

7. 当前主功能模块

7.1 文献问答

入口：

  • POST /api/v1/rag/chat

底层：

  • src/rag/vector_store.py
  • src/rag/embeddings.py
  • src/rag/hybrid_retriever.py
  • api/rag_routes.py

索引来源：

  • 默认 data/rag_index_final_v15_spl/vector_index.pkl
  • 可通过 RAG_VECTOR_INDEX 指定其他索引。

7.2 family structured facts

入口：

  • GET /api/v1/rag/family/pfam
  • GET /api/v1/rag/family/baseline
  • GET /api/v1/rag/family/stage-context

底层：

  • src/rag/family_facts.py
  • data/family_facts/*.json

用途：

  • 给分析项目 identify/discovery/result agent 提供结构化证据，避免自然语言正则。

7.3 species 查询

入口：

  • GET /api/v1/species/list
  • GET /api/v1/species/search
  • GET /api/v1/species/gene-families
  • GET /api/v1/species/stats

底层：

  • data/gene_family_species_index.json
  • scripts/build_gene_family_species_index.py

7.4 方法学复现支持

入口：

  • /api/v1/methodology/*

底层：

  • src/rag/unified/llm_methodology_extractor.py
  • src/rag/unified/bbav5_methodology_config.py
  • src/rag/unified/methodology_reviewer.py

用途：

  • 从论文 methods 抽取复现实验配置。
  • 生成 bbav5 stage 对齐参数。
  • 供前端人工审核。

7.5 Case QA

入口：

  • /api/v1/case/ft-spl/status
  • /api/v1/case/ft-spl/qa

底层：

  • src/rag/unified/case_qa.py
  • src/rag/unified/case_package.py
  • data/ft_spl_reproduction_case_package*.json

用途：

  • 稳定、确定性的真实复现案例问答。

8. 清理分级建议

P0：可立即清理或迁移

风险低，基本不影响运行：

  • __pycache__/
  • .pytest_cache/
  • .ruff_cache/
  • api/nohup.out
  • frontend/nohup.out
  • src/rag/*.bak
  • api/*backup*.py
  • api/*.bak
  • scripts/temp/
  • tests/__pycache__/

P1：需要先做引用检查再归档

  • src/rag/extractors/v13/
  • src/rag/extractors/v14/
  • src/rag/extractors/extract_v11_final.py
  • src/rag/extractors/extract_v12_*
  • scripts/extractors/extract_v7_*
  • scripts/extractors/extract_v10_*
  • scripts/build_rag_*
  • scripts/rebuild_index*
  • scripts/create_faiss_index*
  • api/rag_v10_routes.py
  • api/raptor_routes.py
  • api/temporal_routes.py
  • api/reasoning_routes.py

P2：保留但重命名/重构

  • scripts/build_index_from_v15_spl.py

    • 当前作为兼容入口。
    • 建议最终瘦身为 10 行以内 wrapper。

  • README.md

    • 内容明显停留在 V2.2/旧项目结构。
    • 应重写为 V15 + KG-RAG + methodology + bbav5 knowledge backend。

  • docs/

    • 文档很多但缺少当前主线索引。
    • 建议更新 docs/DOCS_INDEX.md，把历史文档全部标记为 historical。

  • frontend/

    • 多个 KG HTML/JSON 版本混杂。
    • 建议保留当前可用页面，其余迁入 archive/frontend_snapshots/。

9. 建议的目标目录结构

建议逐步整理成：

gene-family-mas-v2/
  api/
  src/
    rag/
      core/
      retrieval/
      extraction/
        v15/
      methodology/
      unified/
      storage/
  scripts/
    current/
    evaluation/
    migration/
    archive/
  data/
    runtime/
    facts/
    indexes/
    evaluation/
    raw_manifest/
  docs/
    current/
    architecture/
    api/
    history/
  tests/
    unit/
    integration/
    archive/
  archive/

不建议一次性移动大量文件。应按“先引用检查、再迁移、再跑测试”的顺序做。

10. 后续清理执行方案

Step 1：建立引用清单

对每个候选文件运行：

rg "文件名或模块名" .

输出：

  • 被 API 主入口引用：不可删。
  • 被 tests/current 引用：迁移前改测试。
  • 只被 docs/history 或 backup 引用：可归档。

Step 2：先清缓存和日志

清理目标：

  • __pycache__
  • .pytest_cache
  • .ruff_cache
  • *.pyc
  • nohup.out
  • 临时 log

Step 3：脚本重整

保留当前主线脚本到 scripts/current/：

  • family facts 构建
  • v15 family index 构建
  • species index 构建
  • methodology batch
  • case QA/evaluation
  • v15 extraction

其余迁入 scripts/archive/。

Step 4：抽取器重整

保留：

  • src/rag/extractors/v15/
  • 当前仍被 v15 import 的公共模块。

迁移：

  • v13/v14 和 v2-v12 历史抽取器。

Step 5：数据重整

建立 manifest：

  • 原始论文路径
  • v15 result 路径
  • gold/evaluation 路径
  • runtime index/facts 路径

然后将 paper/、output/、v14_output/、历史 v15_output/ 分批迁移。

11. 当前不要动的文件/目录

这些是当前主线或刚接入分析项目的关键点：

  • api/main.py
  • api/routes.py
  • api/rag_routes.py
  • api/species_routes.py
  • api/methodology_routes.py
  • api/case_routes.py
  • src/rag/family_facts.py
  • src/rag/base.py
  • src/rag/vector_store.py
  • src/rag/embeddings.py
  • src/rag/hybrid_retriever.py
  • src/rag/extractors/v15/
  • src/rag/unified/
  • src/llm/
  • scripts/build_index_from_v15_family.py
  • scripts/build_family_fact_cards_from_v15.py
  • scripts/build_gene_family_species_index.py
  • data/family_facts/
  • data/rag_index_final_v15_spl/
  • data/gene_family_species_index.json
  • data/pc/
  • methodology_batch_Ft_spl/
  • tests/test_*case*
  • tests/test_methodology_*
  • tests/test_unified_rag_simulated.py

12. 结论

当前项目的核心已经转向 V15 抽取 + KG-RAG + 方法学复现 + 分析项目知识服务。项目冗余主要来自多代抽取器、重复索引构建脚本、历史前端可视化文件、运行输出和大体积论文语料。

最稳妥的整理策略不是直接删除，而是：

  1. 先把当前主线写清楚。
  2. 给候选文件打标签。
  3. 按 P0/P1/P2 分批迁移。
  4. 每批迁移后跑 API smoke test 和当前 pytest。

建议下一步先执行 P0 清理和脚本目录重整，因为收益高、风险低。

Reference in New Issue View Git Blame Copy Permalink