# GDEFN 生物关联智能预测与分析系统软件设计说明书

## 1. 文档信息

| 项目 | 内容 |
| --- | --- |
| 软件全称 | GDEFN 生物关联智能预测与分析系统 |
| 软件简称 | GDEFN |
| 版本 | V1.0 |
| 文档版本 | V1.0 |
| 编制日期 | 2026-08-23 |
| 适用范围 | 科研预测、实验复现、数据质检与软著材料整理 |

## 2. 设计目标与边界

本软件将原有 GDEFN 论文代码封装成本地科研工作台，面向 miRNA–mRNA 关联识别与药物–靶标相互作用识别两类二分类任务。系统提供数据概览、节点或特征文件预测、快速基线评估、论文模型训练、检查点管理、质量审计、实验日志与结果溯源等功能。

本系统的结果是计算预测，不是已经湿实验验证的生物学事实，不得替代实验、药理评价或临床判断。

## 3. 总体架构

软件采用“浏览器界面—Flask 服务—预测/训练服务—原始科研资产”的分层架构。

```text
本地浏览器
    │  HTTP / JSON / CSV
    ▼
Flask 接口层（research_software/app.py）
    ├── 数据仓库与质检（predictor.py / DataRepository）
    ├── 局部图只读抽样（graph_service.py / GraphVisualizationService）
    ├── 快速 Diagonal LDA（predictor.py / BaselinePredictionService）
    ├── GDEFN 检查点推理（predictor.py / 完整模型服务）
    ├── 原始训练进程管理（training.py）
    └── 论文实验日志解析（research_log.py）
    │
    ▼
原始代码与数据（main.py / models.py / utils.py / datasets / logs / checkpoints）
```

### 3.1 展示层

`research_software/web` 承载单页科研界面，包含科研总览、智能预测、图网络可视化、模型评估、训练中心、数据质检、实验记录、模型架构和帮助页。图网络页使用原生 SVG 与浏览器端力导向布局，支持节点拖拽、画布平移、缩放、属性查看和 SVG 导出。界面仅请求同源接口，适合在 `127.0.0.1` 本地运行。

### 3.2 接口层

`app.py` 负责参数接收、输入校验、调用业务服务、统一 JSON 响应、历史记录及 CSV 导出。异常被区分为输入错误、引擎不可用、预测错误和服务器错误，避免将内部堆栈直接暴露给终端用户。

### 3.3 业务层

- `DataRepository` 懒加载并缓存特征、标签和划分索引，返回数据概况与只读质量报告。
- `GraphVisualizationService` 只读解析所选数据集/折次的原始边、标签和划分文件，以 0 基中心节点执行确定性广度优先搜索（BFS），返回局部诱导子图及统计量；线程安全 LRU 缓存只保存不可变内存对象。
- `BaselinePredictionService` 在选定数据集和折次的原始训练索引上现场拟合 Diagonal LDA，支持节点和外部同维特征预测。
- GDEFN 完整模型服务在依赖和对应活动检查点齐备时，调用原始 `models.py` 与 `utils.py` 完成整图推理。
- `TrainingManager` 以独立子进程调用原始 `main.py`，限制同时只有一个训练任务，并采集进度与末尾日志。
- `research_log.py` 只读解析 `logs/*.txt`，提取五折记录与 ACC、F1、Precision、Recall、Specificity、NPV 六项指标。

## 4. 便携式路径设计

系统不依赖某个固定盘符或用户目录。`config.py` 以文件自身位置为起点：

```text
SOFTWARE_DIR   = research_software 所在目录
PROJECT_ROOT   = SOFTWARE_DIR 的上级目录
DATASET_ROOT   = PROJECT_ROOT / datasets
CHECKPOINT_ROOT= PROJECT_ROOT / checkpoints
LOG_ROOT       = PROJECT_ROOT / logs
RUNTIME_ROOT   = SOFTWARE_DIR / runtime
WEB_ROOT       = SOFTWARE_DIR / web
```

原始训练代码也通过 `main.py` 和 `utils.py` 的脚本所在目录解析数据、日志与检查点。因此，整体复制或移动“完整代码”目录后，只要保留相对目录结构即可重新运行。API 的公开数据集元数据不返回绝对路径；检查点和日志路径以项目相对路径展示。

程序写入位置仅限于项目内：

