# 血细胞智能识别分析系统

**Repository Path**: peakb_admin/blood-cell-analyzer

## Basic Information

- **Project Name**: 血细胞智能识别分析系统
- **Description**: 本系统是面向专业化验场景的临床辅助诊断平台。采用“本地边缘计算 + 云端大模型”协同架构：前端基于 Electron、React 与 TypeScript 构建高性能交互界面；后端通过 FastAPI 部署 YOLO (ONNX) 模型实现毫秒级细胞检测与计数；针对复杂病理，集成云端多模态大模型生成辅助分析报告。系统旨在为医疗工作者提供专业、高效、智能的数字化化验工具。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 血细胞智能识别分析系统

血细胞智能识别分析系统是一个面向骨髓血细胞显微图像分析的桌面端与后端一体化项目。系统支持患者样本管理、显微图上传、YOLO 细胞检测、二阶段细胞分类、人工校正、统计分析、报告生成和训练资产归档。

本项目的核心目标不是替代医学诊断，而是构建一个可复现、可迭代、可交互复核的血细胞识别分析原型，帮助完成从数据标注、模型训练到软件集成的完整工程闭环。

## 项目亮点

- 支持四代检测模型并列选择：原始 49 类分割、几何单类分割、CVAT 粗分类模型三、CVAT 增强粗分类模型四。
- 支持 MLL 骨髓单细胞精分类模型作为二阶段分类器，缓解非医学专业学生难以完成细粒度标注的问题。
- 支持整张样本大图矩形标注和 CVAT 数据导出，标注数据已按训练迭代归档。
- 支持检测框重叠去重、切片边缘过滤、模型策略隔离，避免不同模型推理参数互相干扰。
- 前端样本分析界面支持标记图/原图切换、横向样本浏览、原图框内修改类别、单例缩略图来源预览。
- 文档、训练脚本、训练结果、CVAT 数据和关键模型权重已整理成可答辩、可交接的结构。

## 技术栈

- 桌面端：Electron、React 18、TypeScript、Vite、Tailwind CSS
- 后端：FastAPI、Pydantic、SQLAlchemy
- 异步任务：Celery、Redis
- 数据与对象存储：MySQL、MinIO
- 模型训练与推理：Ultralytics YOLO detect/segment/classify、PyTorch
- 标注工具：CVAT
- 文档与分析：python-docx、openpyxl、matplotlib

## 项目结构

```text
blood-cell-analyzer/
├─ backend/                  # FastAPI 后端、模型推理、报告统计、任务接口
├─ desktop/                  # Electron + React 桌面端
├─ docs/                     # 项目文档
│  ├─ plan/                  # 计划阶段文档
│  ├─ midterm/               # 中期标注、训练路线和 CVAT 说明
│  ├─ final/                 # 最终交付文档和训练可视化报告
│  └─ api/                   # OpenAPI 契约和接口约定
├─ training/
│  ├─ cell_segmentation/     # 原始分割、CVAT/MLL 转换和训练脚本
│  ├─ two_stage/             # dataset1+dataset2 几何单类训练说明
│  └─ iterations/            # 按模型代际归档的训练资产
├─ runs/                     # 本地 YOLO 训练输出，README 说明归档规则
├─ cvat/                     # 本地 CVAT 部署/导出目录，README 说明标注归档
├─ outputs/                  # 文档和报告生成输出
├─ scripts/                  # 启动、转换、文档生成和训练归档脚本
├─ docker-compose.yml
└─ README.md
```

## 模型体系

| 模型 | 训练来源 | 任务粒度 | 软件用途 |
| --- | --- | --- | --- |
| 模型一 | `dataset1` 原始标注 | 49 类实例分割 | 旧细分类基线，用于对比分析 |
| 模型二 | `dataset1 + dataset2` | 单类几何分割 | 只检测细胞位置，类别统一为单细胞 |
| 模型三 | CVAT `myData_3` | 粗分类矩形检测 | 第一轮人工粗标注训练结果 |
| 模型四 | CVAT `myData_4` | 扩充粗分类矩形检测 | 当前主要检测模型 |
| MLL 分类器 | TCIA MLL 单细胞数据集 | 精细类别分类 | 对模型三/四检测框进行二阶段识别 |

训练资产入口：

- [training/iterations/README.md](training/iterations/README.md)
- [docs/final/reports/README.md](docs/final/reports/README.md)
- [runs/README.md](runs/README.md)

## 文档入口

- [docs/README.md](docs/README.md)：项目文档总览
- [docs/plan/README.md](docs/plan/README.md)：计划阶段文档
- [docs/midterm/README.md](docs/midterm/README.md)：中期标注和训练路线文档
- [docs/final/README.md](docs/final/README.md)：最终交付文档
- [docs/api/README.md](docs/api/README.md)：API 契约说明

最终交付件包括项目计划书、需求规格说明书、设计说明书、系统测试报告、测试用例表、用户手册、安装维护手册和训练可视化分析报告。

## 快速启动

### 1. 后端环境

复制后端配置：

```powershell
copy .\backend\.env.example .\backend\.env
```

如需使用 GPU 推理，请在 `backend/.env` 中确认模型路径、`CELL_SEG_DEVICE` 和二阶段分类器路径。

### 2. Docker 联调

```powershell
docker compose up --build
```

默认服务：

- 后端 API：`http://127.0.0.1:8000`
- API 文档：`http://127.0.0.1:8000/docs`
- MySQL：`3306`
- Redis：`6379`
- MinIO：按 `docker-compose.yml` 配置

### 3. 本地桌面端

```powershell
cd .\desktop
npm install
npm run dev
```

开发环境默认通过 `desktop/.env.development` 将 `/api` 代理到后端服务。

## 常用开发命令

后端测试：

```powershell
D:\anaconda3\python.exe -m pytest backend\tests
```

前端构建：

```powershell
cd .\desktop
npm run build
```

重新生成最终文档：

```powershell
D:\anaconda3\python.exe scripts\build_final_core_documents.py
D:\anaconda3\python.exe scripts\build_delivery_documents.py
D:\anaconda3\python.exe scripts\build_training_visual_report.py
```

重新归档训练迭代：

```powershell
D:\anaconda3\python.exe scripts\archive_training_iterations.py
```

## 数据与标注

原始大数据集默认位于本地 `dataset/`，不整体纳入仓库。CVAT 人工标注导出已压缩归档：

- `training/iterations/model-03-cvat-coarse-myData3/data/myData_3.zip`
- `training/iterations/model-04-cvat-coarse-myData4/data/myData_4.zip`

CVAT 标签配置和操作说明位于 [docs/midterm/cvat-labeling](docs/midterm/cvat-labeling/README.md)。

## 注意事项

1. 本系统是课程/毕业设计性质的辅助分析系统，不应作为临床诊断依据。
2. `runs/` 和 `cvat/` 是本地工作目录，默认只提交 README 和必要归档，不提交完整缓存。
3. 新增模型时需要同步更新后端模型槽位、环境变量示例、训练归档和最终文档。
4. 若 PowerShell 中 `conda activate yolo_gpu` 失败，可使用 `D:\anaconda3\envs\yolo_gpu\python.exe` 直接运行训练脚本。

---

英文早期说明见 [README.en.md](README.en.md)。