机器人装上"眼睛"和"大脑"：WSL2 本地部署 Qwen2.5-VL-3B 踩坑实录（RTX 5060）

这是机器人开发系列的第 2 篇。上一篇搭好了 ROS2 Jazzy + Gazebo Harmonic 的仿真环境，这一篇给机器人装上"视觉大脑"——在 WSL2 里本地部署 Qwen2.5-VL-3B 多模态大模型。过程中踩了 10 个坑，每个坑都有完整解决方案。

系列文章：第1篇：ROS2 + Gazebo 环境搭建 ← 你在这里 | 第2篇：VLM 本地部署 | 第3篇：接入 ROS2（待更新）

---

前言：这个项目要做什么

先交代一下背景。我正在做一个具身智能（Embodied AI）机器人项目，目标很明确：

让机器人在 Gazebo 仿真环境里自己动起来，用摄像头"看"到周围环境，然后调用本地部署的大模型理解画面内容，最后通过 ROS2 把理解结果转化成控制指令，指挥机器人行动。

整个项目的技术栈分成三层：

层级	组件	作用
仿真层	ROS2 Jazzy + Gazebo Harmonic	机器人运动控制、传感器仿真、物理环境
智能层	Qwen2.5-VL-3B-Instruct	视觉理解 + 语言推理，给机器人"大脑"
连接层	ROS2 节点 + 话题通信	把 VLM 封装成 ROS2 节点，打通上下游

上一篇已经完成了仿真层的搭建——ROS2 Jazzy 和 Gazebo Harmonic 在 WSL2 里跑起来了，机器人模型能加载，传感器数据能读取。

这一篇解决智能层——把 Qwen2.5-VL-3B 塞进本地 RTX 5060 显卡，让机器人有自己的"视觉大脑"。

为什么是本地部署，不用云端 API？四个原因：

1. 延迟——API 调用来回几百毫秒，机器人实时控制扛不住
2. 隐私——摄像头画面直接传云端，敏感场景不敢用
3. 成本——调用量上去了，账单跟着涨
4. 离线——机器人跑在外面，没网就废了

选 Qwen2.5-VL-3B 的原因也很简单：3B 参数刚好能在 8G 显存的 RTX 5060 上跑，多模态（能看图能聊天），中文好，开源可商用。

环境：WSL2 + Ubuntu 24.04 + RTX 5060 8G，跟上一篇完全一致。

封面：从 ROS2 机器人到 Qwen2.5-VL 视觉大脑

---

一、整体部署路线

先看一下从上一篇结束到本篇目标的完整路线：

图：四步部署路线——CUDA Toolkit → Python 虚拟环境 → PyTorch cu132 → Qwen 模型

1.1 我的硬件环境

跟上一篇完全一致：

项目	配置
显卡	NVIDIA GeForce RTX 5060 8GB
系统	Windows 11 + WSL2 (Ubuntu 24.04)
内存	32GB
Python	3.12
目标模型	Qwen/Qwen2.5-VL-3B-Instruct
前置环境	ROS2 Jazzy + Gazebo Harmonic（已完成）

1.2 最终效果

部署完成后，你可以在本地终端里跟大模型聊天，支持纯文本和图片输入，推理完全本地运行，不联网。下一篇会把它接入 ROS2，让 Gazebo 里的机器人真正"看懂"世界。

---

二、踩坑实录：10个问题全记录

这篇文章的核心价值就在这儿——每个坑我都踩过，每个解决方案都亲测有效。

坑1：CUDA runfile 安装"没反应"

现象： 执行 sudo sh cuda_12.6.0_560.28.03_linux.run 后，终端什么都不显示，像卡住了一样。

原因： 不是卡住了，是 runfile 启动了 ncurses 图形界面，但终端没有正确渲染出来。

解决方案：

• 等一会儿，界面会出来的
• 第一屏是 EULA 协议，输入 accept 回车
• 安装类型选 Custom (Advanced)，不要选默认的
• 只勾选 CUDA Toolkit，其他都取消（尤其是 NVIDIA Graphics Driver，WSL2 不需要装 Linux 版驱动）

# 下载 CUDA Toolkit 12.6
wget https://developer.download.nvidia.com/compute/cuda/12.6.0/local_installers/cuda_12.6.0_560.28.03_linux.run

# 运行安装（耐心等界面出来）
sudo sh cuda_12.6.0_560.28.03_linux.run

关键提醒：WSL2 的显卡驱动是 Windows 端提供的，Linux 里不要装 Driver，只装 Toolkit 就行。这一点跟上一篇装 Gazebo 时的情况类似——WSL2 里很多驱动都是 Windows 托管的。