- 预测历史：`research_software/runtime/prediction_history.jsonl`
- 训练进程日志：`research_software/runtime/training/*.log`
- 不可变训练运行：`checkpoints/<dataset>/runs/<run_id>/fold_01.pt` 至 `fold_05.pt`，每折同时保存 `.json` 元数据侧车文件
- 活动模型清单：`checkpoints/<dataset>/active_manifest.json`，只在同一运行的五折全部成功后原子切换
- 原始论文实验日志：`logs/*.txt`

## 5. 数据设计

### 5.1 数据集概况

| 数据集 | 节点数 | 特征维数 | 类别 | 折数 | 特征图 K |
| --- | ---: | ---: | ---: | ---: | ---: |
| miRNA–mRNA（`mi-m`） | 7,611 | 900 | 2 | 5 | 1 |
| Drug–Target（`dti`） | 2,664 | 500 | 2 | 5 | 5 |

标签在加载时统一为 0/1。如原标签的最小值大于 0，程序会整体减 1。

### 5.2 0 基索引约定

内置节点预测所接收的是特征矩阵行号，必须使用 **0 基索引**：

- `mi-m` 有效范围为 0–7610。
- `dti` 有效范围为 0–2663。

折次在用户界面和 API 中使用 1–5；原始 `load_data` 内部则使用 0–4，完整模型服务会自动执行 `fold - 1` 转换。

### 5.3 无实体映射的客观限制

原始 mi-m 数据资产只含数值特征、0/1 标签、图边与索引划分，没有随仓库提供 7,611 行完整实体名称表。系统因此对全部关系保留原始 0 基行索引，其中 16 条论文案例覆盖为已核验真实名称；DTI 2,664 条关系已通过固定上游嵌入快照完成全量映射。外部样本 ID 仅是输出追踪标识，不会自动转换为图节点。

### 5.4 DTI 划分审计与泄漏风险

系统对原始划分进行只读审计，不会默默清洗后再声称复现原实验。编制期检查得到：

- DTI 第 2 折的训练索引存在 1 个重复项，且节点 `623` 同时出现在训练与测试划分中。
- DTI 第 5 折的节点 `28` 同时出现在训练与测试划分中。
- 上述交叉会造成训练/测试泄漏风险，相关指标不应直接解释为完全独立测试性能。

DTI 没有独立验证文件。原始论文训练代码以固定随机方式将每折 2,000 个原始训练索引按 80%/20% 分成 1,600 个训练位置和 400 个验证位置；快速 Diagonal LDA 则明确使用原始训练文件中的全部 2,000 个位置拟合。这是两种引擎的另一口径差异。

如开展清洗后对照实验，必须生成新的、版本化的划分文件，单独标注“清洗后实验”，不得与原划分日志或论文指标混合引用。

### 5.5 图网络可视化数据语义

图网络页显示的是所选折次 `alledgXXX.txt` 的原始结构边，不是模型新预测出的关联。服务将边按无向边处理，把反向边和重复边规范为一个端点有序的唯一边；从中心节点开始，按照排序后的邻接节点执行确定性 BFS，最多选择请求数量的节点，再返回这些节点之间的全部诱导边。

节点属性中的 `label` 来自原始标签文件，`split` 来自所选折次的训练/验证/测试文件，`degree` 是该节点在完整折图中的唯一邻居数，不是当前显示子图内的度。接口严格拒绝越界编号、格式异常和互相冲突的划分归属，不会为绘图而静默修复原始数据。前端仅对返回子图执行力导向排布；布局位置不参与 GDEFN 训练或推理，也不代表生物距离。

## 6. 双预测引擎设计

| 特性 | 快速科研基线 | GDEFN 完整论文模型 |
| --- | --- | --- |
| 引擎标识 | `baseline-diagonal-lda` | `gdefn` |
| 来源标记 | `quick-baseline` | `gdefn-checkpoint` |
| 核心方法 | 对角协方差线性判别 | 三视图 GCN + DEF + UFE + 对比/一致性约束 |
| 拟合/加载 | 选定折次首次使用时现场拟合，进程内缓存 | 通过数据集的活动清单定位同一不可变运行中对应折次的 `.pt` 检查点 |
| 基本依赖 | NumPy | PyTorch、SciPy、scikit-learn、PyTorch Geometric |
| 节点索引预测 | 支持 | 支持 |
| 上传特征文件 | 支持 | 不支持；完整模型依赖整图 |
| 现场测试折评估 | 支持 | 当前 Web API 未提供 |
| 是否可以声称为论文模型结果 | 不可以 | 仅在检查点和配置匹配时可以 |

