2、开发环境搭建：安装Vivado、安装XRT、配置FINN Docker环境、验证安装是否成功

好，咱们正式开始动手了。这一章要解决一个核心问题——把开发环境搭起来。说实话，我第一次搭FINN环境的时候，踩了不少坑。尤其是Docker和XRT的版本匹配问题，折腾了我整整一个下午。所以这一章，我会把那些容易出问题的地方，一个一个给你指出来。

2.1 安装Vivado——选对版本很重要

FINN对Vivado的版本有明确要求。我个人习惯用Vivado 2020.1或2021.1，这两个版本跟FINN的兼容性最好。你想想看，如果版本不对，后面编译的时候报一堆莫名其妙的错，那才叫头疼。

⚠️ 注意： 不要用Vivado 2022及以上版本。FINN目前对高版本支持不完善，我试过，会报Tcl脚本错误。

安装步骤其实不复杂：

  1. 去Xilinx官网下载Vivado HLx安装包。建议选WebPACK版本，够用了。
  2. 运行安装程序，选择安装路径。我个人习惯放在 C:\Xilinx\Vivado\2020.1 或者 /opt/Xilinx/Vivado/2020.1。
  3. 安装时勾选“Vivado”和“Vitis”组件。SDK可以不用装，我们主要用Vivado做综合和实现。
  4. 安装完成后，设置环境变量。在 .bashrc 或 .bash_profile 里加上：
export XILINX_VIVADO=/opt/Xilinx/Vivado/2020.1
export PATH=$XILINX_VIVADO/bin:$PATH

验证安装是否成功，跑一下：

vivado -version

如果能看到版本号，说明Vivado装好了。嗯，这一步一般不会出问题。

2.2 安装XRT——别小看这个运行时库

XRT是Xilinx Runtime的缩写。说白了，它就是FPGA和主机之间的“翻译官”。没有它，你的模型推理结果根本传不到CPU上。

安装XRT要注意两点：

  • 版本必须匹配：XRT 2.14对应Vivado 2020.1，XRT 2.13对应Vivado 2019.2。混着用会报错。
  • 安装顺序：先装Vivado，再装XRT。我曾经反过来装过，结果XRT找不到Vivado的库文件。

安装命令很简单（以Ubuntu 18.04为例）：

sudo apt update
sudo apt install -y xrt_202020.2.14.0_18.04-amd64-xrt.deb

装完后，检查一下：

xbutil examine

如果能看到你的FPGA设备信息，说明XRT工作正常。看不到？别急，检查一下驱动有没有加载：

lsmod | grep xclmgmt

如果没有输出，手动加载一下：

sudo modprobe xclmgmt
💡 小技巧： 我习惯把 modprobe xclmgmt 加到 /etc/rc.local 里，这样重启后自动加载驱动。

2.3 配置FINN Docker环境——最省心的方式

FINN官方推荐用Docker。为什么？因为依赖太多了——Python 3.8、ONNX、PyTorch、Brevitas……一个个手动装，你会崩溃的。Docker镜像里全给你准备好了。

先装Docker：

sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker

然后拉取FINN镜像。注意，这里有个坑——镜像很大，大概4-5GB。建议用个好点的网络：

docker pull xilinx/finn:latest

拉取完成后，启动容器。我个人习惯用这个命令：

docker run -it --rm \
  -v /path/to/your/project:/workspace \
  -v /opt/xilinx:/opt/xilinx \
  --device /dev/xclmgmt \
  xilinx/finn:latest /bin/bash

解释一下参数：

  • -v /path/to/your/project:/workspace：挂载你的项目目录，这样在容器里修改的文件，宿主机也能看到。
  • -v /opt/xilinx:/opt/xilinx：挂载Vivado和XRT的安装目录，让容器能调用它们。
  • --device /dev/xclmgmt：把FPGA设备透传给容器。
⚠️ 注意： 如果容器里报“找不到vivado”的错误，八成是挂载路径不对。检查一下宿主机上Vivado的实际安装路径。

2.4 验证安装是否成功——跑一个最小测试

环境搭好了，怎么知道能不能用？我建议跑一个FINN自带的测试用例。这个用例很小，几分钟就能跑完。

在容器里执行：

cd /workspace
git clone https://github.com/Xilinx/finn.git
cd finn
python setup.py install

然后跑一个最简单的模型——单层全连接网络：

cd tests
python test_single_fc.py

如果一切正常，你会看到类似这样的输出：

INFO: Running test_single_fc...
INFO: Building FINN accelerator...
INFO: Running inference...
INFO: Accuracy: 100.0%

看到“Accuracy: 100.0%”了吗？恭喜你，环境搭建成功了！

🎯 验证清单：
  • Vivado能正常启动，版本正确
  • XRT能识别FPGA设备
  • Docker容器能正常启动，且能调用Vivado和XRT
  • FINN测试用例能跑通

2.5 常见问题与避坑指南

我遇到过不少问题，挑几个典型的说说：

  • Docker容器里找不到显卡： 如果你用的是NVIDIA GPU加速，记得加 --gpus all 参数。不过FINN主要用FPGA，GPU不是必须的。
  • XRT报错“No Xilinx devices found”： 检查一下FPGA驱动有没有加载，或者试试 sudo xbutil reset 重置一下设备。
  • Vivado综合时内存不足： 小模型还好，大模型（比如ResNet-50）需要至少16GB内存。我建议用32GB的机器。
💡 我的经验： 如果你用的是Windows系统，建议装WSL2 + Docker Desktop。我之前在Windows上直接装Vivado，各种路径问题。换成WSL2后，清爽多了。

好了，环境搭建就到这里。下一章我们开始真正动手——用FINN编译一个简单的二值神经网络。到时候你会看到，从模型到FPGA比特流，整个过程有多流畅。

记住，环境搭好了，后面就顺了。别急，慢慢来。

← 上一章 📖 返回目录 下一章 →