坑2：pip3 命令找不到

现象：

Command 'pip3' not found

解决方案：

sudo apt update
sudo apt install python3-pip -y

坑3：PEP 668 外部环境保护

现象：

error: externally-managed-environment
× This environment is externally managed

原因： Ubuntu 24.04 默认开启了 PEP 668，禁止直接往系统 Python 里装包，防止搞坏系统。

解决方案： 用虚拟环境（这才是正确做法）

# 安装 venv 模块
sudo apt install python3.12-venv -y

# 创建虚拟环境
python3 -m venv ~/vlm_env

# 激活虚拟环境
source ~/vlm_env/bin/activate

激活后终端前面会出现 (vlm_env) 标识，之后所有 pip 安装都在这个环境里。这跟上一篇装 ROS2 时用的系统包管理完全不同——Python 开发强烈建议用虚拟环境隔离。

坑4：RTX 5060 不支持 CUDA 12.6？sm_120 报错

现象： 安装 PyTorch cu126 版本后，运行时报错：

RuntimeError: CUDA error: no kernel image is available for execution on the device
# 或者提示 sm_120 not supported

原因： RTX 5060 是 Blackwell 架构，计算能力是 sm_120。PyTorch 的 cu126 版本编译的时候还不支持 sm_120，所以跑不起来。

图：RTX 5060 的 sm_120 架构需要 CUDA 13.2 版本的 PyTorch

解决方案： 升级到 CUDA 13.2 版本的 PyTorch

# 先卸载所有旧版本
pip uninstall -y torch torchvision torchaudio
pip uninstall -y nvidia-cublas-cu12 nvidia-cuda-cupti-cu12 nvidia-cuda-nvrtc-cu12 nvidia-cuda-runtime-cu12 nvidia-cudnn-cu12 nvidia-cufft-cu12 nvidia-curand-cu12 nvidia-cusolver-cu12 nvidia-cusparse-cu12 nvidia-nccl-cu12 nvidia-nvjitlink-cu12 nvidia-nvtx-cu12

# 安装 cu132 版本
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu132

划重点：RTX 50 系列（Blackwell 架构）必须用 CUDA 13.x 对应的 PyTorch 版本，cu126 及以下都不支持。这个坑浪费了我最多时间，因为网上 99% 的教程都告诉你装 cu126。

坑5：pip 下载超时，速度太慢

现象： 下载 modelscope 等包的时候速度只有几 KB/s，然后超时失败。

解决方案： 换清华源

pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple

坑6：~ 路径识别不了

现象： 用 ~/qwen2.5-vl-3b-instruct 作为模型路径加载，报错：

HFValidationError: Repo id must use alphanumeric chars, '-', '_' or '.'. The name cannot start or end with '-' or '.'

原因： transformers 库把 ~ 当成了 repo id 的一部分，没有展开成家目录路径。

解决方案： 用绝对路径

# 错误写法
model = AutoModel.from_pretrained("~/qwen2.5-vl-3b-instruct")

# 正确写法
model = AutoModel.from_pretrained("/home/你的用户名/qwen2.5-vl-3b-instruct")

坑7：测试图片下载下来是 XML

现象： 用 wget 下载一张测试图片，结果 file 命令查看显示是 XML 文档。

原因： 下载链接是个网页而不是直接的图片文件，wget 抓到了重定向页面。

解决方案： 直接用本地图片。WSL2 访问 Windows 桌面的图片很方便：

/mnt/c/Users/你的用户名/Desktop/test.jpg

坑8：模型体积比想象的大

现象： 以为 3B 模型也就 3 个 G，结果下载下来有 7G 多。

原因： 3B 是参数数量，不是文件大小。FP16 精度下，1B 参数约等于 2GB 显存，3B 就是约 6GB。加上视觉编码器、分词器等其他文件，7-8GB 很正常。

实际占用： 模型文件约 7.5GB，加载后进显存约 6-7GB，RTX 5060 8G 刚好能放下。

坑9：Some parameters are on the meta device

现象： 加载模型时提示：

Some parameters are on the meta device because they were offloaded to the cpu.

原因： 显存不够了，部分参数被放到 CPU 的 meta device 上了。8G 显存跑 3B FP16 模型确实刚好卡在线上。

是否影响使用： 不影响，模型还是能正常推理，只是速度会稍微慢一点。如果想让全部参数都在 GPU 上，可以试试 4-bit 量化，速度还能更快。

坑10：Windows 路径在 WSL2 里用不了

