📚 课程目录第3章环境搭建与配置

3. 环境搭建与配置：开发环境要求、依赖库安装、配置文件解析、常见环境问题排查

说实话，AI ISP 调试工具链的环境搭建，是很多人入门时摔的第一个跟头。我自己带过不少新人，发现 80% 的初期问题都出在环境上——不是库版本冲突，就是系统依赖没装全。这一章，我就把那些坑一个个指给你看。

3.1 开发环境要求

先说说硬件。AI ISP 调试对算力有要求，但不是无底洞。我个人习惯用这套配置：

组件	最低要求	推荐配置	备注
CPU	4 核 2.5 GHz	8 核 3.0 GHz 以上	编译模型时多核优势明显
内存	16 GB	32 GB 或更高	处理 4K 图像序列时吃紧
GPU	NVIDIA GTX 1060	RTX 3080 或 A4000	CUDA 核心数越多越好
硬盘	256 GB SSD	1 TB NVMe SSD	数据集动辄几百 GB
操作系统	Ubuntu 20.04	Ubuntu 22.04	Windows 也能用，但坑更多

注意： 千万别在虚拟机里跑完整的调试流程。我曾经试过，结果 GPU 穿透延迟高得离谱，一个简单的降噪模型推理都要等十几秒。直接上双系统或者物理机，省心得多。

3.2 依赖库安装

依赖库安装是重头戏。我一般把它分成三层：

系统层依赖——编译器、基础工具链
Python 生态——PyTorch/TensorFlow、OpenCV、NumPy
ISP 专用库——RAW 解析、色彩矩阵计算、传感器驱动

先装系统层。Ubuntu 22.04 上，我习惯这样：

sudo apt update
sudo apt install build-essential cmake git libopencv-dev \
    libjpeg-dev libpng-dev libtiff-dev \
    libgflags-dev libgoogle-glog-dev liblmdb-dev

嗯，这里要注意 libopencv-dev 的版本。Ubuntu 源里默认的是 4.5.x，够用。但如果你需要最新的 SIFT 或者 DNN 模块，建议自己从源码编译。

然后是 Python 环境。我个人强烈推荐用 Miniconda 而不是直接 pip。为什么？因为项目之间依赖隔离太重要了。我曾经因为一个旧项目需要 TensorFlow 1.x，新项目需要 2.x，用 pip 全局装直接炸了。

conda create -n ai_isp python=3.10
conda activate ai_isp

# 核心库
conda install pytorch torchvision torchaudio cudatoolkit=11.8 -c pytorch
pip install opencv-python==4.8.1.78
pip install numpy scipy matplotlib scikit-image

# ISP 专用
pip install rawpy colour-science
pip install exifread piexif

小技巧： rawpy 依赖底层 libraw。如果你在编译时遇到错误，先装 sudo apt install libraw-dev 再 pip 安装，能省很多排查时间。

3.3 配置文件解析

AI ISP 工具链的配置文件，说白了就是告诉系统「你要处理什么传感器、用什么参数、输出什么格式」。我见过最复杂的配置有 300 多行，但核心结构其实就这几块：

配置块	作用	常见字段
`[sensor]`	定义传感器特性	width, height, bayer_pattern, black_level, white_level
`[pipeline]`	定义处理流程顺序	stages: [awb, ccm, gamma, lsc, denoise]
`[model]`	指定 AI 模型路径和参数	path, input_size, precision, runtime
`[output]`	输出格式和路径	format, bit_depth, save_dir, preview

举个例子，一个典型的 YAML 配置长这样：

sensor:
  width: 4096
  height: 3072
  bayer_pattern: RGGB
  black_level: 1024
  white_level: 16383

pipeline:
  stages:
    - black_level_correction
    - awb
    - ccm
    - gamma
    - denoise_ai
    - sharpen

model:
  denoise:
    path: "./models/denoise_v3.onnx"
    input_size: [512, 512]
    precision: fp16
    runtime: tensorrt

output:
  format: png
  bit_depth: 16
  save_dir: "./results/"

    关键点： black_level 和 white_level 必须从传感器 datasheet 里拿，不能猜。我见过有人随便填了 0 和 4095，结果整张图偏色偏到离谱，排查了两天才发现是黑电平没对齐。

3.4 常见环境问题排查

环境问题千奇百怪，但归纳起来就几类。我把它们画成了一张排查流程图，方便你对照：

下面是我在实际项目中遇到最多的三个问题，以及对应的解法：

问题一：CUDA 版本不匹配

现象： 运行模型时提示 CUDA error: no kernel image is available for execution on the device。

原因： PyTorch 编译时的 CUDA 版本和当前驱动支持的版本不一致。

解法： 用 nvidia-smi 查看驱动支持的 CUDA 版本，然后安装对应版本的 PyTorch。比如驱动支持 CUDA 11.8，就装 conda install pytorch cudatoolkit=11.8 -c pytorch。

问题二：OpenCV 和 rawpy 冲突

现象： 读取 RAW 文件时崩溃，或者颜色通道顺序错乱。

原因： OpenCV 的 imread 默认把图像转成 BGR，而 rawpy 输出的是 RGB。两者混用时不注意转换就会出问题。

解法： 统一用 rawpy 读取 RAW，用 OpenCV 只做显示和保存。显示前记得 cv2.cvtColor(img, cv2.COLOR_RGB2BGR)。

问题三：模型推理速度极慢

现象： 一张 4K 图像推理耗时超过 10 秒。

原因： 模型没有用 TensorRT 或 ONNX Runtime 加速，跑在 PyTorch 的 eager 模式上。

解法： 导出 ONNX 模型，然后用 TensorRT 做推理优化。我习惯在配置文件的 [model] 块里指定 runtime: tensorrt，工具链会自动做转换。

最后说一句：环境搭建没有捷径，但可以少走弯路。我的建议是——每装一个库，都跑一遍它的官方示例。别等到整个环境搭完了才发现某个核心库装错了。那样排查起来，真的会让人崩溃。