复现流程

GDKVM：含门控 Delta 规则的时空键值记忆的超声心动图视频分割

1. 环境构建

0. 清理环境

若当前 Shell 已激活虚拟环境（左侧显示 (base) 或 (env)），需先退出。

对于 Conda 环境：

conda deactivate

对于普通 venv：

deactivate

备注： uv 的环境管理具有较高的隔离性。在大多数场景下，即便未退出 Conda 环境，直接构建 uv 虚拟环境也不会引发依赖冲突。

1. 工具准备：安装 uv

本项目采用 uv 进行依赖管理。该工具基于 Rust 开发，具备高效的依赖解析能力。

服务器无法直接链接外网时，安装：

pip install uv

或更新至最新版：

pip install --upgrade uv

验证安装：

uv -V

基准版本：今天的版本 0.9.10。

2. 获取项目代码

克隆代码仓库并指定本地目录名。

git clone https://github.com/wangrui2025/GDKVM.git gdkvm_20251215

进入项目目录：

cd gdkvm_20251215

项目结构概览：

.
├── .python-version    # 指定项目使用的 Python 版本
├── pyproject.toml     # 项目的主配置文件
├── uv.lock            # 锁定文件 (确保环境一致性)
└── ...                # 其他项目源代码文件

3. 环境初始化与同步

uv 将读取配置文件，创建虚拟环境，安装所有依赖。

对于更新的环境，可以使用 env_02 环境配置，具体代码参考 env/env_02/pyproject.toml

uv sync

故障排除：内网/受限网络下的 Python 安装

场景： 若执行 uv sync 时报错（如 SSL 错误、连接超时），通常系网络策略限制导致 uv 无法自动下载 Python 解释器。

解决方案： 通过镜像源手动安装 Python。

查看可用版本：

uv python list

通过镜像源安装（以 3.12.12 为例）：

uv python install 3.12.12 --mirror https://github-proxy.lixxing.top/https://github.com/astral-sh/python-build-standalone/releases/download

安装成功后，再次运行 uv sync。

版本约束与兼容性说明

Pydantic 版本冲突 <2.12

现象： Pydantic 2.12+ (2025-10) 的严格 Schema 校验与 wandb 字段声明冲突，多进程下可能导致崩溃。

解决： 配置文件已强制锁定 pydantic<2.12。
Wandb 系统兼容性 (glibc)

现象： wandb>=0.22.2 停止提供针对 Ubuntu 18.04 (glibc 2.27) 的预编译包，导致安装失败。

解决： 需确保系统安装了 Go 编译器以支持源码编译，或升级操作系统。
SSL/TLS 证书错误 (内网/代理环境)
现象： 运行 uv add/sync 时报错（Certificate Expired），因内网防火墙/代理的自签名证书不被 uv 默认的 Rust TLS 信任。

解决方案： 切换为系统原生 TLS 验证。
方案 A (临时单次)
```
uv add wandb --native-tls
```
方案 B (永久推荐)
```
export UV_NATIVE_TLS=1
```
* 建议将此命令添加到 ~/.bashrc 或 ~/.zshrc

4. 激活环境

source .venv/bin/activate

注：推荐显式激活环境，以便进入交互式调试（如 Python REPL）及使用 pip 检查包状态。

验证环境（应输出项目 .venv 目录下的路径）：

which python

输出结果示例：
/data/Anon/Repo/gdkvm_20251215/.venv/bin/python

2. 数据准备

我们使用 CAMUS 和 EchoNet-Dynamic 数据集。

数据集下载

已处理数据集: CAMUS HuggingFace EchoNet-Dynamic todo

原始数据集: CAMUS 官方网站 HuggingFace 镜像 EchoNet-Dynamic 官方网站镜像

3. 模型训练与评估

3.1 模型训练

1. 环境配置

根据 Shell 环境（zsh 或 bash）选择相应的 train.sh 脚本，并配置以下环境变量以适配硬件环境：

CUDA_VISIBLE_DEVICES: 0,1 # 指定使用的 GPU 设备编号
MASTER_PORT: 29500        # 分布式训练的主端口号，避免冲突

2. 参数设定

编辑配置文件 config/config_gdkvm_01.yaml，针对实验需求调整关键超参数：

data_path: /data/Anon/dataset/camus_png256x256_10f_20250709/   # 数据集的实际存放路径
batch_size: 8                                                  # 单次训练的样本数量
learning_rate: 1.0e-4                                          # 学习率
num_iterations: 3000                                           # 总迭代次数
eval_stage:
  num_vis: 0                                                   # 可视化图片的数量
  wandb_mode: "offline"                                        # 设置为 "offline"

3. 执行训练

赋予执行权限：

chmod +x ./train.sh

启动训练：

./train.sh

3.2 训练结果输出

训练产物（模型权重、可视化结果等）将保存至 train.sh 中 hydra.run.dir 指定的目录。

gdkvm_20251215/outputs

3.3 WandB 监控

实验采用 Weights & Biases (WandB) 进行离线日志记录。

日志路径: gdkvm_20251215/wandb
具体运行目录: 包含时间戳与哈希值的子文件夹（例如：offline-run-20251215_123456-abcdef1gh）。

上传离线日志

训练结束后，可以使用以下命令将离线数据同步到 WandB 云端：

wandb sync gdkvm_20251215/wandb/offline-run-20251215_123456-abcdef1gh