推理端 Ai 功能使用手册

版本日期：2026-05-09

适用对象：NVIDIA CUDA/TRT 通用版推理端。

程序名称：Ai.exe

一、推理端作用

推理端 Ai.exe 负责接收发射器发送过来的画面，加载模型，执行 TensorRT 推理，然后根据配置进行目标筛选、瞄准计算和输入设备控制。

推理端不负责采集远端机器画面。当前标准部署中，画面由发射器发送，推理端通过 UDP 接收。

二、目录结构

标准 NVIDIA CUDA/TRT 通用环境包解压后，根目录通常包含：

注意：

• Ai.exe 必须放在环境包根目录运行。
• 不要只单独复制 Ai.exe 到空目录运行，否则会缺少 DLL、模型或配置。
• 第一次运行 TensorRT 模型时，可能会根据当前显卡自动生成 .engine 文件。

三、启动前检查

启动前确认：

四、标准启动步骤

1. 解压 NVIDIA CUDA/TRT 通用环境包。
2. 解压 EXE 更新包。
3. 把 Ai.exe 放到环境包根目录。
4. 打开 config.ini，确认 capture_method = udp_capture。
5. 确认 udp_port = 1234。
6. 双击运行 Ai.exe。
7. 观察控制台是否出现 Listening on UDP 0.0.0.0:1234。
8. 启动发射器，并把目标 IP 设置为推理端机器 IPv4，端口设置为 1234。
9. 推理端控制台出现 g_capture_fps 大于 0 后，说明接收正常。
10. 第一次构建 TensorRT engine 时等待完成，不要中途关闭。

五、默认热键

当前标准配置的默认热键：

说明：

• 修改 config.ini 后，可以按 F4 重新加载配置。
• 涉及模型、后端、输入设备初始化的配置，建议重启 Ai.exe。
• 如果客户反馈按键不生效，先检查配置里的 button_targeting、button_shoot、input_method。

六、核心配置说明

配置文件：config.ini

1. 采集和接收

重要说明：

• udp_ip = 0.0.0.0 是监听地址，不是发射器目标地址。
• 发射器目标 IP 必须填写推理端机器真实 IPv4，例如 192.168.1.20。
• 发射器目标端口必须与 udp_port 一致，当前标准是 1234。

可选采集方式：

客户标准部署优先使用 udp_capture。

2. 模型和后端

说明：

• 第一次运行会根据 ONNX 和当前显卡生成 TensorRT .engine。
• .engine 与显卡架构、TensorRT 版本、部分配置相关，不建议跨机器直接复用。
• 如果更换显卡、升级 TensorRT 或模型异常，优先删除旧 .engine，保留 .onnx 后重新运行生成。

3. 输入设备

处理原则：

• 使用 KMBOX_NET 时，先确认 IP、端口、UUID 正确。
• 使用串口设备时，先在设备管理器确认 COM 口。
• 输入设备不工作时，先不要调模型，先确认 input_method 和设备连接。

4. 按键配置

5. 目标筛选和瞄准

类别配置示例：

class_def_0 = Class0,player,0.50
class_def_1 = Class1,head,0.50
class_def_3 = Class3,player,0.50
class_def_6 = Class6,head,0.50

说明：

• player 表示身体或人物目标。
• head 表示头部目标。
• disabled 表示忽略该类别。
• 类别阈值越高越保守，误识别更少，但可能漏检。

6. 显示和日志

客户排查问题时，建议保留 session_log_enabled = true。

七、控制台正常日志判断

启动正常时，控制台通常会出现以下信息：

[Startup] exe_path=...
[Startup] config_path=...
[Capture] capture_method=udp_capture udp_ip=0.0.0.0 udp_port=1234
[UDPCapture] Listening on UDP 0.0.0.0:1234
[Detector] Loading engine: ...
[MAIN] TRT 检测器已初始化

接收到发射器画面后，应看到：

[AimDbg][Capture] g_capture_fps=...

判断标准：

• g_capture_fps=0：没有收到有效画面。
• g_capture_fps 大于 0：推理端已经收到画面。
• 持续出现 Detector Error：模型推理或 CUDA/TRT 环境异常。

八、常见问题

1. 双击 Ai.exe 后提示缺少 DLL

