环境安装与依赖准备

这一步解决什么问题

LingBot-Map 是一个面向流式 3D 重建的推理项目，核心依赖包括：

• Conda：隔离 Python、CUDA 运行时相关依赖，避免和系统环境互相污染。
• PyTorch：模型推理、GPU 张量计算、bf16/fp16 加速的基础。
• 项目本体：克隆 Robbyant/lingbot-map，安装 Python 依赖，使 demo.py、gct_profile.py 等脚本可运行。
• FlashInfer：用于 paged KV cache attention 的高性能后端，长序列流式重建时通常比 SDPA 更快。
• 可视化依赖：用于点云、相机轨迹、离线渲染或交互式 demo 展示。

适用场景：

• 在一台新 GPU 服务器上部署 LingBot-Map。
• 在本地工作站运行 demo.py 查看重建结果。
• 对比 flashinfer 和 sdpa 后端的速度与显存占用。
• 配置离线渲染或交互式可视化环境。

---

一套推荐的目录和环境

建议把代码和模型权重分开放，方便升级代码或替换 checkpoint。

bash📋 复制
mkdir -p ~/projects
cd ~/projects

git clone https://github.com/Robbyant/lingbot-map.git
cd lingbot-map

推荐 Conda 环境名：

bash📋 复制
lingbot-map

推荐 Python 版本：

bash📋 复制
Python 3.10

创建环境：

bash📋 复制
conda create -n lingbot-map python=3.10 -y
conda activate lingbot-map

升级基础构建工具：

bash📋 复制
python -m pip install --upgrade pip setuptools wheel
pip install ninja packaging

---

PyTorch 和 CUDA 要先对齐

先确认机器上的 NVIDIA 驱动是否正常：

bash📋 复制
nvidia-smi

你会看到类似信息：

text📋 复制
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 555.xx.xx              Driver Version: 555.xx.xx      CUDA Version: 12.x    |
+---------------------------------------------------------------------------------------+

这里的 CUDA Version 表示驱动支持的最高 CUDA 版本，不一定等于你要安装的 PyTorch CUDA wheel 版本。

CUDA 12.1 环境

如果你的驱动支持 CUDA 12.1 或更高版本，可以安装 PyTorch CUDA 12.1 版本：

bash📋 复制
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

CUDA 12.4 环境

如果你希望使用 CUDA 12.4 wheel：

bash📋 复制
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

只做 CPU 环境检查

LingBot-Map 的实际推理建议使用 NVIDIA GPU。CPU 环境只适合安装检查、阅读代码或跑少量工具脚本：

bash📋 复制
pip install torch torchvision torchaudio

安装后检查：

bash📋 复制
python - <<'PY'
import torch

print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
print("torch cuda:", torch.version.cuda)

if torch.cuda.is_available():
    print("gpu:", torch.cuda.get_device_name(0))
PY

---

安装 LingBot-Map 项目依赖

进入项目目录：

bash📋 复制
cd ~/projects/lingbot-map

安装 README 中维护的依赖：

bash📋 复制
pip install -r requirements.txt

如果项目包含 setup.py 或 pyproject.toml，建议用 editable 模式安装项目本体：

bash📋 复制
pip install -e .

这样做的好处是：你修改本地源码后，不需要重复安装包，Python 会直接引用当前工作区代码。

检查脚本入口是否可用：

bash📋 复制
python demo.py -h
python gct_profile.py -h

如果命令能打印参数说明，说明项目依赖大体安装完成。

---

FlashInfer：长序列推理推荐后端

LingBot-Map 的 README 中明确提到：

• SDPA 后端可用。
• 长序列场景推荐 FlashInfer。
• gct_profile.py 可通过 --backend flashinfer 验证性能。
• demo.py 可结合 --compile 进一步加速。

FlashInfer 的 wheel 和 PyTorch 版本、CUDA 版本 强相关。安装前先查看当前环境：

bash📋 复制
python - <<'PY'
import torch

torch_ver = ".".join(torch.__version__.split("+")[0].split(".")[:2])
cuda_ver = torch.version.cuda

print("torch minor:", torch_ver)
print("cuda:", cuda_ver)
PY

例如：

text📋 复制
torch minor: 2.5
cuda: 12.1

对应的 FlashInfer 安装命令通常形如：

bash📋 复制
pip install flashinfer-python -i https://flashinfer.ai/whl/cu121/torch2.5/

如果你的环境是 PyTorch 2.4 + CUDA 12.1，则示例为：

bash📋 复制
pip install flashinfer-python -i https://flashinfer.ai/whl/cu121/torch2.4/

如果你的环境是 PyTorch 2.5 + CUDA 12.4，则示例为：

bash📋 复制
pip install flashinfer-python -i https://flashinfer.ai/whl/cu124/torch2.5/

安装后检查：

bash📋 复制
python - <<'PY'
import flashinfer
print("flashinfer imported:", flashinfer.__name__)
PY