现象： 想加载 Windows 桌面上的图片，直接传 C:\Users\xxx\Desktop\test.jpg 找不到文件。

解决方案： WSL2 里访问 Windows 文件要用 /mnt/c/ 开头：

# Windows 路径
C:\Users\程江浩\Desktop\test.jpg

# WSL2 路径
/mnt/c/Users/程江浩/Desktop/test.jpg

小贴士：我在对话脚本里做了自动转换，直接输 Windows 路径也能用。

---

三、完整安装步骤（保姆级）

踩了这么多坑，给大家整理一份正确的、一步到位的安装流程。跟着走，上面的坑一个都不会踩。

3.1 前置确认：ROS2 环境已就绪

如果你跟着上一篇走，ROS2 Jazzy 和 Gazebo Harmonic 应该已经在 WSL2 里跑起来了。先确认 GPU 直通正常：

nvidia-smi

能看到显卡信息就说明基础环境没问题。

3.2 安装 CUDA Toolkit

# 下载 CUDA 12.6 runfile
cd ~/Downloads
wget https://developer.download.nvidia.com/compute/cuda/12.6.0/local_installers/cuda_12.6.0_560.28.03_linux.run

# 运行安装
sudo sh cuda_12.6.0_560.28.03_linux.run

安装界面里：

1. 输入 accept 同意协议
2. 选 Custom (Advanced)
3. 只勾选 CUDA Toolkit，取消其他所有选项
4. 确认安装

安装完成后配置环境变量：

echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

验证：

nvcc -V

3.3 创建 Python 虚拟环境

# 安装 pip 和 venv
sudo apt update
sudo apt install python3-pip python3.12-venv -y

# 创建并激活虚拟环境
python3 -m venv ~/vlm_env
source ~/vlm_env/bin/activate

注意：ROS2 用的是系统 Python（/usr/bin/python3），VLM 开发用的是虚拟环境 Python（~/vlm_env/bin/python3），两者互不干扰。这是我专门设计的隔离方案。

3.4 安装 PyTorch（cu132 版本！）

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu132

验证：

python3 -c "
import torch
print(f'CUDA: {torch.cuda.is_available()}')
print(f'GPU: {torch.cuda.get_device_name(0)}')
print(f'VRAM: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB')
"

输出类似这样就对了：

CUDA: True
GPU: NVIDIA GeForce RTX 5060
VRAM: 8.0 GB

3.5 安装依赖包

# 用清华源加速
pip install modelscope transformers accelerate pillow qwen-vl-utils -i https://pypi.tuna.tsinghua.edu.cn/simple

3.6 下载 Qwen2.5-VL-3B 模型

# 新建 download_model.py
from modelscope import snapshot_download

model_dir = snapshot_download(
    'Qwen/Qwen2.5-VL-3B-Instruct',
    cache_dir='/home/你的用户名/qwen2.5-vl-3b-instruct'
)
print(f"模型下载到：{model_dir}")

python3 download_model.py

下载大小约 7.5GB，耐心等待。

3.7 测试模型

from transformers import Qwen2VLForConditionalGeneration, AutoProcessor
from qwen_vl_utils import process_vision_info
import torch

# 模型路径——用绝对路径！
model_path = "/home/你的用户名/qwen2.5-vl-3b-instruct/Qwen/Qwen2.5-VL-3B-Instruct"

print("Loading model...")
model = Qwen2VLForConditionalGeneration.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
    device_map="auto"
)
processor = AutoProcessor.from_pretrained(model_path)
print("Model loaded!")

# 测试图片理解
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "/mnt/c/Users/你的用户名/Desktop/test.jpg"},
            {"type": "text", "text": "请描述这张图片的内容。"}
        ]
    }
]

text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
image_inputs, video_inputs = process_vision_info(messages)
inputs = processor(
    text=[text],
    images=image_inputs,
    videos=video_inputs,
    padding=True,
    return_tensors="pt"
).to("cuda")

print("Running inference...")
generated_ids = model.generate(**inputs, max_new_tokens=512)
generated_ids_trimmed = [
    out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_text = processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)

print(f"\n输出：{output_text[0]}")

能正常输出图片描述，就说明智能层部署成功了！

---

四、交互式对话脚本

测试成功后，我写了一个交互式对话脚本，可以像跟 ChatGPT 聊天一样跟本地千问对话，还支持发图片。

使用方法

source ~/vlm_env/bin/activate
python3 chat_vlm.py

支持的命令