原因：

• 只复制了 Ai.exe，没有放在完整环境包根目录。
• 环境包没有完整解压。
• 杀毒软件隔离了 DLL。

处理：

1. 重新解压 NVIDIA CUDA/TRT 通用环境包。
2. 把 Ai.exe 放到环境包根目录。
3. 确认根目录存在 CUDA、TensorRT、OpenCV 相关 DLL。
4. 把目录加入杀毒软件信任区。

2. 首次启动很慢

原因：

• TensorRT 正在根据当前显卡和 ONNX 模型构建 .engine。

处理：

• 等待构建完成。
• 不要中途关闭程序。
• 后续启动会直接加载已生成的 .engine，速度会明显变快。

3. RTX 50 系显卡报 no kernel image is available for execution on the device

原因：

• 使用了旧 CUDA/OpenCV 构建包，里面的 CUDA 内核没有包含 RTX 50 系 Blackwell 架构需要的 sm_120。

处理：

• 使用 2026-05-09 后整理的 NVIDIA CUDA/TRT 多架构通用包。
• 确认 OpenCV CUDA、TensorRT、CUDA DLL 来自同一套新环境包。
• 不要混用旧包里的 OpenCV CUDA DLL。

4. 控制台一直 g_capture_fps=0

原因：

• 推理端没有收到发射器画面。

检查顺序：

1. 发射器是否已经点击启动。
2. 发射器目标 IP 是否是推理端机器真实 IPv4。
3. 发射器目标端口是否是 1234。
4. 推理端是否显示 Listening on UDP 0.0.0.0:1234。
5. 推理端 config.ini 是否为 capture_method = udp_capture。
6. Windows 防火墙是否允许 UDP 1234。
7. 两台机器是否网络互通。

5. 日志里 decoded=0

原因：

• 收到了数据，但数据没有成功解码。

常见原因：

• udp_payload_xor 与发射器协议不匹配。
• 发射器版本和推理端版本不配套。
• 发射器用 TCP，推理端用 UDP，或反过来。
• 端口被其他程序占用或收到非本软件数据。

处理：

• 当前标准保持 udp_payload_xor = true。
• 发射器和推理端使用同一次交付的配套版本。
• 默认使用 UDP。
• 保证端口只给当前软件使用。

6. 检测器持续报错

处理顺序：

1. 关闭 Ai.exe。
2. 备份日志。
3. 删除 models 目录下旧的 .engine。
4. 保留 .onnx 模型。
5. 重新运行 Ai.exe 让 TensorRT 重新构建。
6. 如果仍然报错，检查显卡驱动、CUDA/TRT 包和显卡型号。

7. 输入设备不动

处理顺序：

1. 确认 input_method 是否符合实际设备。
2. KMBOX_NET 检查 IP、端口、UUID。
3. 串口设备检查 COM 口和波特率。
4. 检查设备是否被其他程序占用。
5. 检查是否按下了 F3 进入暂停状态。
6. 检查是否按住了正确的 button_targeting。

8. 修改配置后没有变化

处理：

• 保存 config.ini。
• 按 F4 重新加载配置。
• 如果修改的是模型、后端、输入设备初始化相关配置，直接重启 Ai.exe。

9. 延迟高或跟随慢

先排除画面链路：

• 发射器降低分辨率到 640x640 或 416x416。
• 发射器 JPEG 质量降低到 70 左右。
• 发射器 FPS 设置为 120 或 60。
• 使用 UDP。
• 尽量使用有线网络。
• 推理端确认 g_capture_fps 稳定。

再排除推理端配置：

• 检查 detection_resolution。
• 检查 confidence_threshold 是否过高。
• 检查 fovX / fovY 是否过小。
• 检查输入设备是否响应慢。

九、客户排查资料要求

推理端问题建议客户提供：

• Ai.exe 控制台完整截图。
• config.ini。
• session_logs 目录。
• models 目录文件列表。
• 显卡型号。
• NVIDIA 驱动版本。
• Windows 版本。
• 发射器系统页截图。
• 发射器参数页截图。

如果问题和 RTX 50 系相关，必须确认客户使用的是新版 NVIDIA CUDA/TRT 多架构通用包，不要继续在旧包上排查。