### 6.1 快速 Diagonal LDA

对两个类别分别计算特征均值和方差，使用池化对角方差与小正则项计算线性权重及截距，再通过 Sigmoid 转换为正类概率。该引擎的目的是低依赖、快速演示和基线对照，不使用图结构、三视图融合或论文检查点。

### 6.2 GDEFN 检查点推理

完整模型从融合图、度感知删边图与加边图学习三视图表征，经注意力融合后，注入 MLP 双编码器表征和 UFE 超图/图扩散表征，最后输出二分类对数概率。检查点包含 `state_dict`、`run_id`、数据集、折次、随机种子、最佳轮次、测试指标和模型配置等字段，并为每折生成不含权重的 JSON 元数据侧车文件。

训练运行以 `run_id` 创建不可变子目录，每折经完整推理与指标计算成功后，先写临时文件，再通过原子替换发布 `.pt` 和 `.json`。只有同一运行的五折都完成，才会以临时清单原子替换 `active_manifest.json`。中断或失败的运行可保留部分子目录供排查，但不会切换当前活动模型；如此前尚无活动清单，完整引擎继续保持不可用。

推理前，系统校验活动清单的格式、模型名、数据集、折次相对路径与路径边界，校验侧车元数据的特征数和类别数，并要求支持 `weights_only=True` 的安全 PyTorch 加载器。加载后还会再校验检查点内部元数据，并计算 SHA-256 写入结果溯源。任一校验失败都返回“引擎不可用”，不允许自动退化为快速基线却仍使用 GDEFN 名义。日志文件不能替代模型权重。

`models.py` 中的核心模型类为 `GDEFN_MH_Fusion`；软件名称、模型名称、界面标签和结果来源字段均统一使用 GDEFN 口径。

## 7. 主要业务流程

### 7.1 内置节点预测

1. 校验数据集、折次、阈值、引擎和 0 基节点索引。
2. 加载/拟合选定引擎。
3. 计算正类概率，按阈值转为 0/1 结论。
4. 附加引擎来源、参考标签、数据划分、置信度分档与耗时。
5. 将结果追加写入 JSONL 历史，可按运行编号导出 CSV。

### 7.2 特征文件预测

1. 仅接受 UTF-8 的 CSV、TSV 或 TXT，上限 20 MB。
2. 可有表头，每行可为纯特征，或“1 个样本 ID + 全部特征”。
3. `mi-m` 必须有 900 个数值特征，`dti` 必须有 500 个数值特征。
4. 检查列数一致性、数值性、有限性与批量上限 5,000 行。
5. 仅调用快速 Diagonal LDA；外部特征不会被自动接入 GDEFN 整图。

### 7.3 图网络可视化

图网络浏览是独立的只读流程：

1. 校验数据集、折次、0 基中心节点和最大显示节点数。
2. 读取或命中缓存中的标签、划分和原始结构边，规范化唯一无向边。
3. 以中心节点执行确定性 BFS，构建局部诱导子图和节点/边统计。
4. 前端按标签、数据划分或完整图度数着色，执行交互式力导向布局。
5. 用户可查看节点属性并导出当前画布为 SVG；该流程不写原始数据、不调用预测引擎。

### 7.4 训练与检查点

1. 校验数据集、轮次 10–5000、早停耐心值、随机种子和设备名。
2. 以当前 Python 解释器启动 `main.py --save-checkpoints`。
3. 原始脚本执行五折训练、早停与测试，每折将最优状态和元数据原子写入 `runs/<run_id>/`。
4. 五折全部成功后原子替换活动清单；中断、停止或任一折失败都不会切换活动模型。
5. 后台管理器读取标准输出，更新折次、轮次、状态与日志末尾。

## 8. API 设计摘要

