# 目标服务器环境与迁移操作

本包用于继续实现与训练，**不含已实现的八项统一训练命令**。Linux x86_64、Python3.11、8×24GiB RTX4090，可联网，建议当前空闲≥120GiB。使用支持PyTorch cu124的NVIDIA驱动；安装后实际GPU运算检查为准，不携带源机驱动。源机虚拟环境含全局Unsloth遗留冲突，`environment/source_environment_reference.json`及`source_pip_check.txt`仅用于溯源，不是目标安装列表。

## 1. 外层包校验、解压与数据校验

先核对与ZIP一起交付的SHA-256文件，然后将ZIP解压到任意目标目录。进入解压出的 `pallet_baselines_8x4090_handoff_v1` 根目录执行：

```bash
python3.11 tools/verify_handoff.py --root . --unpack-dataset
python3.11 -m venv .venv-project
.venv-project/bin/python -m pip install --upgrade pip
.venv-project/bin/python -m pip install numpy==1.26.4 pillow==11.0.0
.venv-project/bin/python tools/verify_handoff.py --root . --check-data
```

第一条命令只需要Python标准库，核对外层冻结清单及内嵌数据SHA，安全解压数据，逐文件SHA校验，且不查源PCD。第二次data检查还全量核对PNG/AnyLabeling/YOLO/COCO/采集组、读取各split与domain/缺测状态分层的NPZ样本。已存在的数据只校验，拒绝覆盖已有修改。读取失败不记为通过。

数据解压后约24GiB；NPZ只解压一份供八项共享。冻结包内 `source` 保留原工作区快照，继续实现时：

```bash
mkdir -p work
cp -a source work/source
```

`source/configs/active_dataset.json`及`active_formal_dataset.json`含历史本机绝对路径，仅作为历史证据。新运行使用包根 `handoff_config.json`，其所有运行路径相对包根。源码中的旧构建命令或默认 `load_protocol(...verify_sources=True)`会要求原始库，不作为迁移训练接口。

## 2. 项目环境（YOLO、RF-DETR、公共评价）

```bash
.venv-project/bin/python -m pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124
.venv-project/bin/python -m pip install --only-binary=av -r environment/requirements-project.lock
.venv-project/bin/python -m pip check
```

清单锁定现有项目顶层训练/评价依赖以及关键transformers、timm等版本。以干净venv安装，不启用system-site-packages，不从旧Unsloth环境克隆。源 `pyproject.toml`记录headless OpenCV，而Ultralytics元数据要求opencv-python；目标清单统一使用同版本opencv-python，不同时安装两个cv2提供者。**此交接阶段以PYTHONPATH加载源码，不直接pip安装源项目**，避免其历史headless依赖重复安装。目标执行者若更新项目安装元数据，需单独记录代码变更。

PyAV锁为满足supervision的14.2.0，具有CPython3.11/manylinux2014预编译包；使用only-binary避免在glibc较旧主机上回退到FFmpeg源码编译。源机glibc2.27，预检查发现新版18.1.0需要较新的manylinux基线，本包没有沿用这一版本。

```bash
export PYTHONPATH="$PWD/work/source"
.venv-project/bin/python -c 'import torch, torchvision, ultralytics, rfdetr, pytorch_lightning; print(torch.__version__, torchvision.__version__); print(torch.cuda.device_count()); print([(str(torch.cuda.get_device_properties(i).uuid), torch.cuda.get_device_properties(i).total_memory) for i in range(torch.cuda.device_count())]); assert torch.cuda.device_count() == 8; [torch.ones((64,64),device=f"cuda:{i}").matmul(torch.ones((64,64),device=f"cuda:{i}")) for i in range(8)]; torch.cuda.synchronize()'
.venv-project/bin/python -m pip freeze > target_project.freeze.txt
```

完整目标freeze和pip check必须在训练前保存；本包不是离线wheelhouse，也不声称目标安装已在8卡机器验证。RF官方train extras的其它可选依赖如peft/roboflow，若新入口实际调用需要，执行者在该环境补齐、检查并在正式配置冻结前写入目标锁定清单；不因可选依赖变更升级torch/rfdetr或改变正式输入。

## 3. ECDet-S独立环境

```bash
python3.11 -m venv .venv-ecdet
.venv-ecdet/bin/python -m pip install --upgrade pip
.venv-ecdet/bin/python -m pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124
mkdir -p third_party
git clone https://github.com/Intellindust-AI-Lab/EdgeCrafter.git third_party/EdgeCrafter
git -C third_party/EdgeCrafter checkout d7fdcb5100a2b2b97275b8b91d6bb171d4188cab
.venv-ecdet/bin/python -m pip install -r environment/requirements-ecdet.lock
.venv-ecdet/bin/python -m pip check
.venv-ecdet/bin/python -m pip freeze > target_ecdet.freeze.txt
```

包内另存固定提交的原始requirements、许可证和config供核对。EC原清单NumPy2.0.1、SciPy1.16.0与源项目不同，独立环境使用，不能覆盖项目环境。交接的EC锁定清单用于训练，不安装原清单中的ml_dtypes/ONNX/ONNXRuntime部署依赖；本轮不要求EC导出。新loader应独立复用同一几何/框逻辑，不能把NumPy1.26版项目依赖强装进EC环境。

## 4. 官方权重与联网来源

`weights`已含当前官方 `yolov8s.pt`和`yolo26s.pt`，manifest记录SHA和大小。目标如重下载必须比对原SHA；禁止改用历史best.pt。

其它模型通过 `model_sources.json` 指定的官方来源下载，保存本地SHA-256后绑定所有run。RF-DETR Small可由锁定的RFDETRSmall初始化自动获取；EC使用官方README链接的COCO检测 `ecdet_s.pth`，不选O365版本。不要八个任务同时写同一个下载目标。外部来源权重尚未随包下载，状态明确为download_required。

## 5. 实施和调度

将 `TASK_zh.md` 连同 `handoff_config.json`交给目标执行者。先补齐 `pallet.baselines` 等接口并测试，再执行八项独立任务；不存在可直接执行的 `launch_8gpu.sh`。GPU枚举按目标PyTorch UUID映射，不能复制源机UUID。所有训练结束再在单一空闲4090做统一测速。结果目录为 `runs`，须保存目标环境、配置、数据/源码/权重哈希、实际epoch、预测与指标；结果回传不覆盖冻结源数据或原包。
