GermCell-YOLOv8

基于 YOLOv8 的男性生殖细胞检测工具，用于从显微镜图像中检测和分类不同类型的生殖细胞。

项目结构

GermCell-YOLOv8/
├── configs/              # 配置文件
│   └── data.yaml        # 数据集配置文件
├── dataset/              # 数据集目录
│   ├── images/          # 图像文件
│   │   ├── train/       # 训练集图像
│   │   └── val/         # 验证集图像
│   └── labels/          # 标注文件
│       ├── train/       # 训练集标注
│       └── val/         # 验证集标注
├── scripts/             # 脚本文件
│   ├── train.py        # 训练脚本
│   ├── predict.py      # 推理脚本
│   └── export.py       # 模型导出脚本
├── runs/                # 训练输出（自动生成）
├── requirements.txt     # Python 依赖
└── README.md           # 项目说明

安装环境

方法一：自动安装（推荐）

运行智能安装脚本，会自动检测系统并安装合适的 PyTorch 版本：

Windows:

# 1. 创建虚拟环境
python -m venv venv
venv\Scripts\activate

# 2. 运行自动安装脚本
python scripts/setup.py

Mac/Linux:

# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 2. 运行自动安装脚本
python scripts/setup.py

脚本会自动：

• ✅ 检测是否有 NVIDIA GPU
• ✅ 检测 CUDA 版本
• ✅ 安装对应的 PyTorch 版本（GPU 或 CPU）
• ✅ 安装所有其他依赖
• ✅ 验证安装是否成功

方法二：手动安装

如果你想手动安装：

Windows:

# 1. 创建虚拟环境
python -m venv venv
venv\Scripts\activate

# 2. 安装依赖
pip install -r requirements.txt

Mac/Linux:

# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 2. 安装依赖
pip install -r requirements.txt

注意: 手动安装时，requirements.txt 不包含 PyTorch，需要根据你的系统手动安装：

• 有 GPU: pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
• 无 GPU: pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

3. 验证安装

python -c "from ultralytics import YOLO; print('安装成功！')"

准备数据集

数据集目录结构

请确保数据集按以下结构组织：

dataset/
├── images/
│   ├── train/          # 训练集图像（.jpg, .png 等）
│   └── val/            # 验证集图像
└── labels/
    ├── train/          # 训练集标注（.txt）
    └── val/            # 验证集标注

标注格式

使用 YOLO 格式的文本文件（.txt），每个图像对应一个同名的标注文件。

标注文件格式：每行一个目标对象

class_id x_center y_center width height

• class_id: 类别ID（0-3，对应4种细胞类型）
• x_center, y_center: 边界框中心点坐标（归一化到 0-1）
• width, height: 边界框宽度和高度（归一化到 0-1）

类别说明

本项目检测4种男性生殖细胞类型：

• 0: Primary spermatocyte - 初级精母细胞
• 1: Secondary spermatocyte - 次级精母细胞
• 2: Spermatogonium - 精原细胞
• 3: Spermatozoa - 精子

训练

基本训练

运行训练脚本：

python scripts/train.py

训练参数说明

默认训练参数（可在 scripts/train.py 中修改）：

• 模型: yolov8n.pt (YOLOv8 nano，最小最快)
• 图像尺寸: 640x640
• 训练轮数: 50 epochs
• 批次大小: 16
• 工作进程: 4
• 设备: cuda (如果有GPU，否则自动使用CPU)

训练输出

训练完成后，模型权重保存在：

• runs/detect/train/weights/best.pt - 最佳模型
• runs/detect/train/weights/last.pt - 最后一轮模型

训练日志和结果图表保存在 runs/detect/train/ 目录。

自定义训练参数

如需修改训练参数，编辑 scripts/train.py：

model.train(
    data="configs/data.yaml",
    imgsz=640,        # 图像尺寸
    epochs=100,       # 训练轮数
    batch=32,         # 批次大小
    workers=8,        # 数据加载进程数
    device="cuda",    # 设备：cuda 或 cpu
    patience=50,      # 早停耐心值
    save=True,        # 保存检查点
    project="runs",   # 项目目录
    name="detect"     # 实验名称
)

推理

基本推理

运行推理脚本（自动使用最新训练的模型）：

python scripts/predict.py

脚本会自动：

1. 查找训练后的最佳模型（runs/detect/train/weights/best.pt）
2. 使用验证集图像进行推理（dataset/images/val/）
3. 保存结果到 runs/detect/predict/ 目录

推理参数

默认推理参数：

• 置信度阈值: 0.5
• 推理源: dataset/images/val/
• 保存结果: 是

如需修改参数，编辑 scripts/predict.py 中的 model.predict() 调用。

推理结果

推理结果保存在 runs/detect/predict/ 目录，包括：

• 带检测框的图像
• 检测结果信息

导出模型

基本导出

导出为 ONNX 格式（默认）：

python scripts/export.py

指定导出格式

支持以下格式：

# ONNX 格式（推荐，跨平台）
python scripts/export.py --format onnx

# PyTorch 格式
python scripts/export.py --format pt

# OpenVINO 格式（Intel 优化）
python scripts/export.py --format openvino

# TensorRT 引擎（NVIDIA GPU）
python scripts/export.py --format engine

# TorchScript 格式
python scripts/export.py --format torchscript

指定模型路径

如果模型不在默认位置，可以指定路径：

python scripts/export.py --model runs/detect/train/weights/best.pt --format onnx

导出参数说明

• --model: 模型文件路径（可选，默认使用最新训练的模型）
• --format: 导出格式（可选：onnx, pt, openvino, engine, torchscript，默认：onnx）

配置文件

data.yaml

数据集配置文件位于 configs/data.yaml：

path: dataset              # 数据集根目录
train: images/train        # 训练集路径（相对于 path）
val: images/val            # 验证集路径（相对于 path）

names:                     # 类别名称
  0: Primary spermatocyte
  1: Secondary spermatocyte
  2: Spermatogonium
  3: Spermatozoa

常见问题

1. 找不到模型文件

问题: 运行推理或导出时提示找不到模型文件

解决:

• 确保已经完成训练
• 检查 runs/detect/train/weights/ 目录是否存在 best.pt 文件
• 或使用 --model 参数指定模型路径

2. CUDA 内存不足

问题: 训练时出现 CUDA out of memory 错误

解决:

• 减小批次大小（batch）：将 batch=16 改为 batch=8 或更小
• 减小图像尺寸（imgsz）：将 imgsz=640 改为 imgsz=416 或 imgsz=320
• 使用更小的模型：将 yolov8n.pt 改为 yolov8n.pt（已是最小）

3. 数据集路径错误

问题: 训练时提示找不到数据集

解决:

• 检查 configs/data.yaml 中的 path 是否正确
• 确保数据集目录结构正确
• 确保图像和标注文件名称对应（除了扩展名）

4. 推理结果不理想

问题: 检测精度低或漏检

解决:

• 增加训练轮数（epochs）
• 使用更大的模型（如 yolov8s.pt, yolov8m.pt）
• 增加数据增强
• 检查标注质量
• 调整置信度阈值

依赖说明

主要依赖包：

• ultralytics>=8.1.0 - YOLOv8 核心库
• opencv-python - 图像处理
• numpy - 数值计算
• pyyaml - YAML 配置文件解析
• tqdm - 进度条显示

许可证

本项目基于 Ultralytics YOLOv8，请遵循相应的开源许可证。

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

• v1.0.0: 初始版本，支持训练、推理和模型导出