github-setup-zh

name	github-setup-zh
description	配置任意开源 GitHub 研究仓库（任何领域）时使用——clone、配 conda env、装依赖、下权重、跑 demo。触发信号：README 给了 `quick_install.sh` / `requirements.txt` 你正要照着跑；pip install 卡住/失败/意外把 numpy 拉到不同版本；`import X` 能跑但 demo 崩；demo "应该 30 秒"却跑了几小时。

GitHub 仓库配置 — 通用流程

概述

开源研究仓库的安装脚本几乎都很脆弱：作者机器上当时跑通的 pip pin，merge 之后就开始漂。照 README 字面跑通常会失败。这个 skill 抓住通用流程 —— 不管哪个仓库，做什么、按什么顺序，都是相同的；最后给一份 pixel3dmm + SMIRK 的实战案例，把每条通用原则映射到具体的坑。

核心原则：最小安装 → 验证 import → 在小样例上 smoke test → 再扩。不要无脑信 pip pin 组合，numpy / cv2 / cuda 传染性依赖会在你脚下挪动。

何时使用

• clone 任意 GitHub 研究仓库并按其 install 步骤配置
• 在已有 conda env 上加一个姊妹项目（只装差异化包）
• 跑需要 FLAME / SMPL-X / mediapipe / gdown 重权重的 demo
• pip install 卡 / 失败 / 拉到意外版本
• import X 能跑但 X.load(ckpt) 报模糊错误
• demo "应该 30 秒"实际跑几小时 — 多半是 env 或资源问题

不适用：生产部署（用容器）、纯 CPU 工具库。

通用流程

digraph workflow_zh {
    "已有可用姊妹 env？" [shape=diamond];
    "复用 + 装差异包" [shape=box];
    "新建 conda env" [shape=box];
    "完整读 README" [shape=box];
    "8 阶段安装" [shape=box];
    "小样例 smoke 测试" [shape=doublecircle];
    "失败？" [shape=diamond];
    "按类型诊断" [shape=box];

    "已有可用姊妹 env？" -> "复用 + 装差异包" [label="是"];
    "已有可用姊妹 env？" -> "新建 conda env" [label="否"];
    "复用 + 装差异包" -> "小样例 smoke 测试";
    "新建 conda env" -> "完整读 README";
    "完整读 README" -> "8 阶段安装";
    "8 阶段安装" -> "小样例 smoke 测试";
    "小样例 smoke 测试" -> "失败？";
    "失败？" -> "按类型诊断" [label="是"];
    "按类型诊断" -> "8 阶段安装";
    "失败？" -> "固化为 install_env.sh" [label="否"];
}

8 阶段

1. 决策：复用姊妹 env vs 新建
2. 完整读 README：跑任何命令前，先把所有权重 / 子仓库 / 版本 pin / 外部服务（FLAME 官网账号、gdown ID 等）列出来
3. 加固 env：PATH 顺序、pip index、build-isolation 默认值
4. 装 torch + CUDA toolkit + 编译工具：在做其他事之前先验证 torch.cuda.is_available()
5. 装 requirements.txt：先 pin numpy + setuptools，再用 --no-build-isolation 装老旧 / 源码编译类包
6. 源码编译附加包（pytorch3d / nvdiffrast / 自定义 CUDA kernel）：永远 --no-build-isolation
7. 子仓库 + 重权重：gdown / wget；下载后立即检查文件大小；放到期望的路径
8. 重 pin 容易被传染性依赖拉走的包（numpy、opencv），需要时加 monkey-patch（torch.load weights_only）

然后：在小样例上 smoke test。通过则把工作命令固化成一份幂等的 install_env.sh。

失败类型（按症状诊断，不按仓库）

出错时，先识别是哪个类型。每个类型都有固定的修法。

类型	症状	修法
A. Env 隔离	conda activate ENV 后 which python 还是 base	手动追加 $ENV/bin:$PATH
B. 构建依赖	pip 编译时 ModuleNotFoundError	--no-build-isolation + 确保依赖已预装
C. 版本兼容矩阵	运行时 numpy / cv2 / torch 报 AttributeError	找到冲突对，pin 较低那个，重装
D. 网络 / 镜像	pip / wget 超时、gdown 403、conda 校验和错配	切 index、重试、用镜像、清缓存
E. 资源放置	FLAME / 预训练 ckpt FileNotFoundError	检查目录是否是占位结构；cp 不要 ln -sfn
F. 系统层兼容	libx264 not found、EGL 初始化失败	用 conda-forge 替代、接受 CPU 后退、换库
G. API 破坏性变更	ckpt 加载报模糊错、签名不匹配	在脚本入口处 monkey-patch 默认值
H. 资源争用	demo 比 README 慢 100 倍	怪 env 之前先 nvidia-smi / ps aux --sort=-%cpu

每个具体问题都映射到某个类型；识别出类型后，修法就短。

复用模式（姊妹 env）

大多数项目都跑在已有的 torch-cuda-python 栈之上。只装差异比新装风险更低、更快。

source ~/miniconda3/etc/profile.d/conda.sh
conda activate sister_env
export PATH="$CONDA_PREFIX/bin:$PATH"
export PIP_INDEX_URL="https://pypi.org/simple"

# 1. 列出当前关键版本
pip list | grep -iE "torch|numpy|opencv|cuda|matplotlib"

# 2. 只装新仓库 requirements.txt 里的差异包
pip install --no-build-isolation --no-cache-dir <only_diff_packages>

# 3. 立即重 pin 可能被差异安装拉走的包
pip install --no-build-isolation --no-cache-dir "numpy==<known_good>" "opencv-python<<known_good>"

