HALCON 的深度学习能力从 17.12 版本开始落地到商业产品线，官方提供了一套叫 MVTec Deep Learning Tool 的图形化工具，配合 HDevelop 里的 read_dl_model 、 apply_dl_model 这些算子，可以直接把一个图像分类项目从标注一路带到产线部署。这个流程我前后在工业视觉项目里用过多回，从工件分拣到表面缺陷检测，再到底色识别，把整套链路摸得很熟。今天就以图像分类为例，把“DeepLearningTool + HALCON”这套方案从环境搭建、数据准备、模型训练、评估调参，一直到 C# / QT 部署集成的完整过程讲透。不管你是刚接触 HALCON 的新手，还是想在现有视觉项目里引入深度学习的工程师，这篇都能给你一条可以直接落地的路径。

工业视觉里有个很现实的痛点：传统算法在背景干净、对比明显的场景下很能打，可一旦遇到纹理复杂、缺陷形态不固定、类别之间长得又很像的情况，阈值分割加 Blob 分析的方案就变得非常脆弱。深度学习分类模型天然擅长这种“说不清规则，但能看出区别”的任务。HALCON 的价值在于，它把深度学习从模型训练到推理部署的整条链路都做进了自家生态，你不用再像搞开源框架那样，脱离开视觉系统单独搭一套 Python 服务。下面直接进入正题。

1. 整体设计与思路拆解

1.1 为什么不是 PyTorch / TensorFlow，而是 HALCON

很多做视觉开发的工程师会问：深度学习分类用 PyTorch 不是更灵活吗，为什么要选 HALCON？我的回答是：看你的项目形态和团队构成。

如果你做的是纯算法预研、发论文或者做复杂网络结构创新，那 PyTorch / TensorFlow 自然无可替代。但工业视觉项目往往要求“视觉系统”整体交付，包含相机采集、图像预处理、UI 交互、PLC 通信、结果输出一整套。HALCON 的价值在“全链路”。你用 HALCON 做传统算法定位 ROI，然后直接在同一环境里调用深度学习模型做分类，精度不够了再用 Deep Learning Tool 补数据、重新训练。整套流程的数据接口、图像类型、坐标系统都是统一的，不需要写一堆胶水代码把 Python 和 C# 环境硬凑在一起。

另一个关键因素是合规。商用项目交付出去，客户对软件版权、模型授权都比较敏感。HALCON 的 Runtime License 机制很成熟，项目上线时买对应运行时授权即可，不涉及开源协议合规问题。相比之下，直接拿开源框架做商业交付，需要在许可证、依赖库版权方面格外小心，很多公司在这一块没有完整法务评估体系。

当然，HALCON 这套方案不是没有缺点。它给到的网络结构是封装好的，训练参数也是有限的几个开关，你要是想魔改 Backbone 或者自定义 Loss，它做不到。但换个角度想，工业分类任务绝大多数用官方预训练模型就够了，限制参数反而降低了对使用者的算法能力要求。

1.2 一个完整项目的流程分解

用 HALCON 做深度学习和自研框架有相似之处，但它的项目节奏有自己的一套。我习惯把整个项目切成五个阶段：

• 环境搭建 ：安装 HALCON、配置 License、确认 GPU / CPU 推理环境、按需安装 MVTec Deep Learning Tool。
• 数据准备 ：用工业相机或已有图库采集图像，清洗并剔除模糊、重复样本，然后统一尺寸、划分训练集 / 验证集 / 测试集。
• 数据标注 ：MVTec Deep Learning Tool 里新建分类任务，给每个图像打类别标签，导出成 HALCON 能直接读的标注文件。
• 模型训练与评估 ：选择预训练模型，设定 Epochs / Batch Size / Learning Rate，训练结束后看准确率、混淆矩阵、Loss 曲线，不够就调。
• 推理部署与集成 ：在 HDevelop 里验证推理效果，再把模型接入 C# / QT 工程，处理图片输入、结果显示、通讯输出等。

这五个阶段里，数据准备和标注往往占掉 60% 以上的时间。很多刚用 HALCON 做深度学习的人，一上来就急着训练，标注做得潦草，后面模型精度上不去才回来补数据，时间成本翻倍。建议第一次做的时候，每个类别的图片量至少准备 300 到 500 张，工业场景如果有光照、角度、焦距变化，还需要按产线的实际工况去覆盖，不要只拿实验室的干净图。