---

可视化依赖：桌面和服务器分开装

LingBot-Map 的 demo 和离线渲染通常会涉及图像、点云、视频或 Web 可视化。常见依赖可以这样补齐：

bash📋 复制
pip install opencv-python imageio imageio-ffmpeg matplotlib open3d trimesh plotly

如果需要交互式 Web demo，可安装：

bash📋 复制
pip install gradio

如果项目使用 browser-based 3D viewer，也可以补充：

bash📋 复制
pip install viser

无显示器服务器

如果你在无桌面的 Linux 服务器上运行，opencv-python 和 open3d 有时会因为 OpenGL、X11、GLIBCXX 等问题报错。

更稳的做法是使用 headless OpenCV：

bash📋 复制
pip uninstall -y opencv-python
pip install opencv-python-headless

如果仍然需要 Open3D 离屏渲染，可能还需要系统库，例如 Ubuntu：

bash📋 复制
sudo apt-get update
sudo apt-get install -y libgl1 libglib2.0-0 libegl1

---

安装命令汇总：CUDA 12.1 + PyTorch + FlashInfer

下面是一套常用 GPU 服务器安装流程，可以直接复制执行。

bash📋 复制
# 1. 创建环境
conda create -n lingbot-map python=3.10 -y
conda activate lingbot-map

# 2. 基础工具
python -m pip install --upgrade pip setuptools wheel
pip install ninja packaging

# 3. PyTorch，CUDA 12.1 wheel
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 4. 项目代码
mkdir -p ~/projects
cd ~/projects
git clone https://github.com/Robbyant/lingbot-map.git
cd lingbot-map

# 5. 项目依赖
pip install -r requirements.txt
pip install -e .

# 6. FlashInfer，注意 torch2.5/cu121 要和你的实际环境一致
pip install flashinfer-python -i https://flashinfer.ai/whl/cu121/torch2.5/

# 7. 可视化依赖
pip install opencv-python imageio imageio-ffmpeg matplotlib open3d trimesh plotly gradio viser

---

关键命令和接口说明

命令 / 接口	作用	典型使用场景
conda create -n lingbot-map python=3.10	创建隔离 Python 环境	新机器部署、多人共用服务器
conda activate lingbot-map	进入项目环境	每次运行 demo 前
pip install torch ... --index-url ...	安装匹配 CUDA 的 PyTorch	GPU 推理、性能测试
pip install -r requirements.txt	安装项目声明的依赖	首次安装项目
pip install -e .	以 editable 模式安装项目本体	开发、调试、改源码
pip install flashinfer-python ...	安装 FlashInfer attention 后端	长视频、长序列、KV cache 加速
python demo.py -h	查看交互式 demo 参数	确认脚本可执行
python gct_profile.py --backend flashinfer --dtype bf16	测试 GCT 推理性能	验证 FlashInfer 是否工作
python demo.py --compile ...	启用编译优化	在支持的 PyTorch/GPU 上提高吞吐

---

可运行检查脚本：确认 GPU、FlashInfer、可视化包

在项目根目录创建文件：

bash📋 复制
cat > check_env.py <<'PY'
import importlib
import sys

def check_import(name, required=True):
    try:
        mod = importlib.import_module(name)
        version = getattr(mod, "__version__", "unknown")
        print(f"[OK] {name}: {version}")
        return True
    except Exception as e:
        level = "FAIL" if required else "WARN"
        print(f"[{level}] {name}: {e}")
        if required:
            return False
        return True

ok = True

print("Python:", sys.version.replace("\n", " "))

ok &= check_import("torch", required=True)

import torch

print("torch cuda available:", torch.cuda.is_available())
print("torch cuda version:", torch.version.cuda)

if torch.cuda.is_available():
    print("gpu:", torch.cuda.get_device_name(0))

    dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
    x = torch.randn(1024, 1024, device="cuda", dtype=dtype)
    y = x @ x.T
    torch.cuda.synchronize()
    print("cuda matmul:", y.shape, y.dtype, float(y[0, 0]))
else:
    print("[WARN] CUDA 不可用；LingBot-Map 实际推理建议使用 NVIDIA GPU")

# FlashInfer 是推荐加速项，不作为基础安装的硬失败
check_import("flashinfer", required=False)

# 可视化相关
check_import("cv2", required=False)
check_import("open3d", required=False)
check_import("imageio", required=False)
check_import("matplotlib", required=False)
check_import("trimesh", required=False)
check_import("gradio", required=False)
check_import("viser", required=False)

if not ok:
    raise SystemExit(1)

print("environment check finished")
PY

运行：

bash📋 复制
python check_env.py

正常情况下会看到类似输出：

