配置MatConvNet真不算复杂但坑在于版本之间的咬合关系比较严特别是要把ECO-GPU这种老派但依然能打的目标跟踪器跑起来Matlab 2019a、VS2017、CUDA 10这套组合几乎是绕不开的一个搭配。我自己当初折腾这套环境花了好几天中间踩了无数坑最后算是把整个链路跑通了。这篇就把完整的配置过程、每一步的为什么以及我实际踩过的坑全部写出来给后面还要配这套环境的朋友省点时间。1. 版本选择的逻辑和可行性分析先说结论Matlab 2019a VS2017 CUDA 10这个组合是MatConvNet编译和ECO-GPU运行都比较舒服的一个版本搭配不是唯一的但基本是最省心的一组。1.1 MATLAB 2019a与VS2017的匹配关系Matlab自带MEX编译器机制编写C/C扩展的时候需要调用外部编译器。不同版本的Matlab对编译器支持范围不一样具体到2019a这个版本它对Visual Studio的处理支持是从VS2015到VS2019但真正稳定兼容、踩坑最少的是VS2017。核心原因在于Matlab 2019a的MEX接口底层依赖的运行时库和VS2017的vc14.1工具集匹配度很高链接阶段很少出现符号冲突或者运行时库不一致的问题。如果你用VS2019去配合Matlab 2019a也不是完全不能跑但经常遇到的问题是mex -setup无法正确识别VS2019或者识别了却在编译时报一堆LNK4075之类的链接警告因为VS2019默认的v142工具集会引入一些新的运行时行为导致生成的MEX文件和Matlab 2019a自带的依赖库产生细微冲突。用VS2017则基本可以一步到位因为Matlab 2019a官方发布的MEX模板就是按VS2017的工具集生成的。还有一个细节很多人忽略VS2017安装时不需要装全所有组件但必须安装“使用C的桌面开发”工作负载否则系统里根本没有C编译器和Windows SDKmex -setup自然就找不到编译器。当初我第一次装的时候只装了C#相关的组件结果折腾半天编译器识别不出来。1.2 CUDA 10与GPU驱动的关系CUDA版本和显卡驱动之间有严格的对应关系。CUDA 10.0要求的驱动版本最低是411.31通常说410以上就基本兼容如果你是NVIDIA 10系或20系显卡这个驱动门槛很好满足。但要注意CUDA 10和Matlab 2019a之间有一个重要的兼容前提Matlab 2019a内部的GPU支持是基于CUDA 10开发的具体来说是针对CUDA 10.0的toolkit进行过测试的。这里我特别提醒一点Matlab 2019a官方文档里写的是“支持CUDA 10.0”但如果你装了CUDA 10.1或更高版本MatConvNet编译时大概率会报版本不对因为MatConvNet的vl_compilenn脚本会根据nvcc版本生成不同的编译参数CUDA 10.1改了某些编译选项之后会导致生成的GPU代码和Matlab 2019a的CUDA运行时库不匹配。所以别贪心装高版本CUDA就老老实实用CUDA 10.0补丁包10.0 Update 1也可以。另外如果你手头是比较新的显卡比如3060、4060这类安培架构卡实际CUDA 10会无法正常工作因为新架构需要高版本CUDA才能发挥完整算力甚至驱动本身就不支持旧CUDA toolkit做运行时加载。这也是为什么整套配置更适合老显卡环境RTX 2080及以下基本都没问题。1.3 为什么ECO-GPU需要这套组合ECOEfficient Convolution Operators是目标跟踪领域一个很有代表性的算法它在保持较高精度的同时大幅提升了速度。ECO-GPU是它的GPU加速版本运行推理和训练都依赖深度特征提取网络而这一层特征网络在MatConvNet框架下加载预训练模型因此要求MatConvNet编译好GPU支持。ECO作者提供的代码基于MatConvNet而MatConvNet的GPU支持依赖三个东西Matlab、C编译器、CUDA toolkit。这三者必须满足MatConvNet编译脚本内部预设的版本阈值。MatConvNet对Matlab版本没有特别严格的限制旧一点的版本也能跑但对于GPU编译CUDA版本必须和Matlab自带的Parallel Computing Toolbox中GPU支持包的版本对得上。Matlab 2019a对应的CUDA支持版本就是10.0如果换成Matlab 2020a则是CUDA 10.2或11.0这也是为什么我反复强调这个组合——拆开来看其实都是各自版本的最稳选择组合在一起就是天作之合。2. 搭建编译环境安装验证和前置工作配置这套环境不是装上软件就完事每一环都要验证否则后面编译失败你根本分不清是编译器问题还是CUDA问题。我自己吃过这个亏下面把每个验证步骤都列出来。2.1 检查GPU算力与驱动版本动手之前先用GPU-Z或者NVIDIA控制面板确认两件事显卡的算力等级和当前驱动版本。算力等级决定CUDA代码编译时的arch参数MatConvNet编译时要指定显卡架构。比如GTX 1060是Pascal架构算力6.1编译参数里要把-arch对应加上Turing架构的RTX 2080算力是7.5参数又不一样。如果不加MatConvNet会默认用一套兼容性参数也能跑但性能不是最优部分op可能出问题。驱动版本也很好验证NVIDIA控制面板的系统信息里能看到。如果驱动版本低于411.31CUDA 10装完后nvcc -V能显示版本但实际运行GPU代码时Matlab会报CUDA driver version is insufficient这个问题非常阴间因为你看不到驱动有什么异常但GPU计算就是跑不起来。建议直接装一个较新的稳定版驱动比如451.77或461.92这类驱动向下兼容CUDA 10完全没问题。驱动太老反而麻烦。2.2 安装并验证VS2017 C环境VS2017的安装过程基本都是下一步点到底关键点在于组件选择。打开安装器后选择“使用C的桌面开发”工作负载右侧会自动带上Windows 10 SDK、VC 2017工具集、以及CMake相关的组件。这些默认选中项建议保持不动其他用不到的工作负载比如UWP开发、.NET桌面开发可以不选能省不少磁盘空间。装完后别急着打开Matlab先在开始菜单找到“VS2017的开发人员命令提示符”打开后输入cl如果显示类似Microsoft (R) C/C Optimizing Compiler Version 19.16的版本信息说明C编译器已经正常可用。这一步很重要因为有些时候VS壳能正常打开但真正的C工具链没有装完整cl会提示找不到命令这种环境去Matlab里配置编译必然失败。验证完cl之后再打开一个普通的CMD输入以下命令确认SDK注册信息where link where nmake如果这些都能找到说明VS2017的环境是完整的。此时打开Matlab 2019a在命令行执行mex -setup正常情况下会列出可用的C编译器选择对应VS2017的选项即可。如果提示找不到编译器大概率是VS组件缺失回头重装对应的桌面开发负载就行。2.3 安装CUDA 10并验证nvccCUDA 10.0的安装包从官网下载即可建议下载完整安装包约2GB左右别用网络版因为网络版在安装过程中对网络环境要求很高容易中断。安装时选择自定义安装里面的组件默认全选即可但要注意不要勾选Visual Studio Integration中的VS2017选项如果它有弹窗提示不兼容的话。虽然CUDA安装器一般对VS2017有官方支持但我遇到过装了CUDA集成之后VS2017的cl环境反而变慢的情况后来重装系统后我再装CUDA就刻意取消VS Integration组件只保留Driver、CUDA Runtime、Development组件。这些核心组件才是编译所必需的。安装完成后打开一个新的CMD依次输入nvcc -V systeminfo | findstr /i cudanvcc -V会显示Cuda compilation tools的版本信息比如release 10.0, V10.0.130。确认这条命令输出正常后打开Matlab运行gpuDevice如果Matlab能正确输出你的显卡信息比如Name: GeForce GTX 1080 Ti和ComputeCapability: 6.1说明Matlab已经能调起GPU这是后面编译GPU MEX的前提。如果这里就报错那MatConvNet编译基本不用想了先解决gpuDevice的问题再看其他。提示gpuDevice报错一般有三种情况没有装Parallel Computing Toolbox、驱动太老、或者显卡算力太低。前两种好解决第三种只能换机器或者放弃GPU版。3. MatConvNet编译的完整操作环境验证完毕后真正核心的部分就是编译MatConvNet。这一步是整条链路的枢纽编译成功之后后面ECO-GPU只是配置路径的问题编译失败则会卡住很长时间所以这里每一步都要仔细。3.1 下载MatConvNet并准备目录从MatConvNet的GitHub仓库下载代码或者直接用git clone拉取。推荐使用git clone因为仓库里包含了所有需要的外部依赖子模块如果用zip下载很容易缺文件。git clone --recursive https://github.com/vlfeat/matconvnet.git--recursive参数会把matlab、examples以及底层依赖的vlfeat子模块都拉下来。如果忘了加这个参数也没关系后续可以在代码库根目录执行git submodule update --init --recursive补拉子模块。这一步很多人忽略结果编译到最后报缺失vl_imreadjpeg之类的函数折腾半天其实只是子模块没拉全。下载完成后把MatConvNet代码放到一个路径纯净的地方我建议直接放在C:\matconvnet或者D:\matconvnet这种和Matlab安装目录无关的路径下。千万别放在带中文或者空格的路径里比如C:\用户\张三\matconvnet这条路径英文化和不带空格是最稳的否则编译时的Makefile解析路径会出现莫名其妙的问题。3.2 理解vl_compilenn的关键参数MatConvNet的编译入口是vl_compilenn函数在Matlab中调用它即可完成MEX编译。这个函数有多个参数其中几个直接影响GPU编译的成败vl_compilenn(enableGpu, true, ... cudaMethod, nvcc, ... cudaRoot, C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.0, ... cudaArch, 6.1, ... enableImreadJpeg, true, ... verbose, 1);各参数含义enableGpu是否启用GPU编译必须为true。cudaMethod编译GPU代码的方式填nvcc这也是唯一合理的方式。cudaRootCUDA安装根目录默认路径一般就是上述路径如果你的CUDA装在其他位置需要对应修改。cudaArch你的显卡算力版本GTX 10系填6.1RTX 20系填7.5。如果填了不匹配的架构代码可以编译成功但运行时某些算子的速度和稳定性都差一截。enableImreadJpeg是否启用Matlab自带的JPEG读取功能ECO-GPU中用不到图像分类那套流程但建议开启因为后续跑其他实验会方便。verbose输出详细编译信息卡住的时候能看到具体卡在哪一步。这里cudaArch很多人会填错因为MatConvNet官方示例写的是5.2之类那是旧文档。如果你的显卡算力和填的参数不匹配有些MEX函数会报no kernel image is available for execution on the device这个错误在运行时非常隐蔽因为编译不报错。最简单的办法是在Matlab里执行gpuDevice查看你的ComputeCapability然后把这个数字填进去。3.3 编译过程对照与结果验证执行编译命令后Matlab会开始逐条编译MEX文件这个过程大概持续十到二十分钟取决于机器配置和VS编译器的线程数。编译过程中会大量刷屏如果verbose1会看到每条编译命令的细节。编译结束后命令行会提示类似Getting computer ... Setting up ... Building with nvcc ... Compiling ...并且不会出现红色的error信息。此时切换到MatConvNet的根目录执行addpath(fullfile(pwd, matlab)); vl_setupnn然后运行自带的简单测试vl_test(gpu, true)vl_test会跑一组快速测试完整跑完可能需要几分钟。重点看输出中是否有GPU相关测试用例通过。如果出现类似vl_test_nnconv_gpu的FAIL项说明编译产物有问题需要回头检查cudaArch或者CUDA版本。这是我个人强烈建议的一步很多人编译完就直接去跑ECO结果一运行就崩回头排查发现是MatConvNet本身的GPU算子不过关白白浪费时间。注意如果vl_test中大部分测试通过但个别测试超时或者失败常见原因有两个。一是显卡驱动不是最新的旧的驱动和CUDA 10在某些算子上有兼容问题二是显卡显存不够部分测试对显存要求比较高。可以先用小batch的测试用例跑一遍确认基础算子正常。4. ECO-GPU代码部署MatConvNet编译完毕最难的部分已经过去了。接下来就是把ECO-GPU的代码正确部署到Matlab里让它可以加载预训练模型并跑起来。4.1 获取代码并整理依赖路径ECO-GPU的官方代码可以从作者的GitHub仓库获取。代码仓库的结构不算复杂核心目录包括ECO核心跟踪器代码、utils工具函数、deep_features深度特征提取相关。拿到代码后第一件事是检查代码里引用的MatConvNet路径是否正确。ECO代码通常在某个配置文件中会写上matconvnet根目录的路径比如在run_ECO.m或者某个startup.m里addpath(genpath(/path/to/matconvnet/matlab));你必须把这个路径改成自己机器上实际的MatConvNet目录。这里我建议改完之后用一段简单的代码验证路径是否正确exist(vl_setupnn, file)如果返回2说明Matlab能找到vl_setupnn函数路径配置没问题如果返回0说明路径没有生效后面运行ECO百分之百会报Undefined function vl_setupnn。ECO代码本身的startup.m还会调用vl_setupnn初始化MatConvNet这一般会自动完成。但要注意ECO是较早的代码它可能会调用vl_nnconv这类底层函数的一些旧签名而新版MatConvNet可能对部分函数签名做了调整。如果运行时报参数个数错误可以在MatConvNet的matlab目录下搜索对应函数确认函数定义。4.2 修改配置文件参数ECO-GPU有两种运行模式ECO-GPU完整GPU版本和ECO-HC不使用深度特征的快速版本。我们的目标是前者所以需要设置好对应的参数。在ECO的代码里找到主运行脚本通常是run_ECO.m里面有一系列参数。关键参数包括net_type设置使用的特征网络类型一般填imagenet-vgg-m-2048这是ECO默认使用的网络。deep_features是否使用深度特征必须为true。gpu_id指定使用的GPU设备序号一般填1即可。model_path预训练模型的存放路径需要手动指定。其中model_path是个容易出问题的点。ECO需要下载预训练模型文件比如imagenet-vgg-m-2048.mat。这个模型文件比较大大约几百MB下载后需要放到合适的位置。把模型文件放到ECO目录下后配置model_path指向该目录即可。如果下载模型文件的网络不稳定可以考虑使用断点续传工具或者将其挂在网络条件较好的时机下载。模型文件不完整时Matlab加载会报Unable to read MAT-file届时还需要重新下载。4.3 首次运行与结果验证一切配置完成后在Matlab命令行切换到ECO目录执行run_ECO首次运行会看到一系列初始化日志包括加载网络模型、构建特征金字塔、初始化滤波器等过程。如果一切正常会弹出跟踪窗口并显示跟踪结果叠加视频帧。此时说明整套配置已经成功。如果运行过程中报错优先看错误信息中涉及的是哪个函数。常见的错误包括Undefined function or variable vl_imreadjpeg说明MatConvNet编译时没有启用JPEG读取支持或者vl_setupnn没有正确执行。Invalid MEX-file说明MEX文件是编译成功了但运行时依赖的某个DLL找不到通常是CUDA运行时库的路径没有加入系统环境变量。解决办法是把C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.0\bin和C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.0\libnvvp两个目录添加到系统PATH里然后重启Matlab。Out of memory说明显存不足ECO在默认参数下大约需要4GB以上显存如果是4GB以下的显卡建议关闭CNN特征或者使用ECO-HC。提示如果机器显存紧张可以在ECO参数里把use_gpu设为1但将cnn_features设为false这样会退化为使用手工特征的ECO-HC模式显存占用大幅下降同时依然保持GPU加速的特性。5. 高频报错与排查实录配置过程中总会遇到各种报错这里把我实际遇到过的几个高频问题整理成表附带排查路径方便对照。现象原因解决方案mex -setup找不到编译器VS2017没装C桌面开发负载重装VS2017并勾选“使用C的桌面开发”vl_compilenn编译时报spmd相关错误Matlab并行工具箱未安装或版本不对检查ver命令输出中是否有Parallel Computing Toolbox编译完成后vl_test中GPU测试全失败cudaArch参数填错查看gpuDevice的ComputeCapability并修正参数运行ECO报Invalid MEX-fileCUDA运行时DLL未加入PATH把CUDA的bin目录加入系统PATH并重启Matlab运行ECO报Out of memory显存不足或显存被其他程序占用关闭其他占用显存的程序或改用ECO-HC加载模型时报Unable to read MAT-file模型文件不完整重新下载模型文件并确认MD5校验编译过程中cl内部编译错误VS2017更新工具集的bug安装VS2017的最新Update版本5.1 MATLAB直接闪退问题这个场景我遇到过好几次启动run_ECO后Matlab窗口直接就消失了连错误信息都没有。排查到最后基本是两种可能第一种是GPU驱动和CUDA运行时库版本冲突。如果Matlab一运行到GPU相关代码就闪退先检查gpuDevice是否能正常输出如果gpuDevice本身就导致闪退那就是驱动太老或者和当前CUDA版本不匹配升级驱动即可。第二种是显存不足导致的异常。ECO在初始化时会加载模型并分配大量显存如果此时其他程序占用了显存Matlab可能不会给出优雅的错误提示而是直接崩溃。这种情况下先把浏览器、游戏之类的显存占用程序关掉也可以考虑更换分辨率更低的输入数据进行测试。5.2 编译速度和配置效率的技巧编译MatConvNet最耗时的部分是编译几十个MEX文件如果中途失败再重新编译很多文件要重来。一个省时间的方法是先跑一遍不启用GPU的编译也就是vl_compilenn(enableGpu, false)这样能把CPU相关的MEX文件全部编译好排除CPU部分的问题。之后再添加GPU参数重新编译增量编译只会处理GPU相关的部分速度会快很多。另外一个实用技巧是把编译日志重定向到文件中方便排查错误diary(compile_log.txt) vl_compilenn(enableGpu, true, verbose, 1); diary off这样命令窗口的详细输出会保存到文件中出错后可以直接搜索日志里的error关键词定位问题。5.3 与其他框架共存的环境隔离如果你机器上同时装了其他深度学习框架比如PyTorch的CUDA版本那么环境变量中的PATH可能会有多个CUDA目录。这种情况下一定要确保Matlab使用正确的CUDA 10路径。一个简单的检查方法是在Matlab命令行中运行getenv(PATH)查看输出的PATH列表中CUDA相关目录顺序。如果在用户环境变量里手动添加了CUDA 10的路径但系统环境变量里先出现了更高版本CUDA的目录那么系统可能会优先加载高版本的DLL。解决办法是把CUDA 10的路径放在更靠前的位置或者删掉其他版本的CUDA路径。对于需要同时使用不同CUDA版本的场景建议在运行Matlab之前先设置当前CMD会话的环境变量指定CUDA目录然后从这个会话启动Matlab。这样可以保证Matlab进程内的CUDA环境完全受控不受全局配置干扰。5.4 ECO调试中一些不常被提及的点ECO-GPU是用VGG-M网络作为特征提取基座的如果显卡驱动或CUDA版本有问题网络前向推理时可能帧率极低。正常的配置在常见显卡上处理352x288的小序列时帧率应该能达到20FPS以上如果你的速度在个位数甚至更低优先怀疑cudaArch设置是否过保守。另外ECO的默认配置是为VOT或OTB数据集准备的数据集的读取路径需要正确配置才能跑起来。如果你是拿自己的视频文件测试需要将视频读取转换成代码期望的格式否则也会报各种读取错误。6. 一些经验和技巧总结配置这套环境的过程本质上就是一个版本匹配的游戏。Matlab 2019a、VS2017、CUDA 10、MatConvNet、ECO这五个环节任何一个地方的版本错了后面都会引发连锁反应。如果所有环节都严格配套一次跑通的概率是很高的。最后再分享一个实际工作中的小技巧MatConvNet编译好之后建议在MatConvNet目录下执行vl_setupnn并保存你的Matlab工作环境快照下次新开Matlab时会话自动加载路径省去重复配置的麻烦。另外如果你遇到模型加载之后首帧初始化速度很慢大约要等十几秒才看到第一帧结果这是正常的因为ECO在第一帧要做特征网络初始化、滤波器预训练等额外工作。后续帧的速度会明显提升。配置完了之后建议多看几个不同序列的测试结果确认不只是跑通了一段视频而是整个跟踪流程都正常工作。如果只在单一序列上测试成功可能掩盖了一些潜在问题比如某些分辨率下特征金字塔构建会失败这些现象在更大范围测试中才会暴露出来。多说一句这套配置虽然版本有些老但ECO这个算法至今在很多场景下依然有不错的参考价值。理解它需要MatConvNet这个框架作为支撑恰好也是接触MatConvNet编译流程的一个很好的契机。跑通之后你再去改其他基于MatConvNet的代码至少不会再被环境问题拦住思路。