2. 环境准备与工具链搭建

2.1 HALCON 版本到底怎么选

HALCON 的深度学习能力不是所有版本都一样，选版本主要看两件事：一是你是否需要深度学习训练功能，二是你的 GPU 环境是否被支持。

这里给出一个基于我个人经验的参考表：

版本	深度学习推理	深度学习训练	建议场景
17.12	支持（CPU 为主）	不直接支持	老项目维护或仅做传统视觉
19.11	支持（GPU 加速成熟）	通过 DL Tool 支持	中后期项目兼容
20.11	支持	训练功能完善	性价比高，建议此版本起步
23.05 / 24.x	支持	支持新网络与增强功能	新项目首选

关于 MVTec Deep Learning Tool，它对应的是 HALCON 的深度学习训练界面，可以直接从 MVTec 官网下载，和 HALCON 主程序是分开安装的。很多用户只装了 HALCON，找不到标注和训练界面，原因就在于此。下载时注意选择与 HALCON 版本匹配的 Training Tool 版本，跨大版本容易读不了模型文件。

2.2 硬件配置与 License 配置

训练阶段建议用 NVIDIA 显卡，显存至少 8GB。我用过 6GB 显存的卡训练紧凑型分类模型，勉强能跑，但 Batch Size 被压得很低，训练速度很慢。推理阶段倒没那么苛刻，CPU 也能跑，只是速度慢不少。如果产线节拍要求在 100ms 以内出结果，最好还是上 GPU 推理。

License 配置是个高频踩坑点。正确步骤是：

1. 从 MVTec 官网申请试用 License，或者使用公司购买的正版 License 文件。
2. 将 License 文件拷贝到 HALCON 安装目录下的 license 文件夹（例如 C:\Program Files\MVTec\HALCON-xx\license ）。
3. 如果 HALCON 打开后提示找不到 License，检查环境变量 HALCONROOT 和 HALCONLICENSES 是否指向正确的安装目录。

我踩过的一个坑是：HALCON 装好后，单独把 License 文件放在了自定义文件夹，没有更新 HALCONLICENSES 环境变量，结果每次启动都提示 License 不识别。这个环境变量默认指向安装目录下的 license ，只要把文件放对位置，一般不用手动改。

验证安装是否成功，可以在 HDevelop 里执行：

read_dl_model ('pretrained_dl_classifier_compact.hdl', DLModelHandle)

如果返回了模型句柄，没有报错，说明 HALCON 能正常读取深度学习模型，工具链基本就绪。

2.3 C# / QT 开发集成环境准备

HALCON 的深度学习模型最终要部署到自己的上位机程序里，最常见的两种开发环境是 C#（WinForms / WPF）和 Qt（C++ / QML）。准备工作有两块：

• C# 环境 ：在 Visual Studio 中新建工程后，添加 HALCON 的 .NET 程序集 halcondotnet.dll 。这个文件一般在 C:\Program Files\MVTec\HALCON-xx\bin\dotnet35 或 dotnet461 目录下。引用后在代码里 using HalconDotNet; 就能调用 HALCON 算子了。
• Qt 环境 ：需要链接 HALCON 的 C++ 库。在 .pro 文件里添加 INCLUDEPATH += $$(HALCONROOT)/include 和 LIBS += -L$$(HALCONROOT)/lib/x64-win64 -lhalconcpp ，然后在代码里 include "halconcpp/HOperatorSet.h" 。

这两个环境的集成细节，我在后面推理部署章节再展开写，这里先确保工具链通路上没有断点。

3. 数据准备与标注细节

3.1 样本数量、类别平衡与图像质量

模型训练效果的上限由数据质量决定。分类任务里最容易出现的问题就是类别不平衡和图像信息不一致。

关于数量，我给一个最保守的建议：每个类别至少 300 张。当然越多越好，500 张以上会有明显改善。如果现场实在凑不够数量，可以先做数据增强，比如水平翻转、小角度旋转、缩放 0.9 到 1.1 倍、亮度扰动。需要注意，HALCON 的 Deep Learning Tool 本身提供了一些增强选项，但增强方式要和实际场景匹配。比如工件有方向性要求，就不能随便做旋转增强，否则模型会学到错误的不变性。

