第二章：开发环境搭建

说实话，搭建开发环境这事儿，看着简单，但坑是真不少。我见过太多人卡在这一步，折腾好几天都跑不起来。今天我就把经验掰开了揉碎了讲给你听。

2.1 安装Xilinx Vitis

先说说Vitis。这东西说白了就是Xilinx的统一开发平台，集成了SDK、HLS、Vivado这些工具。我个人习惯用2021.1版本，稳定，踩过的坑少。

⚠️ 注意： 版本选择很重要。FINN对Vitis版本有明确要求，别随便装个最新版就往上怼。我见过有人装了2022.2，结果FINN死活不认，折腾两天才发现是版本不匹配。

安装步骤其实不复杂：

  1. 去Xilinx官网下载Vitis安装包（大概20GB左右）
  2. 运行安装程序，选择Vitis + Vivado + HLS三个组件
  3. 安装路径别带中文和空格，这是老生常谈了
  4. 等...大概1-2小时，取决于你的网速和硬盘速度

嗯，这里有个小技巧。安装时选「Custom」模式，只勾选你需要的器件型号。全选的话，安装包能到100GB+，没必要。我一般只选Zynq和Kintex系列，够用了。

2.2 配置FINN环境

FINN环境配置，说白了就是让Python能找到Vitis的库和工具链。这里我踩过不少坑，一个个说。

2.2.1 安装依赖

先确认你的Python版本。FINN要求Python 3.8或3.9，别用3.10以上，有些库不兼容。

# 创建虚拟环境，我习惯用conda
conda create -n finn_env python=3.8
conda activate finn_env

# 安装基础依赖
pip install --upgrade pip
pip install numpy onnx onnxruntime
pip install pynq xrt
💡 提示： 用conda创建环境时，记得指定python版本。我曾经图省事没指定，结果装了一堆不兼容的包，最后全删了重来。

2.2.2 设置环境变量

这是最容易出问题的地方。Vitis安装完后，需要手动设置环境变量，让FINN能找到Xilinx的工具链。

# 在~/.bashrc或~/.zshrc中添加
export XILINX_XRT=/opt/xilinx/xrt
export XILINX_VIVADO=/tools/Xilinx/Vivado/2021.1
export XILINX_HLS=/tools/Xilinx/Vitis_HLS/2021.1
export PATH=$XILINX_XRT/bin:$XILINX_VIVADO/bin:$XILINX_HLS/bin:$PATH
export LD_LIBRARY_PATH=$XILINX_XRT/lib:$LD_LIBRARY_PATH

# 别忘了source一下
source ~/.bashrc

为什么会这样？因为FINN在编译和部署时，需要调用Vivado做综合布局布线，调用Vitis_HLS做高层次综合。找不到路径，它就罢工。

2.2.3 克隆FINN仓库

git clone https://github.com/Xilinx/finn.git
cd finn
pip install -e .

这里有个坑。FINN的master分支可能不太稳定，我建议用release版本。比如v0.7或v0.8，这些版本经过充分测试，问题少。

2.3 验证安装

环境配好了，怎么知道对不对？跑个简单的测试用例。

# 进入FINN目录
cd finn

# 运行一个简单的测试
python -m pytest tests/test_brevitas_export.py -v

# 或者跑一个完整的端到端示例
cd examples/notebooks
jupyter notebook end2end_example.ipynb

如果看到类似这样的输出，说明环境没问题：

============================= test session starts ==============================
collected 5 items

tests/test_brevitas_export.py::test_export_mlp PASSED                    [ 20%]
tests/test_brevitas_export.py::test_export_cnv PASSED                    [ 40%]
...
============================= 5 passed in 12.34s ==============================
✅ 验证清单：
  • Python能导入finn包（import finn）
  • Vivado能正常启动（vivado -version）
  • Vitis_HLS能正常编译（vitis_hls -version）
  • XRT驱动能识别设备（xbutil examine）

2.4 常见环境问题排查

这部分我花点时间细讲。因为环境问题占了FINN学习曲线的大头，至少70%的报错都跟环境有关。

问题1：找不到Vivado或Vitis_HLS

现象： 运行FINN时提示「vivado: command not found」

原因： 环境变量没设对，或者没source

解决： 检查环境变量路径是否正确。我习惯用which vivado来确认。如果返回空，说明路径有问题。

# 检查Vivado是否在PATH中
which vivado
# 如果返回空，手动指定路径
export PATH=/tools/Xilinx/Vivado/2021.1/bin:$PATH

问题2：Python版本不兼容

现象： 安装FINN时提示「Python 3.10 is not supported」

原因： FINN对Python版本有硬性要求

解决： 用conda创建3.8或3.9的环境。别想着硬改代码，我试过，最后发现改的代码比写的还多。

问题3：ONNX Runtime版本冲突

现象： 运行测试时提示「ONNX Runtime version mismatch」

原因： FINN依赖特定版本的ONNX Runtime

解决： 查看FINN的requirements.txt，安装指定版本。

pip install onnxruntime==1.12.0

问题4：XRT驱动问题

现象： 部署到FPGA时提示「No Xilinx device found」

原因： XRT驱动没装好，或者设备没插好

解决： 先检查硬件连接，再确认驱动加载。

# 检查XRT驱动状态
lsmod | grep xrt
# 如果没加载，手动加载
sudo modprobe xrt
⚠️ 重要提醒： 如果你用的是虚拟机，记得把USB设备透传过去。我有个学生折腾了两天，最后发现是虚拟机没识别到FPGA板子。

问题5：内存不足

现象： Vivado综合时崩溃，提示「Out of memory」

原因： FINN编译大模型时，Vivado需要大量内存

解决： 至少16GB内存，建议32GB。如果不够，可以调整Vivado的并行度。

# 限制Vivado使用的线程数
export VIVADO_NUM_JOBS=2

2.5 我的个人建议

说了这么多，总结几条实在的：

  • 用Docker：Xilinx官方提供了FINN的Docker镜像，省去环境配置的麻烦。我后来基本都用Docker，省心。
  • 备份环境：配好环境后，用conda export导出环境配置。万一搞坏了，一键恢复。
  • 别用Windows：FINN在Windows上支持很差，建议用Ubuntu 20.04或18.04。我见过有人在Windows上折腾一周，最后换Linux半天搞定。
💡 终极技巧： 如果你只是想快速体验FINN，可以用Google Colab。Xilinx官方有Colab notebook，在线就能跑，不用配环境。但说实话，真要搞项目，还是得本地搭环境。

好了，环境搭建就讲到这里。下一章我们开始真正动手，写第一个FINN自定义算子。到时候你会发现，环境配好了，后面的路就好走多了。

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