📚 课程目录第2章 DIANN安装与配置

2. DIANN 安装与配置

DIANN 的安装说难不难，说简单也藏着不少坑。我最早在一台老旧服务器上折腾了整整一个下午，后来总结出一套标准流程，基本上不会再出岔子。这一章我把安装的每个环节掰开来讲——系统要求、各平台安装步骤、环境变量怎么配、GPU 加速怎么启动。照着做，半小时内肯定跑起来。

2.1 支持的系统要求

DIANN 在三大主流系统上都能跑，但细节差异不小。我做质控分析时遇到过同一套配置在 Windows 上没问题，到了 Linux 就报动态库缺失的情况。你想想看，提前核对系统要求能省多少 debug 时间。

操作系统	最低版本	推荐配置	我踩过的坑
Windows	Windows 10 20H2	Windows 11 / Server 2022	曾经缺 VC++ 运行时，直接黑框闪退
Linux	Ubuntu 20.04 / CentOS 8	Ubuntu 22.04 / Rocky 9	记得装 libgl1-mesa-glx，不然界面崩溃
macOS	macOS 12 Monterey	macOS 14 Sonoma	M1/M2 要用 Rosetta 2，建议用原生 ARM 版

⚠ 注意：DIANN 对 32 位系统完全不支持。如果还在用 32 位系统，趁早换。我有个同事抱着老工控机不放，最后不得不手动编译，折腾了两天。

2.2 安装步骤

三种系统的安装方式差别挺大。我个人习惯先看 Linux，因为它最灵活，也最容易出问题。

2.2.1 Windows 安装

Windows 安装最直观，但步骤不能跳。我刚开始时直接双击 .exe，结果路径带空格导致后续脚本全报错。

从官方 GitHub Release 页面下载最新版 DIANN-x.x.x-win64.exe。
右键以管理员身份运行，选择安装目录（不要有中文或空格）。我习惯用 C:\DIANN。
安装程序会自动添加环境变量。但我不放心，会手动检查。
安装完成后打开命令提示符，输入 diann --version 验证。

# 验证安装
diann --version
# 预期输出示例：
DIANN version 1.9.1 (build 20241101)

💡 小经验：如果在 PowerShell 里找不到命令，大概率是 PATH 没生效。重启终端或者手动加一下路径：$env:Path += ";C:\DIANN" 临时解决，然后去系统环境变量里补上。

2.2.2 Linux 安装

Linux 下我推荐用 AppImage 或者编译安装。先说说最简单的 AppImage 方式。

# 下载 AppImage
wget https://github.com/diann-software/diann/releases/latest/download/DIANN-x86_64.AppImage
chmod +x DIANN-x86_64.AppImage
./DIANN-x86_64.AppImage --appimage-extract
# 提取后可执行文件在 squashfs-root/usr/bin/diann

如果你喜欢更干净的安装方式，我建议从源码编译。我在编译时遇到过 OpenMP 库版本冲突，后来指定了 -DOpenMP_CXX_FLAGS=-fopenmp 才通过。

# 编译依赖
sudo apt install build-essential cmake libgl1-mesa-dev libx11-dev libxext-dev
git clone https://github.com/diann-software/diann.git
cd diann
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
sudo make install

我曾经在 Ubuntu 22.04 上编译失败，原因是 GCC 默认版本高于 13，DIANN 的某些依赖还没适配。解决办法是使用 CC=gcc-12 CXX=g++-12 cmake .. 指定低版本编译器。

2.2.3 macOS 安装

macOS 用户推荐通过 Homebrew 安装，既方便又干净。我自己用 M1 MacBook Pro，直接 brew 搞定。

# 添加 DIANN 自定义 tap
brew tap diann-software/diann
brew install diann

# 验证
diann --version

如果不用 Homebrew，也能下载预编译的 .dmg 安装包。但要注意 Intel 和 ARM 版本不要混用。我记得有次在 M2 机子上误装了 Intel 版，跑批处理时性能只有原生的一半，后来换成 ARM 版才正常。