类别平衡方面，如果 A 类有 1000 张，B 类只有 100 张，模型训练时会对 A 类严重过拟合，B 类准确率会很低。处理办法有两种：一是收集更多 B 类数据；二是给 B 类做离线增强，把数量补到和 A 类接近。我在做缺陷分类时遇到过比例悬殊的情况，当时用增强把少数类从 100 张扩到 500 张，B 类召回率直接从 55% 拉到了 85% 以上。

图像质量有一条核心原则：训练集和现场推理图像的采集条件必须一致。如果现场是环形光源、低角度打光，而训练集用了另一台相机的图像，或者光照条件差异很大，模型上线后准确率会明显下降。这是最容易忽略却又影响最大的一个问题。

3.2 用 MVTec Deep Learning Tool 完成标注与训练配置

MVTec Deep Learning Tool 的界面逻辑很直观。以分类任务为例：

1. 打开 Deep Learning Tool，点击 “Create New Training Data Set” 创建新工程。
2. 导入图像目录，支持一次性导入文件夹内所有图片。
3. 选择任务类型 “Classification”。
4. 在标注界面里，一张张为图像选择类别标签。效率比较高的做法是分类别放到不同文件夹里，导入后先批量指定一个默认类别，再逐张去改异常样本。
5. 导出数据集，格式选择 HALCON 支持的 .hdl 数据集文件，以及对应的图像列表。

导出后你会得到一个数据集描述文件，HALCON 会用这个文件构建训练用的 DLDataset。这个文件务必和图像文件夹保持相对路径一致，不要把图像移走后再训练，否则加载数据时会疯狂报找不到文件。

标注时有一个容易犯的错误：“标签和实际类别对不上”。比如 A 类是有划痕工件，B 类是合格工件，如果标的时候把有划痕的图误标成了合格品，模型就会被带偏。建议标注完成后做一次反向抽检，随机抽 20% 的图，重新确认标签是否正确。这个环节花不了多少时间，但对模型上限的影响是决定性的。

3.3 数据集划分与文件命名规范

HALCON 训练分类模型时，数据需要划分为训练集、验证集和测试集。官方提供 split_dl_data_set 算子来切分数据集。我一般按 80% / 10% / 10% 的比例划分，示意代码如下：

* 加载标注好的数据集
read_dl_data_set ('data.hdl', DLDataset)
* 按比例切分数据集
split_dl_data_set (DLDataset, 0.8, 0.1, 0.1, 'random', DLDatasetSplit)

这里 'random' 表示随机切分，后续还可以通过参数控制随机种子，保证多次训练结果可复现。划分完毕后，HALCON 会在数据集对象里记录每张图像属于哪个子集，训练时自动读取对应子集。

文件命名上，我强烈建议只用英文和数字，不要用中文和特殊字符。HALCON 对中文路径的支持虽然没有完全拒绝，但实际运行中经常遇到编码问题导致的读取失败。我在项目里吃过一次亏：客户发来的图像集中在某个带中文名文件夹下，HDevelop 里能读，一到 C# 调用就报 HALCON error #2011: Invalid image ，后来把路径改成全英文才彻底解决。

4. 模型训练与调参

4.1 预训练模型怎么选

HALCON 提供了预训练的分类模型，我常用的是 pretrained_dl_classifier_compact.hdl 和 pretrained_dl_classifier_resnet50.hdl 。两者区别很直接：

模型文件	速度	精度	模型大小	适合场景
compact	快	稍低	较小	CPU 推理、产线节拍快、类别差异明显
resnet50	较慢	更高	较大	GPU 推理、类别相似度高、纹理复杂

初次做项目，如果没把握，可以先从 resnet50 开始训练，看精度上限。精度达标后再尝试切到 compact 模型，对比推理时间和精度损失，决定最终部署选型。

HALCON 还支持从零训练一个分类模型，也就是创建 DLClassificationModel 时指定合适的网络结构。但从零训练需要的数据量和训练时间都远大于微调，工业项目里不推荐，除非你的图像和 ImageNet 分布差异太大，微调效果始终上不去。

4.2 训练参数设置与 Loss 曲线观察

训练的核心参数就那么几个： epochs 、 batch_size 、 learning_rate 。我的经验值是这样的：

