LingBot-Vision 加载时报版本冲突、从报错栈第一行倒推依赖组合

LingBot-Vision 加载时报版本冲突，多数情况下不是“升到最新就能好”，而是安装某个包时把另一个包的 ABI 或符号替换掉了。想判断到底是谁引起的，可以固定一条顺序：导出当前实际版本，读报错栈定位触发模块，在隔离环境里逐个回退候选包，锁定可用组合，最后用同一张图跑两次确认数值没有漂移。

版本冲突的定位顺序建议固定为：导出实际版本 → 读报错栈找触发模块 → 隔离环境单包回退 → 冻结依赖 → 同输入两次运行比对。它适用于本地或容器里能稳定复现的加载失败；如果失败原因是权重文件缺失、路径写错或许可证问题，这条路径不适用。回退动作应先在独立虚拟环境里做，直接在主环境升级候选包，通常会把其他依赖一并带偏。

先把当前环境实际装的版本导出来

凭印象判断版本是最容易走偏的一步，先把解释器和包的真实版本落到文件里。虚拟环境或 conda 环境都适用下面这套写法：

python -c "import sys; print(sys.version)"
python -m pip freeze > env_full.txt
python -m pip list `--format`=freeze > env_list.txt
# conda 环境可另外执行
conda env export `--no-builds` > env_conda.yml

导出的文件建议放在项目根目录或固定的记录目录里，便于后面比对。需要重点关注的包通常是：torch、torchvision、numpy、transformers、tokenizers、huggingface_hub、safetensors、protobuf、pydantic、accelerate、Pillow，以及 LingBot-Vision 自身和它的直接依赖。想确认“谁在依赖谁”，可以用 python -m pip show 包名，看 Requires 字段，而不是只看顶层写死的版本号。注意 pip freeze 记录的是解析后的实际版本，和 requirements.txt 里写的范围可能并不一致。

读报错栈第一行确定触发模块

不同框架下“第一行”含义略有差别，稳妥的阅读顺序是：先看最后一行异常类型和消息，再从最外层第一行往下扫，找到第一个出现在 site-packages 里的第三方包路径，这个路径的顶层包名通常就是触发模块。

undefined symbol: 后面跟一段 C++ 符号名，多半是编译扩展的 ABI 不匹配，常见于 torch 与 torchvision、numpy 这类需要编译的包。
cannot import name 'X' from 'Y'，说明 Y 的版本与调用方预期不一致，X 是判断版本高低的关键符号名。
module 'numpy' has no attribute 'X'，往往是 numpy 主版本切换带来的接口变化。
AttributeError: module 'torch' has no attribute 'X'，一般指向 torch 版本偏旧。
requests、urllib3、charset_normalizer 这类出现在栈里，通常只是外围调用，可以暂时排除。

把完整报错保存成文件，避免只截一段：

python -c "import lingbot_vision" 2>&1 | tee load_error.log

需要记录的行有三处：最外层入口那一行、第一个第三方包栈帧、最后一行异常消息。它们分别对应“从哪里进来”“在哪个包炸掉”“具体原因是哪一类”。

在独立虚拟环境里逐个回退候选包

回退动作要在独立环境里做，不要污染正在用的主环境。先按导出文件还原一份接近原始的环境：

python -m venv .venv-probe
. .venv-probe/bin/activate   # Windows: .venv-probe\Scripts\activate
python -m pip install -U pip
python -m pip install -r env_full.txt

然后一次只改一个包，写法就是指定版本：

python -m pip install "torchvision==0.15.2"
# 每次改动后重跑加载验证
python -c "import lingbot_vision; print('LOAD_OK')"

回退顺序建议先动与报错消息直接相关的包，再动它的直接依赖；不要一次改三个包，否则下一次复现时无法判断是哪一个起了作用。每次只记录“改了哪个包、改到什么版本、加载是否通过”三件事。如果回退后报错位置变了，说明已经接近真正冲突点，可以把新的报错栈再按上一步读一遍。加载入口以你项目里的实际模块为准，上面的 import 写法只是占位示例。

锁定可复现的依赖组合并记录

在隔离环境里加载通过之后，立刻把当前状态冻结下来，否则几天后很难记住是哪组版本可用：

python -m pip freeze > locks/env_locked_<日期>.txt

冻结文件建议放在仓库的 locks 目录并纳入版本管理，文件名带上日期或用途说明。重建验证时另开一个干净环境，只装冻结文件：

python -m venv .venv-rebuild
. .venv-rebuild/bin/activate
python -m pip install -r locks/env_locked_<日期>.txt
python -c "import lingbot_vision; print('LOAD_OK')"

重建后能打印出加载成功，才算真正锁定；如果重建时又报同样的冲突，说明冻结文件里混进了环境残留，需要回到隔离环境重新导出。

验证：同一张图两次运行结果一致

依赖调整有可能改变数值行为，所以要用同一张图跑两次做对比。两次运行使用相同的随机种子和输入路径：

python run_infer.py `--image` sample.jpg `--seed` 0 > run1.log
python run_infer.py `--image` sample.jpg `--seed` 0 > run2.log
diff run1.log run2.log

如果输出是日志文本，diff 无输出即可认为一致；如果输出是张量，可先存为 npz 再做数值比对：

import numpy as np
a = np.load("run1.npz")["out"]
b = np.load("run2.npz")["out"]
print(np.allclose(a, b, rtol=1e-5, atol=1e-8))

同环境、同输入、同种子通常应完全一致；如果模型里包含非确定性算子，可能出现末位差异，可以先用 allclose 的默认容差做粗筛，再按你的精度要求收紧阈值。差异超过可接受范围时，回到回退步骤继续排查，而不是直接接受这组依赖。结果记录建议用结构化格式，方便以后对照：

{
  "image": "sample.jpg",
  "lock_file": "locks/env_locked_<日期>.txt",
  "same_seed": true,
  "allclose": true,
  "note": "两次输出仅末位浮点差异"
}

把冻结文件名和这次对比结论一起记下来，下次遇到相同的加载报错，可以直接用这组版本重建环境，不必再从零试错。