text📋 复制
Python: 3.10.x ...
[OK] torch: 2.x.x+cu121
torch cuda available: True
torch cuda version: 12.1
gpu: NVIDIA ...
cuda matmul: torch.Size([1024, 1024]) torch.bfloat16 ...
[OK] flashinfer: ...
[OK] cv2: ...
[OK] open3d: ...
environment check finished

---

运行一次后端性能检查

如果模型和依赖已经准备好，可以用项目自带 profiling 脚本检查后端。

FlashInfer：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16

SDPA：

bash📋 复制
python gct_profile.py --backend sdpa --dtype bf16

如果 GPU 不支持 bf16，可以改成：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype fp16

启用编译优化：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16 --compile

---

demo.py 的安装验证方式

先只看参数，不加载模型：

bash📋 复制
python demo.py -h

如果已经下载模型权重和示例数据，可以按项目 README 的 Quick Start 命令运行。常见形式如下，具体参数以当前仓库 python demo.py -h 为准：

bash📋 复制
python demo.py \
  --backend flashinfer \
  --dtype bf16 \
  --compile

如果 FlashInfer 安装失败或需要排查问题，可以先退回 SDPA：

bash📋 复制
python demo.py \
  --backend sdpa \
  --dtype bf16

---

常见安装问题和处理

torch.cuda.is_available() 是 False

先看驱动：

bash📋 复制
nvidia-smi

如果 nvidia-smi 不存在或报错，说明 NVIDIA 驱动没有正确安装，Conda 和 pip 解决不了这个问题。

如果 nvidia-smi 正常，但 PyTorch 不识别 CUDA，通常是装成了 CPU 版 PyTorch。重新安装 CUDA wheel：

bash📋 复制
pip uninstall -y torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

---

FlashInfer 安装找不到 wheel

FlashInfer wheel 要匹配：

• CUDA tag，例如 cu121、cu124
• PyTorch minor version，例如 torch2.4、torch2.5
• Python 版本
• Linux 架构

先确认当前环境：

bash📋 复制
python - <<'PY'
import torch
print(torch.__version__)
print(torch.version.cuda)
PY

然后选择对应地址：

bash📋 复制
pip install flashinfer-python -i https://flashinfer.ai/whl/cu121/torch2.5/

如果没有与你环境匹配的 wheel，建议优先调整 PyTorch 到 FlashInfer 已发布 wheel 支持的组合，而不是混装不同 CUDA/PyTorch 版本。

---

ImportError: libGL.so.1

通常是 OpenCV 或 Open3D 依赖系统 OpenGL 库。Ubuntu 上安装：

bash📋 复制
sudo apt-get update
sudo apt-get install -y libgl1 libglib2.0-0

服务器不需要本地窗口时，可以换成 headless OpenCV：

bash📋 复制
pip uninstall -y opencv-python
pip install opencv-python-headless

---

bf16 运行报错或结果异常

不是所有 GPU 都适合跑 bf16。检查：

bash📋 复制
python - <<'PY'
import torch
print(torch.cuda.is_available())
if torch.cuda.is_available():
    print(torch.cuda.get_device_name(0))
    print("bf16 supported:", torch.cuda.is_bf16_supported())
PY

如果不支持，使用 fp16：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype fp16

---

--compile 第一次运行很慢

--compile 会触发 PyTorch 编译优化。第一次启动会花时间编译 kernel，之后同一环境、相近输入形状下会更快。

适合：

• 长序列视频
• 多次重复推理
• 固定分辨率、固定参数的服务

不适合：

• 只跑一小段测试
• 频繁切换输入形状
• 正在调试模型内部代码

---

版本边界和部署建议

Conda 只负责环境，不负责显卡驱动

Conda 环境里安装的 cudatoolkit 或 PyTorch CUDA wheel 不能替代宿主机 NVIDIA driver。驱动问题先用 nvidia-smi 排查。

PyTorch、CUDA、FlashInfer 不要随意混装

最容易出问题的是下面这种组合：

• PyTorch 是 cu121
• FlashInfer 装的是 cu124
• 或 FlashInfer wheel 对应 torch2.4，但当前环境是 torch2.5

建议安装后立即跑：

bash📋 复制
python check_env.py

FlashInfer 是性能推荐项，不是唯一后端

如果只是先把 demo 跑通，可以用 SDPA：

bash📋 复制
python demo.py --backend sdpa

长序列、长视频、上万帧流式重建时，再切到：

bash📋 复制
python demo.py --backend flashinfer

可视化环境在服务器上要保守

远程服务器上不建议一开始就启用所有 GUI/窗口功能。先完成：

bash📋 复制
python check_env.py
python demo.py -h

再逐步打开交互式 demo、Open3D 窗口或离线渲染。

安装顺序不要反

推荐顺序是：

1. Conda 环境
2. PyTorch
3. 项目依赖
4. FlashInfer
5. 可视化依赖
6. 模型权重和示例数据
7. 运行 demo / profiling

这样出错时更容易定位是哪一层依赖的问题。