• Epochs ：先设 50，如果训练到 30 轮时验证准确率已经不再提升，就可以提前停掉；如果 50 轮结束时 Loss 还在明显下降，追加到 100 轮。
• Batch Size ：训练阶段显存吃紧时从 8 或 16 开始，如果显存充足， 32 到 64 也可以。太大的 Batch Size 会让收敛变慢，并不总是好事。
• Learning Rate ：用微调模式时， 0.0001 到 0.001 是比较稳妥的区间。学习率太大 Loss 会震荡，太小收敛又很慢。

在 Deep Learning Tool 里，训练页面会实时显示训练损失、验证损失和验证准确率。我判断训练是否正常有一个快捷标准：验证准确率逐步上升且训练 Loss 和验证 Loss 差距不大，说明训练健康；如果训练 Loss 下降但验证 Loss 不降反升，就是过拟合信号，需要加数据、加增强或调低学习率。

训练参数可以在 HDevelop 里用算子直接设置：

set_dl_model_param (DLModelHandle, 'batch_size', 16)
set_dl_model_param (DLModelHandle, 'learning_rate', 0.0005)
set_dl_model_param (DLModelHandle, 'runtime', 'GPU')

'runtime' 参数可以在 GPU 和 CPU 之间切换，训练阶段设成 GPU 会快很多。需要确认你机器的 HALCON 版本支持 GPU 加速，并在 HALCON 环境变量里正确配置了 NVIDIA CUDA 相关依赖。

4.3 评估指标：准确率不够，要看混淆矩阵

训练完之后，Deep Learning Tool 会自动在验证集上做评估，给出整体准确率。但整体准确率会掩盖很多问题。比如 A 类样本占了 90%，模型全部判成 A 类，准确率也有 90%，但这显然不是一个可用的模型。

所以我会重点看混淆矩阵。HALCON 的评估界面能展示每一类的精确率、召回率和 F1 分数。我在实际项目里的做法是：

• 如果某两类的混淆值很高，说明这两类图像人眼都很难区分，优先回看原始图像，确认标注边界是否存在歧义。
• 如果某个类别召回率低，说明模型对这类图像不够敏感，需要补充该类的训练样本，或者增强该类在训练中的权重。
• 如果整体评估优秀，但测试集上就是有零星误判，需要检查这些误判样本是否来自采集条件差异，比如过暗、过亮、失焦。

HALCON 也提供了算子供你在 HDevelop 里自行评估：

evaluate_dl_model (DLModelHandle, DLDataset, 'none', GenParamEval, EvalResult)
* 获取混淆矩阵
get_dl_classification_result (EvalResult, 'confusion_matrix', ConfusionMatrix)

拿到混淆矩阵后，可以直接定位到最容易被分错的类别组合，再有针对性地补数据。

5. 推理部署与 C# / QT 集成

5.1 HDevelop 里的推理全流程

模型训练好并导出后，部署的第一步是在 HDevelop 里把推理流程跑通。完整的推理流程以图像分类为例：

* 1. 读取训练好的模型
read_dl_model ('classify_model.hdl', DLModelHandle)

* 2. 设置推理设备，GPU 或 CPU
set_dl_model_param (DLModelHandle, 'runtime', 'GPU')

* 3. 读取待检测图像
read_image (Image, 'test_image.png')

* 4. 执行推理，返回结果字典
apply_dl_model (DLModelHandle, Image, [], DLResult)

* 5. 提取分类结果
get_dl_classification_result (DLResult, 'top1_class', Top1Class)
get_dl_classification_result (DLResult, 'top1_confidence', Top1Confidence)

top1_class 返回的是类别的索引 ID，而不是类别名称。如果你想拿到“划痕”“正常”这种可读标签，需要在训练时记录类别 ID 与类别名字的映射关系，推理时自己做一次转换。 top1_confidence 是模型对该判断的置信度，通常我会设一个阈值（比如 0.8 或 0.9），低于阈值就判为“未知/拒绝”，避免模型不懂装懂。

HALCON 还支持取 Top-K 结果：

get_dl_classification_result (DLResult, 'top5_class', Top5Classes)
get_dl_classification_result (DLResult, 'top5_confidence', Top5Confidences)

如果产品允许二次确认，Top-5 结果对人工复判很有帮助。

