LingBot-VLA 2.0 本地部署环境的依赖清单与启动验证

本地有 GPU 但装不好 LingBot-VLA 2.0 的依赖，通常会卡在两类位置：一是分不清当前要跑训练还是纯推理，把不需要的包一起装上，产生版本冲突；二是权重文件下载完成后，入口脚本找不到模型路径，启动日志报读取失败。这篇整理的是从空环境到默认示例跑通的依赖处理流程，先确认运行模式，再锁定核心依赖，最后用启动日志和资源监控确认服务状态。

LingBot-VLA 2.0 本地部署的首要判断是先确定当前要跑训练还是纯推理：纯推理环境只需模型加载、权重读取和基础算子库，不必安装完整训练组件；随后用 pip check 锁定依赖冲突，用环境变量固定模型路径与缓存目录；最终以默认示例启动，日志出现模型权重加载完成和服务端口监听字样即算初步通过。具体版本需结合当前仓库说明与环境确认，不要仅凭单条报错重装全部依赖。

先区分运行模式：训练推理/纯推理

LingBot-VLA 2.0 这类 VLA 项目通常会通过入口脚本区分训练和纯推理，部署前先确认当前要跑的模式。纯推理只需要权重加载、tokenizer、图像编码器和基础推理库；训练模式还会引入优化器、分布式通信、数据预处理组件。先看仓库给出的入口：如果存在独立推理脚本，就以它为准；如果只有一个入口脚本，多半有 `--mode` 或 `--task` 这类切换参数，先加 `--help` 看参数列表，再决定依赖范围。

用这两条命令确认当前环境实际装了哪些依赖组：

# 查看仓库提供的入口脚本
ls -la | grep -E "infer|train|launch|run"

# 查看环境里已有的关键依赖
conda env list
pip list | grep -E "torch|vllm|deepspeed|transformers"

纯推理环境下，deepspeed、tensorboard 这类训练组件可以暂时不装；如果训练脚本在纯推理环境下被误启动，报错通常会停在找不到分布式初始化函数或 optimizer 相关参数上。看到这类报错时，先回到入口确认，而不是继续补依赖。

安装核心依赖并核对版本冲突

依赖冲突多数发生在 torch 相关包之间。VLA 项目会同时依赖 transformers、tokenizer、图像编码库和推理加速库，这些包对 torch 版本都有约束。建议的处理顺序是：先按仓库 requirements 建一个新环境，安装完成后立即核对冲突，再补装确实缺失的包。

conda create -n lingbot python=3.10
conda activate lingbot
pip install -r requirements.txt
pip check

pip check 会列出包之间的依赖冲突。遇到冲突时，先锁定核心框架的主版本区间，让其他包跟随这个区间安装，避免后装的包把 torch 换到另一个大版本。给出版本约束时，用固定主版本的写法即可：

# 示例：主版本约束写法
pip install "torch==2.*" "transformers>=4.*"

如果仓库自带 requirements-lock 或 setup.py 中的 install_requires，优先以锁定版本为准。具体版本数字以当前仓库 requirements 或启动脚本里的声明为准。

配置模型权重路径与缓存目录

权重文件下载完成后，最常见的问题是入口脚本按默认相对路径找模型。需要提前把模型路径和缓存目录导出，让入口脚本第一次读取就拿到绝对路径。

export LINGBOT_MODEL_PATH=/data/models/lingbot-vla-2.0
export HF_HOME=/data/cache/huggingface
export TORCH_HOME=/data/cache/torch

部分版本支持在配置文件中写路径，放在 model_path 字段。环境变量和配置文件同时存在时，优先级以启动日志实际打出的读取路径为准。配置完成后，先确认权重目录里包含模型主文件、tokenizer 相关文件和配置文件，再执行启动。启动日志前几行通常会显示实际读取的绝对路径，出现 /data/models/... 而不是 ./models 时，说明环境变量已生效。

运行自带示例并观察启动日志

依赖和环境变量就位后，启动仓库自带示例。以下是命令骨架，实际脚本名以仓库文件名为准：

python run_infer.py `--model`_path "$LINGBOT_MODEL_PATH" `--input`_demo demo/config/example.json `--output`_dir ./outputs

确认启动成功的日志特征有两类：一是模型权重加载完成，日志关键字可能包含 model loaded、load weights、runtime ready 这类字样，具体文案随版本不同；二是服务进入等待输入的状态，常见表现为端口监听或示例推理任务开始执行。两种情况只要出现一个，都属于初步启动通过。

常见失败对照：报 CUDA out of memory 时，先降低 batch size 或限制显存上限；报 tokenizer 找不到时，回到上一节检查权重目录完整性；报 ModuleNotFoundError 时，只修第一个缺失模块，单独补装后再跑一次 pip check，不要一次性重装全部依赖。

录制一次推理过程的系统资源监控

启动通过后，用资源记录确认稳定性。建议跑完一个完整示例，同时记录显存和耗时。以下命令先让 nvidia-smi 在后台写入日志，time 统计推理耗时，结束后杀掉后台记录进程：

nvidia-smi `--query-gpu`=name,memory.used,utilization.gpu `--format`=csv -l 1 > gpu.log &
time python run_infer.py `--model`_path "$LINGBOT_MODEL_PATH" `--input`_demo demo/config/example.json `--output`_dir ./outputs
kill %1

判断基线参考三点：显存峰值没有超过可用显存；整个推理过程 GPU 利用率没有频繁掉零；time 输出没有出现明显中断或超时。首次运行时如果显存随时间持续上涨，优先检查是否存在重复缓存或推理循环未释放的情况，这属于稳定性问题，不是性能问题。把 gpu.log 里的显存峰值和项目说明中的参考显存对比，再调整输入规模。