5分钟跑通SenseNova-Vision:从环境搭建到首次推理的快速开始教程
5分钟跑通SenseNova-Vision:从环境搭建到首次推理的快速开始教程
SenseNova-Vision 是一个将计算机视觉统一为多模态生成的开源项目(Vision as Unified Multimodal Generation)。一句话介绍任务、丢一张图,它就能输出检测框、分割掩码、深度图、关键点、OCR 文本甚至 3D 点云——无需任何任务专用头。本文带你完成 SenseNova-Vision 环境搭建 与 首次推理,5 分钟即可跑通。
它能做什么?一个模型覆盖 10+ 视觉任务 🎯
传统做法是每个视觉任务训练一个模型(检测一个、分割一个、深度又一个)。SenseNova-Vision 用自然语言指令 + 可选视觉提示统一描述任务,模型以原生文本、图像或文本-图像混合形式作答。
| 任务类型 | 具体任务 | 输出形式 |
|---|---|---|
| 结构化视觉理解 | 目标检测、Referring Detection、OCR、关键点、GUI Grounding、相机位姿 | 文本(坐标/文本) |
| 稠密几何预测 | 单目深度、表面法线 | 图像(深度图/法线图) |
| 分割 | 语义、全景、指代、推理、交互式分割 | 图像(掩码) |
| 多视图几何 | 多视图 3D 重建 | 3D 点图 / glb 场景 |
下面是一个真实的目标检测输出示例(COCO 常见类别):
环境搭建:3 步一键完成 🚀
前置条件清单 ✅
| 依赖 | 要求 | 说明 |
|---|---|---|
| 操作系统 | Linux | 参考运行环境为 Linux |
| GPU | NVIDIA 显卡 | 建议 80GB 显存跑完整 demo;单卡推理可用更小规模显卡 |
| CUDA | 12.x 工具包 | 参考环境为 CUDA 12.4,setup.sh 会自动校验版本 |
| Conda | 已安装 | 脚本会自动探测 miniconda3/anaconda3 |
第 1 步:克隆仓库
git clone https://gitcode.com/gh_mirrors/se/SenseNova-Vision
cd SenseNova-Vision
第 2 步:一键创建环境
bash setup.sh sensenova-vision
conda activate sensenova-vision
setup.sh 会自动完成以下工作,无需手动操作:
- 依据 environment.yml 创建 conda 环境(Python 3.10.16 + OpenJDK 8);
- 按 requirements.txt 安装依赖,并用 constraints.txt 锁定版本(PyTorch 2.5.1、transformers 4.49 等);
- 编译安装
flash-attn==2.6.3; - 安装分割/检测/3D 评测扩展(panopticapi、fastevaluate 等);
- 自动执行
pip check与关键库导入验证。
💡 若 CUDA 版本不是 12.x,脚本会直接报错提示,请先安装 CUDA 12.x 再重试。
第 3 步:验证环境
python -c "import decord, fastevaluate, flash_attn, panopticapi, torch; print(torch.__version__, torch.version.cuda, flash_attn.__version__)"
能正常打印版本号,即环境就绪。
首次推理:一条命令出结果 🔥
推理统一入口是 scripts/run_sensenova_vision.sh,所有运行命令都通过它路由。
方式一:跑官方示例(最简单)
bash scripts/run_sensenova_vision.sh example
该命令会加载 SenseNovaVisionModel 并执行 9 组内置示例(通用理解、二值分割、深度、法线、检测、多视图 3D 重建、全景分割等),结果写入 examples/output/example_visualize/。
方式二:自定义单次推理
三个位置参数依次为 任务、查询、图片路径,例如对一张图做二值分割:
bash scripts/run_sensenova_vision.sh inference \
binary_seg \
"person" \
examples/images/2.jpg
输出保存在 examples/output/demo/<task>/ 下,包含原始输出文件和 vis/ 可视化面板。
常用任务速查表
| 任务参数 | 说明 | 查询示例 |
|---|---|---|
raw_query |
原始提示,配合 --mode 选择模式 |
"What are the main objects in this scene?" |
depth / normal |
深度 / 法线估计 | 无需查询,传 "" |
binary_seg |
二值分割 | "person" |
pan_seg |
全景分割 | 类别列表,缺省用 COCO 类别 |
bbox_detection |
边界框检测 | "bird, boat, person" |
keypoint |
关键点检测 | "person" 或 "cat" |
ocr |
文字识别 | 无需查询 |
recon3d / camera_pose |
多视图 3D 重建 / 相机位姿 | 逗号分隔的多视图图片路径 |
例如做目标检测:
bash scripts/run_sensenova_vision.sh inference \
bbox_detection \
"bird, boat, person, cell phone, backpack, handbag" \
examples/images/5.jpg
方式三:交互式推理与 Web Demo
想反复调试不同提示?用交互式模式(模型保持加载,输入 /task、/image 等命令即可切换):
bash scripts/run_sensenova_vision.sh interactive
想要可视化界面?启动 Gradio Web Demo(建议 1 x 80GB 显卡):
MODEL_PATH=/path/to/SenseNova-Vision-7B-MoT \
bash scripts/run_sensenova_vision.sh demo
脚本会先打印本地访问 URL 再启动服务。
常见问题排查 💊
| 现象 | 原因与解决 |
|---|---|
setup.sh 报 CUDA toolkit 12.x is required |
安装了非 12.x 的 CUDA,设置 CUDA_HOME 指向 CUDA 12.x 工具包目录后重试 |
flash-attn 编译/导入失败 |
确认 Python、PyTorch、CUDA 三者匹配;参考环境为 Python 3.10 + PyTorch 2.5.1+cu124 |
| 显存不足 | Web Demo 建议 80GB 显存;单图 inference 可在显存更小的卡上尝试 |
| 找不到模型 | 所有模型相关命令都需要 MODEL_PATH 环境变量或 --model_path 参数指向本地模型目录 |
下一步 📚
跑通首次推理后,可以继续探索:
- 📄 完整推理文档:docs/INFERENCE.md
- 📊 基准评测与指标计算:docs/EVAL.md
- 🏋️ 训练数据准备:docs/train_data_prepare.md
- 🧠 训练指南(多机多卡):docs/TRAIN.md
- 🖼️ 示例图片与标注:examples/
- 🔢 模型核心实现:modeling/bagel/、inference/inferencer.py
# 运行完整基准评测(需先按 docs/data_prepare.md 准备数据)
bash scripts/run_sensenova_vision.sh benchmark all \
--num_gpus 8 \
--tasks_per_gpu 2
恭喜!你已经从零跑通了 SenseNova-Vision 快速开始 全流程——环境一键搭建、一条命令完成首次推理,剩下的就是用它探索更多视觉任务了 🎉


