动手创建 Unet_V2 项目并搭建目录结构
在深度学习项目的实际开发中，一个常见但又容易被忽视的问题是：为什么同样的代码，在不同机器上跑出了不同的结果？甚至根本无法运行？
答案往往不在于模型本身，而在于“环境”和“结构”——缺少隔离的依赖环境、混乱的文件组织、硬编码的路径配置……这些看似琐碎的问题，最终会演变成复现失败、协作困难、维护成本高昂的大麻烦。
为了解决这些问题，我们不会一上来就写模型，而是先花点时间把地基打牢。本文将带你从零开始，基于Miniconda-Python3.10镜像，完整构建一个模块化、可扩展、易于维护的图像分割项目UnetV2-RetinaSegmentation。这个过程不仅是为了跑通代码，更是为了建立一套工程级的最佳实践。
使用 Miniconda-Python3.10 构建独立开发环境
要保证实验可复现，第一步就是环境隔离。Python 项目中最让人头疼的就是包版本冲突：今天装的 PyTorch 明天和其他库打架，或者团队成员之间因为 CUDA 版本不一致导致代码报错。
这时候轻量级的 Miniconda 就派上了用场。它不像 Anaconda 那样臃肿，却同样支持虚拟环境管理，非常适合科研与工程场景。
镜像特性一览
该镜像预装了 Python 3.10 和 Conda 环境管理系统，并集成了 Jupyter Notebook，开箱即用。你可以快速创建专属于项目的独立环境，避免全局污染。
交互式调试：Jupyter 的使用方式
启动容器后，通过浏览器访问 Jupyter 页面：
点击右上角 “New” → “Python 3 (ipykernel)” 新建 notebook：
在单元格中执行以下测试代码，确认核心依赖是否可用：
import sys print("Python version:", sys.version) import torch print("PyTorch version:", torch.__version__) print("CUDA available:", torch.cuda.is_available())如果输出类似如下内容，说明基础框架正常：
Python version: 3.10.12 | packaged by conda-forge PyTorch version: 2.1.0+cu118 CUDA available: True命令行操作：SSH 连接推荐
对于远程服务器或云平台部署，更推荐使用 SSH 登录进行命令行操作。
连接成功后，查看当前所有 conda 环境：
conda info --envs输出示例：
base * /opt/miniconda unet_v2 /opt/miniconda/envs/unet_v2激活你的项目环境（假设已命名为unet_v2）：
conda activate unet_v2安装必要的依赖项（以 GPU 支持为例）：
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 pip install matplotlib scikit-image opencv-python tensorboard至此，干净、可控的运行环境已经准备就绪，可以进入项目搭建阶段。
搭建清晰且可扩展的项目目录结构
一个好的项目结构，应该做到“一看就懂、一改就灵”。模块职责分明，路径统一管理，后续无论是添加新模型还是更换数据集，都能轻松应对。
我们在工作目录下创建主项目文件夹：
mkdir UnetV2-RetinaSegmentation cd UnetV2-RetinaSegmentation然后建立如下层级化的目录结构：
UnetV2-RetinaSegmentation/ ├── dataset/ │ ├── train/ │ │ ├── images/ │ │ └── masks/ │ └── valid/ │ ├── images/ │ └── masks/ │ ├── core/ │ ├── __init__.py │ ├── config_v2.py │ ├── train_unetv2.py │ ├── test_unetv2.py │ └── checkpoint_v2.py │ ├── model/ │ ├── __init__.py │ ├── encoder_v2.py │ ├── sdi_module.py │ ├── decoder_v2.py │ ├── unetv2.py │ ├── loss_v2.py │ └── blocks_v2.py │ ├── utils/ │ ├── __init__.py │ ├── data_utils_v2.py │ ├── preprocess_v2.py │ ├── metrics_v2.py │ ├── visualization_v2.py │ ├── logger_v2.py │ └── misc_v2.py │ ├── weights/ │ ├── unetv2_best_model.pth │ ├── unetv2_last_model.pth │ └── unetv2_exp*.pth │ ├── runs/ │ ├── train_v2/ │ └── test_v2/ │ ├── main_unetv2.py └── test_single_image_v2.py这种分层设计有几个关键考量：
dataset/：数据集中存放，便于统一管理和版本控制（可通过.gitignore排除大文件）。model/：所有网络组件拆解为独立模块，方便替换编码器（如从 CNN 切换到 Swin Transformer）。utils/：工具函数按功能划分，避免出现一个几千行的utils.py。weights/和runs/：明确区分权重保存与运行输出，避免日志和模型混杂。
这样的结构不仅利于个人开发，也极大提升了团队协作效率。
初始化包结构与模块导入机制
为了让各子模块之间能够顺畅引用，必须正确设置 Python 包结构。否则会出现ModuleNotFoundError或相对导入失败等问题。
创建__init__.py文件
在core/,model/,utils/目录下分别创建空的__init__.py文件：
touch core/__init__.py model/__init__.py utils/__init__.py这一步虽小，却是整个项目模块化的重要标志。有了它，你就可以用标准语法跨模块导入：
from core.config_v2 import cfg_v2 from model.unetv2 import UNetV2 from utils.data_utils_v2 import RetinaDatasetV2占位实现关键模块用于验证导入
为了确保结构可行，我们先写几个最小化的占位类来测试导入流程。
全局配置类（初步）
# core/config_v2.py from pathlib import Path class ConfigV2: PROJECT_ROOT = Path(__file__).resolve().parents[1] PROJECT_NAME = "UnetV2-RetinaSegmentation" VERSION = "0.1.0" DATASET_DIR = PROJECT_ROOT / "dataset" cfg_v2 = ConfigV2()模型占位类
# model/unetv2.py import torch import torch.nn as nn from core.config_v2 import cfg_v2 class UNetV2(nn.Module): def __init__(self, in_channels=1, num_classes=1): super().__init__() self.in_channels = in_channels self.num_classes = num_classes self.dummy = nn.Identity() def forward(self, x): b, _, h, w = x.shape return torch.zeros(b, self.num_classes, h, w, device=x.device)数据集占位类
# utils/data_utils_v2.py from typing import Tuple from pathlib import Path import torch from torch.utils.data import Dataset from core.config_v2 import cfg_v2 class RetinaDatasetV2(Dataset): def __init__(self, img_size: Tuple[int, int] = (256, 256)): self.img_size = img_size self._length = 10 def __len__(self): return self._length def __getitem__(self, idx): c, h, w = 1, *self.img_size img = torch.zeros(c, h, w, dtype=torch.float32) mask = torch.zeros(1, h, w, dtype=torch.float32) return img, mask编写导入测试脚本
# test_import.py from core.config_v2 import cfg_v2 from model.unetv2 import UNetV2 from utils.data_utils_v2 import RetinaDatasetV2 def main(): print("=== test_import.py: Import Check ===") print(f"Project: {cfg_v2.PROJECT_NAME} v{cfg_v2.VERSION}") print(f"Root path: {cfg_v2.PROJECT_ROOT}") model = UNetV2() print(f"Model created: in_ch={model.in_channels}, out_ch={model.num_classes}") dataset = RetinaDatasetV2() print(f"Dataset length: {len(dataset)}") print("=== All imports OK! ===") if __name__ == "__main__": main()运行命令：
python test_import.py若输出如下，则说明模块系统已打通：
=== test_import.py: Import Check === Project: UnetV2-RetinaSegmentation v0.1.0 Root path: /path/to/UnetV2-RetinaSegmentation Model created: in_ch=1, out_ch=1 Dataset length: 10 === All imports OK! ===这是项目构建中的第一个里程碑——意味着我们可以安全地继续向下推进，而不必担心后期因导入问题导致重构。
完整配置管理：config_v2.py 的设计哲学
随着项目复杂度上升，硬编码参数将成为维护噩梦。因此我们将config_v2.py升级为全局唯一的配置中心。
# core/config_v2.py from pathlib import Path import torch from typing import Tuple class ConfigV2: """ UnetV2-RetinaSegmentation 项目的全局配置类。 统一管理路径、超参、设备策略等，避免散落在各处的 magic number。 """ # ========== 基本信息 ========== PROJECT_ROOT: Path = Path(__file__).resolve().parents[1] PROJECT_NAME: str = "UnetV2-RetinaSegmentation" VERSION: str = "0.2.0" # ========== 数据路径 ========== DATASET_DIR: Path = PROJECT_ROOT / "dataset" TRAIN_IMG_DIR: Path = DATASET_DIR / "train" / "images" TRAIN_MASK_DIR: Path = DATASET_DIR / "train" / "masks" VALID_IMG_DIR: Path = DATASET_DIR / "valid" / "images" VALID_MASK_DIR: Path = DATASET_DIR / "valid" / "masks" IMG_SIZE: Tuple[int, int] = (256, 256) # H, W IN_CHANNELS: int = 1 NUM_CLASSES: int = 1 # ========== 模型结构 ========== ENCODER_TYPE: str = "cnn" # 'cnn', 'resnet', 'swin' BASE_CHANNELS: int = 64 USE_SDI: bool = True SDI_FUSION_MODE: str = "hadamard" # 'add', 'concat', 'hadamard' SDI_LEVELS: tuple = (1, 2, 3, 4) # ========== 训练参数 ========== BATCH_SIZE: int = 4 NUM_EPOCHS: int = 100 LEARNING_RATE: float = 1e-4 WEIGHT_DECAY: float = 1e-5 LR_SCHEDULER: str = "none" # 'step', 'cosine', 'plateau' NUM_WORKERS: int = 4 PIN_MEMORY: bool = True RANDOM_SEED: int = 42 # ========== 预处理 ========== USE_GREEN_CHANNEL: bool = True USE_CLAHE: bool = True CLAHE_CLIP_LIMIT: float = 2.0 CLAHE_TILE_GRID_SIZE: tuple = (8, 8) # ========== 设备 ========== DEVICE: str = "cuda" if torch.cuda.is_available() else "cpu" # ========== 路径管理 ========== WEIGHTS_DIR: Path = PROJECT_ROOT / "weights" BEST_MODEL_PATH: Path = WEIGHTS_DIR / "unetv2_best_model.pth" LAST_MODEL_PATH: Path = WEIGHTS_DIR / "unetv2_last_model.pth" RUNS_DIR: Path = PROJECT_ROOT / "runs" TRAIN_LOG_DIR: Path = RUNS_DIR / "train_v2" TEST_LOG_DIR: Path = RUNS_DIR / "test_v2" SINGLE_INFER_DIR: Path = RUNS_DIR / "single_v2" # 全局实例 cfg_v2 = ConfigV2() # 向后兼容旧命名 cfg = cfg_v2这个类的设计思路是“集中声明 + 实例共享”：所有配置项在一个地方定义，通过单例模式全局访问。这样做的好处非常明显：
- 修改 batch size 不需要去翻三四个文件；
- 更换数据路径只需改一处；
- 支持未来扩展为 JSON/YAML 配置加载器。
更重要的是，它让整个项目具备了“一次定义，处处生效”的能力。
自动化初始化脚本：setup_project.py
每次新建项目都要手动检查目录是否存在？太低效了。我们写一个自动化脚本来完成这件事。
# setup_project.py """ 项目初始化脚本：检查数据集路径，自动创建输出目录。 """ from pathlib import Path from core.config_v2 import cfg_v2 def setup_directories(): root = cfg_v2.PROJECT_ROOT print(f"[Setup] Project Root : {root}") print(f"[Setup] Project Name : {cfg_v2.PROJECT_NAME}") print(f"[Setup] Version : {cfg_v2.VERSION}\n") # 检查 dataset print("[Setup] Checking dataset directory...") if not cfg_v2.DATASET_DIR.exists(): print(f" [ERROR] Dataset directory not found: {cfg_v2.DATASET_DIR}") print(" 请将 dataset/ 文件夹复制到项目根目录下。") else: print(f" [OK] Dataset exists: {cfg_v2.DATASET_DIR}") for p in [ cfg_v2.TRAIN_IMG_DIR, cfg_v2.TRAIN_MASK_DIR, cfg_v2.VALID_IMG_DIR, cfg_v2.VALID_MASK_DIR ]: status = "[OK]" if p.exists() else "[MISSING]" print(f" {status} {p.name:12}: {p}") print("\n[Setup] Creating output directories...") dirs_to_create = [ cfg_v2.WEIGHTS_DIR, cfg_v2.RUNS_DIR, cfg_v2.TRAIN_LOG_DIR, cfg_v2.TEST_LOG_DIR, cfg_v2.SINGLE_INFER_DIR, ] for d in dirs_to_create: d.mkdir(parents=True, exist_ok=True) status = "[Exists]" if d.exists() else "[Created]" print(f" {status} {d}") print("\n[Setup] Project setup completed.\n") if __name__ == "__main__": setup_directories()运行脚本：
python setup_project.py它会自动检测输入路径完整性，并创建所有必要的输出目录。以后每次克隆项目到新机器，只需运行这一条命令即可快速恢复运行环境。
最终验证：全面测试配置有效性
最后一步，我们编写一个完整的检查脚本，确保所有配置项都能正确加载。
# test2.py """ 全面测试 config_v2.py 是否正确加载所有配置项。 """ from core.config_v2 import cfg_v2 def main(): print("=== test2.py: ConfigV2 Full Check ===\n") print(f"Project : {cfg_v2.PROJECT_NAME}") print(f"Version : {cfg_v2.VERSION}") print(f"Device : {cfg_v2.DEVICE}") print(f"Image Size : {cfg_v2.IMG_SIZE}") print(f"In Channels : {cfg_v2.IN_CHANNELS}") print(f"Num Classes : {cfg_v2.NUM_CLASSES}") print(f"Batch Size : {cfg_v2.BATCH_SIZE}") print(f"LR : {cfg_v2.LEARNING_RATE}") print(f"Use SDI : {cfg_v2.USE_SDI}") print(f"CLAHE Grid : {cfg_v2.CLAHE_TILE_GRID_SIZE}") print(f"Weights Dir : {cfg_v2.WEIGHTS_DIR}") print(f"Train Log : {cfg_v2.TRAIN_LOG_DIR}\n") def check_exists(p, name): print(f"[{'OK' if p.exists() else 'FAIL'}] {name:15}: {p}") check_exists(cfg_v2.DATASET_DIR, "DATASET_DIR") check_exists(cfg_v2.TRAIN_IMG_DIR, "TRAIN_IMG_DIR") check_exists(cfg_v2.WEIGHTS_DIR, "WEIGHTS_DIR") check_exists(cfg_v2.TRAIN_LOG_DIR, "TRAIN_LOG_DIR") print("\n=== test2.py: Check complete. Ready to go! ===") if __name__ == "__main__": main()当看到最后一句 “Ready to go!” 时，你就拥有了一个结构清晰、配置统一、环境可控的高质量项目骨架。
接下来，就可以安心投入到真正的核心任务中：数据加载与增强策略的设计。
版权声明：
欢迎关注『youcans动手学 AI』系列
转发请注明原文链接：【动手学UNet】（11）创建Unet_V2 项目Copyright 2025 youcans
Created: 2025-04-05