# 4. 验证姊妹项目和新项目的 smoke 都还能跑

Smoke 测试模式

任何 install 完成后、做任何其他事之前：

# 选最小样例（5s 视频 / 单张图），不是全数据集
time python demo.py --input samples/short_clip.mp4 --out /tmp/test.npz

失败：停下来，按类型诊断。8 个类型基本覆盖你会遇到的情况。

通过但比 README 慢 100 倍：先排资源争用（nvidia-smi、ps aux）再怪 env。后台训练 / 推理任务会无声拖累你的 demo。

常见误区

信任 README pin 组合：numpy==1.22.4 + opencv==4.9 + mediapipe==0.10.10 一起装会传染性把 numpy 拉到 2.0。每次完整 install 后都要重 pin numpy（类型 C）。

跳过 smoke 测试："直接跑全数据集" → 6 小时后发现第 1 步配错了。

信任部分 git clone 状态：上次失败留下半个 checkout。新 install 看到目录存在就跳过 clone，但配置文件缺失。永远 ls subrepo/，不是只 [ -d subrepo ]。

5 个 retry 脚本而不是修原脚本：每次 retry 都应该 patch 原脚本（加幂等 guard），而不是建 install_v2.sh / install_v3.sh / ...。

没排查 GPU 占用：慢 100 倍时，怪 env 之前先 nvidia-smi。后台训练任务是无声小偷。

警示信号 — 立刻停下排查

• pip 输出 Successfully installed numpy-2.0.x 且你已经 pin 过 1.23.x → 立刻重 pin（类型 C）
• mediapipe 第一帧调用 > 5s → 已退到 CPU（类型 F）
• Demo "完成" 但输出文件空 / 形状不对 → smoke test 抓到逻辑 bug 而不是 env 问题
• README 说 "30 秒 / 卡" 你看到 30 分钟 → 类型 H（资源）或 F（CPU 后退）
• conda activate X 后 which python 是 base 路径 → 类型 A
• 项目里出现 3 个 install_*_resume.sh → 你的脚本不幂等，要合并

固化

Smoke 通过后，把工作命令落成一份：

install_env.sh

要求：

• set -euxo pipefail，失败时大声停下
• [ -d X ] || git clone ... guard，重跑安全
• 8 阶段全部内联，每步注释属于哪个类型
• 把所有 _v2.sh / _resume.sh 这类 retry 残骸丢到 legacy/

案例：Pixel3DMM + SMIRK（本项目踩过的具体坑）

这是一个仓库的具体实例，对应到上面的类型。供参考"这些类型实际长什么样"。

#	实际现象	类型	修法
1	conda activate p3dmm 后 which python 还是 base 3.13，不是 env 的 3.9	A	activate 后 export PATH="$CONDA_PREFIX/bin:$PATH"
2	pip 卡在清华镜像 read timed out	D	export PIP_INDEX_URL="https://pypi.org/simple"
3	chumpy 的 setup.py 直接 import pip（旧式代码）→ build env 里 ModuleNotFoundError	B	pip install --no-build-isolation chumpy
4	pytorch3d 源码编译找不到 torch（build isolation 隔离了 env）	B	pip install --no-build-isolation git+...
5	conda CUDA tarball ChecksumMismatchError (libcusolver)	D	mv $CONDA_PKGS/*.tar.bz2 /tmp/ 后重试
6	ln -sfn /path/FLAME2020 ./MICA/data/FLAME2020 嵌套了内层链接（占位目录已存在）	E	cp /path/FLAME2020/*.pkl ./MICA/data/FLAME2020/
7	PIPNet 的 .pyx 用 np.int_t（numpy ≥1.20 已删），Cython 3 编译失败	C	sed -i 's/np\.int_t/np.intp_t/g' *.pyx; pip install "Cython<3"
8	运行时 AttributeError: module 'numpy' has no attribute 'int'（mediapipe / opencv 4.13 把 numpy 拉到 2.0）	C	每次可能拉 numpy 2 的 install 后都 pip install "numpy==1.23.5" "opencv-python<4.10"
9	torch.load(ckpt) 报 UnpicklingError ... Unsupported global: omegaconf.dictconfig.DictConfig（PyTorch 2.6+ 默认 weights_only=True）	G	脚本顶部 monkey-patch：torch.load = lambda *a, **kw: _orig(*a, **{**kw, "weights_only": False})
10	系统 ffmpeg 不识别 -crf / 没有 libx264（RHEL 8 ffmpeg 3.1）	F	mpeg4 -q:v 1 高质量编码或装 conda-forge ffmpeg
11	mediapipe Linux GPU 初始化失败：EGL not initialized	F	接受 CPU 后退（~50-200 ms/帧）或换 face_alignment torch GPU（~63 ms/帧）
12	gdown 大文件 403	D	gdown <ID> --fuzzy 或换 HuggingFace 镜像
13	SMIRK demo 跑 150 帧用了 53 分钟	H	后台训练把 GPU 占满 100%，等空闲或换卡

实测收益

Pixel3DMM 完整安装：本来要 4+ 小时调试 → 用此 skill 30 分钟搞定。 SMIRK 复用 pixel3dmm env：2 个差异包，5 分钟全部装完。 5s smoke 测试在处理 89 段数据集前抓到 9/13 个坑。 最终 SMIRK 推理：2.6 秒 / 150 帧（vs README 的 mediapipe 路径会跑 30+ 秒）。

参见 pixel3dmm_test/shell/install_env.sh — 把 5 个 retry 脚本（在 legacy/）整合成的单一可复现脚本。