5.2 C# 调用 HALCON 深度学习模型的两种方式

C# 集成 HALCON 大致两条路线：一种是直接调用 HALCON/.NET 的算子，另一种是加载 HDevelop 脚本。

先看直接调用算子的方式。在 Visual Studio 里引用 halcondotnet.dll 后：

using HalconDotNet;

// 读取模型
HTuple dlModelHandle;
HOperatorSet.ReadDlModel("classify_model.hdl", out dlModelHandle);

// 读取图像
HObject image;
HOperatorSet.ReadImage(out image, "test_image.png");

// 执行推理
HTuple dlResult;
HOperatorSet.ApplyDlModel(dlModelHandle, image, new HTuple(), out dlResult);

// 提取结果
HTuple top1Class, top1Confidence;
HOperatorSet.GetDlClassificationResult(dlResult, "top1_class", out top1Class);
HOperatorSet.GetDlClassificationResult(dlResult, "top1_confidence", out top1Confidence);

// 关闭模型句柄
HOperatorSet.ClearDlModel(dlModelHandle);

这种方式的好处是代码流程完全可控，适合需要精细控制异常抛错、记录日志的业务逻辑。要注意 ApplyDlModel 的输入图像既可以是单张 HObject ，也可以是一个 HObject 数组，后者会走批量推理，吞吐量更高。

另一种方式是 HDevEngine 加载 HDevelop 脚本。先在 HDevelop 里把推理流程写成一个外部过程，比如 classify_image ，然后在 C# 中调用：

using HalconDotNet;