2.3 环境变量设置

环境变量这东西，看似小事，实际上很多古怪错误都是它引起的。DIANN 主要用到两个变量：DIANN_HOME 和 PATH。

2.3.1 Linux / macOS

# 编辑 ~/.bashrc 或 ~/.zshrc
export DIANN_HOME=/usr/local/diann
export PATH=$DIANN_HOME/bin:$PATH

# 立即生效
source ~/.bashrc

2.3.2 Windows（两种方式）

图形界面：系统属性 → 高级 → 环境变量 → 新建系统变量 DIANN_HOME=C:\DIANN，编辑 Path 添加 %DIANN_HOME%。
命令行：用 setx 一次性生效（但需重启终端）。

setx DIANN_HOME "C:\DIANN"
setx Path "%Path%;%DIANN_HOME%"

⚠ 避坑指南：我曾经在 Windows 上设置了环境变量但 DIANN 依然找不到动态库，原因是 DIANN_HOME\lib 没有加到 PATH。正确做法是同时把 %DIANN_HOME%\lib 加入 PATH，或者将 diann.exe 所在目录加入即可。

2.4 GPU 加速配置

DIANN 的 GPU 加速主要依赖 NVIDIA CUDA。如果你不做大规模质控分析，CPU 模式也能跑。但一旦数据量上来，GPU 加速能快 5-10 倍。我做过一个包含 200 个样本的 DIA 定量项目，用 GPU 只跑了 3 小时，CPU 模式预估要 20 小时。

2.4.1 前提条件

NVIDIA 显卡（计算能力 ≥ 5.0）
CUDA Toolkit 11.x 或 12.x
cuDNN 8.x 或对应版本

在 Linux 下检查 CUDA 是否可用的命令：

nvidia-smi
nvcc --version

输出应该显示驱动版本和 CUDA 版本。我遇到过驱动版本够新但 nvcc 找不到的情况，多半是 PATH 没有加 CUDA 的 bin 目录。

2.4.2 开启 GPU 模式

DIANN 默认自动检测 GPU。如果检测不到，可以手动强制指定。

# 命令行开启 GPU 加速
diann --use-gpu --gpu-device 0

也可以在配置文件里设置。我个人习惯写一个 diann_config.json：

{
  "gpu": {
    "enabled": true,
    "device_id": 0,
    "memory_fraction": 0.8
  }
}

💡 建议：如果你有多块 GPU，用 --gpu-device 1 指定第二块，避免显存竞争。我原来在共享服务器上忘了指定，结果把所有人的训练任务都挤掉了……嗯，从那以后我再也不偷懒了。

2.4.3 验证 GPU 是否生效

diann --info
# 输出中会包含：
# GPU available: Yes
# CUDA version: 12.1
# Device: NVIDIA A100 80GB

如果显示 GPU available: No，检查三个地方：驱动版本、CUDA 路径、动态库链接。我曾经有一次是因为 LD_LIBRARY_PATH 里漏了 /usr/local/cuda/lib64，加上就识别了。

这张图把安装流程串起来了。从系统要求开始，到三个平台的安装分支，再到环境变量和 GPU 配置，最后以验证命令收尾。你照着这个流程走，基本不会漏步骤。

我的装机清单：

Windows + CUDA 12.1 → 用管理员权限安装 .exe，手动添加 DIANN_HOME 和 %DIANN_HOME%\lib 到 PATH。
Linux + CUDA 11.8 → 编译安装或 AppImage，注意 LD_LIBRARY_PATH 要包含 /usr/local/cuda/lib64。
macOS M1 → brew 安装，确认是 ARM 版，GPU 加速依赖 Metal，默认已集成。

好了，安装配置这部分就到这。把环境跑起来之后，下一件事就是熟悉它的参数体系和质控逻辑了。不过那又是另一码事，咱们先确保手上有把能用的枪。记住，一次配置到位，后面省心无数。我自己当时就是前两步没在意，后面调了半天的 bug。还是那句老话——安装别嫌烦，debug 更头疼。