setup_simtoken.md

SimToken Setup

---

1. Create Environment

conda create -n simtoken python=3.10 -y
conda activate simtoken

python -m pip install --upgrade pip wheel "setuptools<81"

pip install \
  torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 \
  --index-url https://download.pytorch.org/whl/cu121

pip install \
  transformers==4.30.2 \
  peft==0.2.0 \
  accelerate==0.21.0 \
  sentencepiece \
  protobuf \
  safetensors \
  numpy==1.26.4 \
  pandas \
  matplotlib \
  opencv-python \
  pillow \
  tqdm \
  einops \
  timm \
  requests \
  towhee \
  huggingface_hub

---

2. Download from HuggingFace（新机器初始化）

登录 HuggingFace（token 在 https://huggingface.co/settings/tokens 生成）：

huggingface-cli login

下载完整 repo（代码 + 权重 + 压缩数据包，共约 190G）：

mkdir -p /workspace/SimToken
cd /workspace/SimToken

huggingface-cli download yfan07/SimToken \
  --repo-type model \
  --local-dir . \
  --local-dir-use-symlinks False

下载完成后解压数据包：

cd /workspace/SimToken/data

tar -xf image_embed.tar      # ~5–10 分钟
tar -xzf gt_mask.tar.gz
tar -xzf audio_embed.tar.gz
tar -xf media.tar

---

3. Pre-download Model Weights（首次使用必做）

transformers==4.30.2 与新版 huggingface_hub 存在 API 不兼容（use_auth_token 已移除）。 解决方案：先用 CLI 将模型下载到本地缓存，之后运行实验时加 TRANSFORMERS_OFFLINE=1，跳过所有网络请求。

# Chat-UniVi-7B（~14G）
huggingface-cli download Chat-UniVi/Chat-UniVi-7B-v1.5

# CLIP ViT-L（~1.6G）
huggingface-cli download openai/clip-vit-large-patch14

下载完成后即永久缓存，新 session 无需重复下载。

---

4. Example Evaluation

所有评测命令统一加 TRANSFORMERS_OFFLINE=1：

cd /workspace/SimToken

# Unseen split（全量 1656 样本）
TRANSFORMERS_OFFLINE=1 python -W ignore load_model.py --eval_split test_u

# Seen split
TRANSFORMERS_OFFLINE=1 python -W ignore load_model.py --eval_split test_s

# Null split（S metric，越低越好）
TRANSFORMERS_OFFLINE=1 python -W ignore load_model.py --eval_split test_n

# 限制样本数（快速验证）
TRANSFORMERS_OFFLINE=1 python -W ignore load_model.py --eval_split test_u --max_eval_rows 50

# Stage 0 梯度连通性 + bypass 等价性检查（仅诊断）
TRANSFORMERS_OFFLINE=1 python -W ignore load_model.py --eval_split test_u --max_eval_rows 0

每次评估依次输出：Baseline + q-LTPO Stage 1 两组结果及诊断统计。

---

5. Upload to HuggingFace（实验结束后）

数据目录以压缩包形式存储，可大幅减少文件数量，避免 HuggingFace commit 频率限制。

第一步：将数据目录压缩为归档文件（如尚未压缩）

cd /workspace/SimToken/data

tar -cf image_embed.tar image_embed/     # 不压缩（.pt 已是二进制）
tar -czf gt_mask.tar.gz gt_mask/
tar -czf audio_embed.tar.gz audio_embed/
tar -cf media.tar media/

# 确认压缩包存在后删除原始目录
ls -lh *.tar*
rm -rf image_embed/ gt_mask/ audio_embed/ media/

第二步：清理缓存并上传

find /workspace/SimToken -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find /workspace/SimToken -name "*.pyc" -delete

huggingface-cli login   # token 在 https://huggingface.co/settings/tokens 生成（需 Write 权限）

cd /workspace/SimToken
python upload_hf.py --repo yfan07/SimToken

注意事项：

• 建议在 tmux 里运行，防止 SSH 断开：tmux new -s upload，完成后 Ctrl+B D detach
• 支持断点续传：中断后重新执行同一命令会自动跳过已上传文件
• 遇到 rate limit（HTTP 429）时脚本会自动等待约 1 小时后重试
• 监控进度：tail -f /workspace/SimToken/upload.log