HDevEngine engine = new HDevEngine();
engine.SetProcedurePath(@"C:\VisionProcedures\");

HDevProcedure proc = new HDevProcedure("classify_image");
HDevProcedureCall call = proc.CreateCall();

call.SetInputCtrlParamTuple("image_path", "test_image.png");
call.Execute();

HTuple className = call.GetOutputCtrlParamTuple("class_name");
HTuple confidence = call.GetOutputCtrlParamTuple("confidence");

这种方式最大的优点是：算法工程师可以直接在 HDevelop 里调整预处理和推理流程，不需要重新编译 C# 工程。部署现场如果只改阈值这类参数，改脚本即可热生效，维护成本低很多。缺点是脚本被封装成黑盒，遇到问题需要整个链路排查。

5.3 QT 调用 HALCON 的注意点

QT 环境一般走 HALCON 的 C++ 接口。核心调用链和 C# 类似，示例：

#include "halconcpp/HOperatorSet.h"
using namespace HalconCpp;

// 读图
HObject image;
ReadImage(&image, "test_image.png");

// 读取模型
HTuple model;
ReadDlModel("classify_model.hdl", &model);

// 推理
HTuple result;
ApplyDlModel(model, image, HTuple(), &result);

// 取结果
HTuple top1Class, top1Confidence;
GetDlClassificationResult(result, "top1_class", &top1Class);
GetDlClassificationResult(result, "top1_confidence", &top1Confidence);

QT 里有一个高频问题： QImage 和 HObject 转换时通道顺序。HALCON 中彩色图像默认是 RGB 顺序，但很多相机 SDK 输出的是 BGR，如果不注意转换，直接用 QImage 抠图再塞给 HALCON，会出现颜色错乱。稳妥的办法是在相机 SDK 回调里先把图像数据按 RGB 重整，再构造成 HObject 。

此外，QT 工程里如果同时用了 OpenCV，需要注意 HALCON 的 HObject 和 OpenCV 的 Mat 互转。我常用逻辑是：先用 HALCON 做传统定位，把 ROI 区域裁出来转成 OpenCV Mat 做其他处理，最后再转回 HALCON 做深度学习分类。转换函数不复杂，但要特别注意内存释放，否则长时间运行后内存涨得很快。

5.4 部署阶段的性能与稳定性优化

模型部署后，性能主要看三个方面：单次推理耗时、吞吐量、稳定性。

单次推理耗时可以通过设置推理设备来拉开差距。CPU 推理在复杂模型上可能要几百毫秒，GPU 推理可以压到几十毫秒。HALCON 里设置：

set_dl_model_param (DLModelHandle, 'runtime', 'GPU')

如果现场有多张 GPU 卡，还可以指定 gpu_id ：

set_dl_model_param (DLModelHandle, 'gpu_id', 0)

批量推理是提高吞吐量的手段。对于图片幅面不大且产线节拍紧的场景，可以把多张待检图像收集成一个数组，一次性调用 apply_dl_model ，GPU 利用率会明显提高。代价是结果处理逻辑变复杂，需要按数组索引对应到每一张图。

稳定性方面，我特别提醒三个点：

1. 模型句柄不要反复读取释放 。程序启动时一次性加载模型，常驻内存。
2. 对置信度做阈值判断 。低置信度输出单独归类，不要强行给出类别。
3. 图像输入尺寸要固定 。HALCON 在推理时会自动做预处理，但如果你的业务本身有裁剪或缩放逻辑，务必保证所有现场图和训练图的分辨率习惯一致。

6. 常见问题与排查技巧实录

6.1 高频报错与解决方案速查

报错现象	可能原因	解决办法
License not found	License 文件路径不对	将 License 放入 HALCONLICENSES 指向的文件夹
Model file not found	.hdl 模型文件路径错误	确认路径全英文，且模型文件与程序在同一机台
Out of memory	显存不足或 Batch Size 过大	降低 Batch Size，或在其他进程释放 GPU 显存
Invalid image	图像格式不支持或路径含中文	转成 HALCON 支持的格式，路径改为全英文
Deep learning model version mismatch	模型的 HALCON 版本与当前不一致	使用相同版本的 HALCON 重新导出模型
ApplyDlModel failed on GPU	GPU 驱动或 CUDA 版本不匹配	更新驱动，确认 HALCON 对应 CUDA 依赖完整

6.2 训练效果不达预期的排查路线

训练完发现验证准确率很低，先别急着调参数，我按下面的顺序排查：

1. 检查标注是否准确 。找随机 10% 的样本人工复看标签，如果错误率超过 2%，先修正标注再说。
2. 检查数据划分是否泄漏 。同一物体不同角度的图像如果被随机划分到了训练集和测试集，评估结果会偏乐观，上线后真实表现会差很多。如果是这种情况，应该按物体或场景划分数据。
3. 检查类别是否均衡 。训练集里如果某类数量极少，模型很可能对该类直接放弃。
4. 检查图像分辨率和样本尺度 。如果训练图里目标有大有小，模型会去学尺度特征，而不是类别特征。建议先归一化到固定尺寸。
5. 检查增强参数是否过强 。增强过猛会让模型学不到类别核心特征，尤其是旋转增强对方向敏感的工业件来说反而有害。

6.3 几个只有跑过项目才会注意到的细节

路径和命名规范是老生常谈，但每次都能遇到人踩坑，我再强调一遍：项目部署目录、图像保存路径、模型文件路径，全部用英文，不要带空格，更不能带中文。这一点在 C# 和 QT 集成的场景下尤其关键。

还有一个容易忽略的点是模型文件的后备管理。每次重新训练都会覆盖旧模型，如果不做版本管理，改坏了参数回不了头。我现在的习惯是模型文件按 model_20250111_146_acc.hdl 这种规则命名，保留最近几版，上线前再做一次对比验证。

图像采集一致性也是只有跑过现场才会真正重视的问题。实验室里用同一批图像训练推理，往往数据很干净，但一到客户现场，光照变了，镜头的安装距离变了，图像偏暗偏亮，模型准确率立刻掉下来。这时候第一时间要做的不是重新训模型，而是检查现场图与训练图的亮度、对比度、色温分布差异，能用预处理消除的差异先用预处理解决，再谈补充训练数据。

最后一个心得关于“拒识”。很多工业分类项目对准确率要求极高，宁可让模型说“我不认识”，也不能让它硬猜。我在部署时一定会加置信度阈值，低于阈值的统一归为“待人工确认”，而不是随便塞给某一个类别。这样既保护了产品线，也方便后期收集难例数据继续迭代模型。

这套流程从训练到部署，跑通一次之后，后续再遇到新的分类任务，基本就是按模板操作：采集图像、标注、训练、评估、部署。刚开始做第一个项目时可能会觉得步骤很多，但第二个、第三个项目就会越来越顺。HALCON 这个生态最大的优势就是工具链闭环，把精力集中在数据质量上，模型性能反而不用太操心。