命令	功能
直接打字	跟模型聊天
/img 图片路径	加载图片并提问（支持 Windows 路径自动转换）
/clear	清空对话历史
/history	查看对话历史
/help	查看帮助
/quit / /exit	退出

效果示例

==================================================
  Qwen2.5-VL-3B 本地对话
  输入 /help 查看帮助，/quit 退出
==================================================

你: 你会什么？能帮我干什么？
千问: 我是一个视觉语言模型，可以帮你做很多事情：
1. 回答各种问题，包括知识问答、常识解释等
2. 理解和描述图片内容，识别图中的物体、场景、文字等
3. 协助写作，写文章、写代码、写邮件都可以
4. 翻译、总结、推理等文本处理任务
5. 如果你有具体的需求，直接告诉我就好！

你: /img C:\Users\程江浩\Desktop\test.jpg
加载图片：C:\Users\程江浩\Desktop\test.jpg
千问: 这张图片展示了一个宁静的湖边场景...

---

五、性能实测

5.1 显存占用

状态	显存占用
模型加载完成（空闲）	~6.8 GB
推理中（生成回答）	~7.2 GB
带图片推理	~7.5 GB

RTX 5060 8G 显存刚好够用，留了几百 MB 的余量。

5.2 推理速度

• 纯文本回答：约 15-20 字/秒
• 图片理解：首字延迟约 5-8 秒，之后约 10-15 字/秒
• 回答长度：默认 512 tokens，约 300-400 字

作为对比，手机端跑 1.8B 模型大概 5-10 字/秒，RTX 5060 跑 3B 这个速度属于正常水平。

5.3 能力边界

能做的：

• 日常知识问答
• 图片描述、OCR 识别
• 写简单代码、解释代码
• 翻译、总结、润色
• 给机器人做视觉理解（这正是我们要的）

别指望它做的：

• 复杂数学推理（3B 模型能力有限）
• 长文本处理（上下文窗口 32K，但显存不够用满）
• 跟 GPT-4 比效果（参数差了几十倍）

但对于机器人项目来说，"看懂画面 + 简单推理"已经够用了。

---

六、与 ROS2/Gazebo 的关系

这里有必要解释一下，为什么这套环境要跟上一篇的 ROS2 分开：

环境	位置	Python 版本	用途
ROS2 系统环境	/usr/bin/python3	3.12	ROS2 节点、Gazebo 插件
VLM 虚拟环境	~/vlm_env	3.12	大模型推理、AI 开发

两个环境互不干扰。下一篇我会写如何把 VLM 封装成 ROS2 节点——本质上是让 ROS2 节点调用虚拟环境里的 Python 脚本来做推理，通过话题把 Gazebo 摄像头的画面传进去，再把 VLM 的理解结果传出来。

---

七、后续优化方向

部署成功只是第二步，接下来还有几个方向：

7.1 量化加速

用 4-bit 量化（bitsandbytes 或 AWQ），显存占用能降到 3-4GB，速度还能更快。

7.2 vLLM 推理引擎

换 vLLM 作为推理后端，吞吐量能提升 2-3 倍，适合高并发场景。

7.3 接入 ROS2（第3篇）

这是整个项目的最终目标——把 VLM 封装成 ROS2 节点，让 Gazebo 里的机器人通过话题传输摄像头画面，VLM 实时返回环境理解和行动决策。

7.4 更大的模型

如果升级到 12G 显存（比如 RTX 4070 Ti Super），可以上 7B 甚至 14B 模型，效果会好很多。

---

八、总结

这是机器人开发系列的第 2 篇。上一篇搭好了 ROS2 + Gazebo 的仿真平台，这一篇给机器人装上了"视觉大脑"——Qwen2.5-VL-3B 本地部署成功。

关键结论：

1. RTX 50 系列必须用 CUDA 13.x 对应的 PyTorch，cu126 不支持 sm_120
2. 3B 模型 FP16 精度约占 6-7GB 显存，8G 显卡刚好能跑
3. ROS2 系统环境和 VLM 虚拟环境分开管理，互不干扰
4. 本地部署的核心价值是低延迟 + 隐私 + 离线，效果不如云端但够用

项目进度：

• ✅ 第1篇：ROS2 Jazzy + Gazebo Harmonic 环境搭建
• ✅ 第2篇：Qwen2.5-VL-3B 本地部署（本篇）
• ⏳ 第3篇：VLM 接入 ROS2，机器人真正"看懂"世界（预告）

有问题评论区留言，我尽量回复。

---

下一篇预告：把 Qwen2.5-VL 接入 ROS2，打通仿真机器人从"看"到"动"的完整链路。