| 方法 | 路径 | 用途 | 是否写入 |
| --- | --- | --- | --- |
| GET | `/api/status` | 运行环境、检查点与训练状态 | 否 |
| GET | `/api/model` | 软件与模型元数据 | 否 |
| GET | `/api/datasets` | 数据概况和质量报告 | 否 |
| GET | `/api/graph/sample` | 按中心节点返回只读局部结构子图 | 否 |
| GET | `/api/research/metrics` | 最新完整实验指标 | 否 |
| GET | `/api/research/experiments` | 原始日志目录 | 否 |
| GET | `/api/research/experiments/<filename>` | 实验详情 | 否 |
| POST | `/api/predict/nodes` | 节点索引预测 | 是，预测历史 |
| POST | `/api/predict/file` | 特征文件快速基线预测 | 是，预测历史 |
| POST | `/api/evaluate` | 快速基线的指定测试折评估 | 是，预测历史 |
| GET | `/api/template/<dataset>.csv` | 下载特征模板 | 否 |
| GET | `/api/history` | 查看预测/评估摘要 | 否 |
| GET | `/api/history/<run_id>/export.csv` | 导出逐样本结果 | 否 |
| POST | `/api/training/start` | 启动原始五折训练 | 是，日志与检查点 |
| GET | `/api/training/status` | 训练进度和日志末尾 | 否 |
| POST | `/api/training/stop` | 停止当前训练进程 | 是，进程状态 |

## 9. 安全性与稳定性

- 默认仅监听 `127.0.0.1:7860`，不主动对公网暴露。
- 上传类型、大小、编码、列数、行数和数值有限性均受校验。
- 节点批量上限为 5,000，阈值限制为 0.05–0.95。
- 图接口严格限制数据集、折次、0 基中心节点与采样规模；Web 控件允许显示 20–100 个节点，服务端硬上限为 500。
- 输出 CSV 对以 `=`、`+`、`-`、`@` 开头的文本值添加前缀，降低表格公式注入风险。
- API 返回 `nosniff`、`SAMEORIGIN`、`no-referrer`、CSP 和 `no-store` 等响应头。
- 文件名和实验日志查询通过取基名限制路径穿越。
- 模型训练不自动联网安装依赖，不在用户不知情时更改系统环境。

## 10. 评估指标与溯源

快速基线现场评估计算 Accuracy、F1、Precision、Recall、Specificity、NPV、AUC 和混淆矩阵。AUC 使用能处理并列分数的 Mann–Whitney 秩方法，ROC 曲线生成 31 个阈值点供页面绘制。

结果口径必须按以下来源区分：

- `quick-baseline` / `quick-baseline-evaluation`：本次运行现场计算，不是论文 GDEFN 结果。
- `gdefn-checkpoint`：来自活动检查点的 GDEFN 完整模型节点推理。
- `logs/*.txt`：原始训练日志中的历史五折指标；日志本身不是可推理的权重。

每次软件预测生成唯一 `RUN-...` 编号、时间、引擎、数据集、折次、阈值和耗时，支持后续审计。

## 11. 已知限制与后续扩展

1. 数据不含生物实体名称映射，当前不支持按药物名、基因名或 miRNA 名检索。
2. DTI 原始划分存在重复与训练/测试交叉，需在论文或报告中明确披露。
3. 完整 GDEFN 仅支持内置整图上的节点索引推理；接纳全新实体需要定义特征、图接入和重新训练方案。
4. 完整模型推理必须有兼容依赖和每折检查点；仅有历史指标不足以启用。
5. 预测历史使用本地 JSONL，适合单机科研；如扩展多用户部署，需另行增加身份认证、数据库和权限审计。
6. 如进行远程部署，不应直接复用开发服务器，应增加生产级 WSGI、TLS、访问控制和运维策略。
7. 图网络视图是原始结构图的局部浏览工具；BFS 截断、力导向坐标和着色方式不能解释为完整模型注意力、预测置信度或生物机制证据。

## 12. 文件结构

```text
完整代码/
├── main.py                    # 原始五折训练与检查点保存
├── models.py                  # GDEFN 模型定义（核心类 GDEFN_MH_Fusion）
├── utils.py                   # 数据加载与图构建
├── datasets/                  # 内置数据和折次划分
├── logs/                      # 原始训练日志
├── checkpoints/               # 不可变运行、每折元数据与活动清单
└── research_software/
    ├── app.py                 # Web 应用入口和 API
    ├── config.py              # 便携式配置与元数据
    ├── predictor.py           # 数据仓库、双预测引擎和指标
    ├── graph_service.py       # 原始结构图只读解析、缓存与局部 BFS 抽样
    ├── training.py            # 后台训练进程管理
    ├── research_log.py        # 实验日志解析
    ├── web/                   # 前端页面、样式与交互脚本
    ├── runtime/               # 本地运行期记录
    ├── tests/                 # 自动化测试
    └── docs/                  # 设计、使用、软著与测试文档
```