2. FINN开发环境搭建：安装Docker、拉取FINN镜像、配置Vivado与XRT环境

好，咱们直接进入正题。环境搭建这事儿，说难不难，说简单吧，坑也不少。我见过太多人卡在第一步——装了半天，最后发现是Docker版本不对，或者Vivado路径没配好。今天我就把这几步拆开揉碎了讲，你跟着走一遍，基本不会出问题。

2.1 为什么非得用Docker？

你可能想问：为什么FINN非要跑在Docker里？我自己装一套Python环境不行吗？

嗯，理论上可以。但FINN的依赖链太长了——PyTorch、ONNX、Vivado HLS、XRT库……版本稍微一错，编译就崩。我早期做项目时，为了给团队统一环境，折腾了整整两天。后来换成Docker，一句话搞定。

说白了，Docker就是给你一个“干净的、别人验证过的”运行环境。你不需要关心底层库怎么装，镜像里全配好了。

核心思路： FINN的Docker镜像 = 预装好的Python + Vivado HLS工具链 + XRT运行时。你只需要拉下来，挂载你的工程目录，就能直接跑。

2.2 安装Docker

这一步其实没什么技术含量，但有几个细节要注意。

2.2.1 检查你的系统

Docker对Linux支持最好。我个人习惯用Ubuntu 20.04或22.04。Windows也能跑，但需要WSL2，性能会打点折扣。

先确认内核版本：

uname -r
# 建议 5.4 以上

2.2.2 安装Docker Engine

别用apt直接装，版本太旧。去官网走官方源：

# 卸载旧版本
sudo apt-get remove docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 设置稳定版仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

小技巧： 装完后记得把当前用户加入docker组，不然每次都要sudo：

sudo usermod -aG docker $USER
newgrp docker

然后重启一下终端，试试 docker ps，不报错就对了。

2.2.3 验证安装

docker --version
# 输出类似：Docker version 24.0.7, build afdd53b

docker run hello-world
# 看到 "Hello from Docker!" 就说明OK了

我曾经遇到过一个问题：装完Docker后，拉镜像特别慢。后来发现是没配国内镜像源。你可以在 /etc/docker/daemon.json 里加上：

{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}

然后重启Docker：sudo systemctl restart docker。速度能快好几倍。

2.3 拉取FINN镜像

FINN的官方镜像托管在Docker Hub上。你直接拉就行：

docker pull xilinx/finn:latest

这个镜像大概有3-4GB，取决于网络状况，可能要等一会儿。你可以趁这个时间去喝杯咖啡。

拉完之后，检查一下：

docker images
# 应该能看到 xilinx/finn 这个镜像

注意： 如果你用的是Vivado 2022.1或更早版本，建议拉取带版本号的镜像，比如 xilinx/finn:v0.8。最新版镜像默认对应Vivado 2023.1。版本不匹配的话，编译HLS时会报奇奇怪怪的错误。

2.4 配置Vivado与XRT环境

这一步是很多人翻车的地方。FINN在Docker里跑，但Vivado和XRT需要安装在宿主机上。为什么？因为Docker里装Vivado太占空间了，而且许可证管理也麻烦。

所以，正确的做法是：宿主机装Vivado，Docker通过挂载目录来调用它。

2.4.1 安装Vivado

这个我就不细讲了，Xilinx官网下载安装包，一路Next就行。注意几点：

  • 安装路径不要有中文或空格。我习惯装到 /tools/Xilinx 下。
  • 勾选“Vivado HL WebPACK”或“Vivado HL Design Edition”，确保包含HLS工具。
  • 安装完成后，设置环境变量：
echo 'source /tools/Xilinx/Vivado/2023.1/settings64.sh' >> ~/.bashrc
source ~/.bashrc

验证一下：

vivado -version
# 应该能看到版本信息

2.4.2 安装XRT

XRT是Xilinx Runtime，用于FPGA与主机通信。如果你用的是Alveo加速卡或Versal开发板，这一步必须做。

安装XRT：

# 下载对应版本的XRT安装包
wget https://www.xilinx.com/bin/public/openDownload?filename=xrt_202320.2.17.0_Ubuntu_22.04-amd64-xrt.deb

# 安装
sudo apt install ./xrt_202320.2.17.0_Ubuntu_22.04-amd64-xrt.deb

# 设置环境变量
echo 'source /opt/xilinx/xrt/setup.sh' >> ~/.bashrc
source ~/.bashrc

验证：

xbutil examine
# 如果能看到设备信息，说明XRT工作正常

避坑指南： 我曾经在Ubuntu 22.04上装XRT 2022.1版本，结果死活不认设备。后来发现是内核版本太高，XRT的驱动不兼容。解决办法是降级内核到5.15，或者升级XRT到2023.1。你装之前最好查一下兼容性列表。

2.4.3 让Docker识别Vivado和XRT

现在，宿主机上Vivado和XRT都装好了。但Docker容器里还看不到它们。你需要用 -v 参数挂载目录：

docker run -it \
  -v /tools/Xilinx:/tools/Xilinx \
  -v /opt/xilinx:/opt/xilinx \
  -v /your/project/path:/workspace \
  xilinx/finn:latest /bin/bash

解释一下：

  • -v /tools/Xilinx:/tools/Xilinx：把宿主机Vivado挂进容器。
  • -v /opt/xilinx:/opt/xilinx：把XRT挂进去。
  • -v /your/project/path:/workspace：你的工程目录，方便在容器里读写代码。

进入容器后，执行：

source /tools/Xilinx/Vivado/2023.1/settings64.sh
source /opt/xilinx/xrt/setup.sh
which vivado
# 应该输出 /tools/Xilinx/Vivado/2023.1/bin/vivado

看到这个路径，就说明环境通了。

2.5 验证FINN环境

最后一步，跑一个简单的测试，确认FINN能正常工作：

# 在容器内
cd /workspace
python -c "import finn; print(finn.__version__)"
# 应该输出类似 0.8.0 的版本号

如果没报错，恭喜你，环境搭好了。如果报错说找不到模块，检查一下Python路径——FINN的镜像默认Python 3.8，别搞混了。

总结一下： 环境搭建就三步——装Docker、拉镜像、配Vivado+XRT。每一步都有坑，但按我上面写的来，基本一次过。我当年第一次搭的时候，卡在XRT驱动上折腾了一下午。现在你有了这份指南，应该半小时搞定。

下一章，我们会真正开始用FINN跑一个简单的神经网络。到时候你会发现，环境搭好了，后面的事就顺了。

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