Windows自定义识别模块

ICDFactory 自定义识别模块接入指南

本文件既是接口规范，也是可直接交给大模型的开发说明。大模型应先分析用户现有识别项目，再按本规范生成或修改入口文件。

教育版用户如需在 ICDFactory 中使用大模型能力，请先到平台 LLM Key 页面创建平台 Key，并在 ICDFactory 设置中配置。

推荐用法：将本 HTML 文件与识别模块项目源码一起上传给大模型，并要求它“读取本文件，分析项目结构，生成符合 ICDFactory 接口的入口文件和打包命令”。

一、用户操作流程

准备项目：确保原识别项目已经能够加载模型并对图片或视频执行推理。

交给大模型：上传本 HTML 和项目源码。模型文件过大时无需上传，但应提供模型格式、加载方式和调用参数。

生成入口：让大模型结合项目实际语言、框架、配置和推理函数，创建一个命令行入口；不得脱离现有项目臆造模块名。

打包编译：按大模型给出的命令生成 Windows .exe。Python 项目可使用 PyInstaller/Nuitka，其他语言使用对应发布工具。

配置环境：把该 .exe 所在目录加入 Windows 系统环境变量 PATH，然后完全退出并重新启动 ICDFactory。

开始识别：在“自动识别 → 自定义模块”的命令框输入程序名、模型及算法参数，点击“开始识别”。

自动识别窗口命令示例

WildlifeRec --weights "D:\models\best.engine" --threshold 0.5

第一段是 PATH 中的程序名称；后面的参数由自定义入口定义，用来指定模型或推理选项。不要填写 EXE 的绝对路径，也不要填写下面两个由 ICDFactory 管理的参数：

--input_dir
--progress_file

二、给大模型的任务要求

大模型必须先分析项目，再写入口。应定位项目的模型加载、预处理、推理、后处理、类别映射及媒体遍历逻辑，尽量复用已有代码，只补充协议适配层。

大模型最终应交付：

入口文件的完整代码，并说明保存位置。
新增或修改文件清单，以及依赖变更。
本地调试命令，覆盖图片/视频、无检测结果和异常场景。
生成 Windows EXE 的可执行打包命令；如需附带配置、动态库或模型，明确其相对位置。
自动识别窗口中应填写的最终命令示例，其中应明确指定模型。

可直接复制给大模型的提示词

请完整阅读随附的《ICDFactory 自定义识别模块接入指南》HTML，并检查我上传的整个识别项目。

先说明项目使用的语言/框架、现有推理入口、模型加载方式、类别映射、预处理和后处理流程；再基于项目真实结构生成一个 ICDFactory 入口文件。优先复用现有推理代码，不要虚构不存在的模块、函数或路径。

入口必须接受 --input_dir 和 --progress_file，并把检测结果写为媒体同目录同名 UTF-8 TXT；必须按规范持续、原子地更新进度 JSON。请处理递归目录、大小写扩展名、图片/视频、空结果、单文件失败和进程退出码。

最后请给出：
1. 完整入口代码及保存位置；
2. 必要的项目修改和依赖；
3. 可复现的本地测试命令；
4. Windows EXE 打包/编译命令；
5. 把 EXE 目录加入系统 PATH 的步骤；
6. ICDFactory 自动识别窗口中用于指定模型的完整命令示例。

如项目中存在无法确定的模型参数、类别映射或视频处理规则，请先指出并向我提问，不要自行猜测。

三、ICDFactory 启动协议

ICDFactory 会针对队列中的每个布设文件夹分别启动一次识别程序，并在用户命令后自动追加：

--input_dir "<布设文件夹绝对路径>" --progress_file "<布设文件夹>\recognition_progress.json"

参数	含义	要求
`--input_dir`	单个待识别布设文件夹的绝对路径	递归扫描支持的媒体；不得修改或删除原媒体
`--progress_file`	ICDFactory 读取的进度 JSON 路径	启动后尽快创建，运行期间持续覆盖更新

退出码 0 表示成功，非零值表示失败。成功退出前，进度状态必须已写为 completed。

ICDFactory 不通过 Shell 启动模块。不支持 Python/Conda/PowerShell/CMD 等解释器、BAT/CMD、绝对或相对 EXE 路径、管道、重定向及其他 Shell 操作符。只允许填写 PATH 中的 Windows .exe 名称及其普通参数。

四、输入媒体

入口应递归处理 --input_dir 内支持的媒体，并保留目录结构和原文件：

.jpg  .jpeg  .png  .gif  .bmp  .avi  .mp4  .mov  .wmv  .flv

扩展名匹配应忽略大小写。是否逐帧检测视频由识别项目决定，但输出仍以该视频为单位写一个同名 TXT。

五、识别结果 TXT 协议

仅对有检测结果的媒体，在其同一目录写入同名 UTF-8 .txt。允许只输出部分媒体；没有结果时可以不创建文件或创建空文件。

类别 置信度 x_center y_center width height

示例：

豹猫 0.932 0.51 0.48 0.32 0.41
野猪 0.870 0.24 0.53 0.18 0.36

字段	规则
类别	单个不含空白字符的类别名
置信度	有限小数，范围 `0 ≤ value ≤ 1`
`x_center, y_center`	边界框中心点相对媒体宽高的归一化坐标，范围 `0–1`
`width, height`	边界框相对媒体宽高的归一化尺寸，范围 `0–1`，且必须大于 0

每个非空行表示一个检测框，必须恰好六段。像素框 (x1,y1,x2,y2) 可按下式转换：

x_center = ((x1 + x2) / 2) / image_width
y_center = ((y1 + y2) / 2) / image_height
width    = (x2 - x1) / image_width
height   = (y2 - y1) / image_height

六、进度 JSON 协议

程序启动后必须尽快创建指定的进度文件。ICDFactory 在 15 秒内未读取到合法 JSON 会终止程序。因此应先写 starting，再加载大型模型。

{
  "status": "running",
  "processed_files": 12,
  "total_files": 100,
  "current_file": "DCIM/IMG_0012.JPG"
}

字段	类型	规则
`status`	字符串	只能是 `starting`、`running`、`completed` 或 `failed`
`processed_files`	整数	`0 ≤ processed_files ≤ total_files`
`total_files`	整数	待处理媒体总数，必须非负
`current_file`	字符串	当前媒体相对路径；没有时使用空字符串

必须原子更新：先把完整 JSON 写入进度文件同目录的临时文件，刷新并关闭后，再用系统原子替换操作覆盖 --progress_file，防止 ICDFactory 读到半个 JSON。

启动 → starting → running（循环更新）→ completed → 退出码 0
                         ↘ failed → 非零退出码

七、打包、环境变量与运行

1. 打包为 Windows EXE

打包方式由项目技术栈决定。入口可以依赖同目录的模型、配置和动态库，但发布目录移动后仍应可运行。打包前应先用普通命令行运行入口完成协议测试。

Python 项目的示意命令（入口文件名和附加资源必须按项目实际修改）：

pyinstaller --noconfirm --clean --name WildlifeRec your_icdfactory_entry.py

不要机械复制示意命令。深度学习运行库、CUDA DLL、配置文件、类别文件及项目内部包经常需要显式收集；应让大模型结合项目结构给出最终打包参数，并在一台干净环境中验证产物。

2. 加入系统 PATH

找到最终 EXE 所在目录，例如 D:\ICDRecognizers\WildlifeRec。
打开 Windows“编辑系统环境变量”→“环境变量”。
编辑用户或系统变量 Path，新增该目录（不是 EXE 文件路径）。
打开新的命令提示符，执行 where WildlifeRec.exe 验证。
完全退出并重启 ICDFactory，使新的 PATH 生效。

3. 在自动识别窗口指定模型

进入“自动识别”，选择“自定义模块”，在命令框内填写：

WildlifeRec --weights "D:\models\wildlife_v3.engine" --threshold 0.5

模型参数名由入口程序定义，也可以是 --model、--checkpoint 或配置文件参数。关键是命令中只提供程序名、模型和算法参数，不重复输入 ICDFactory 自动追加的参数。

八、交付前验收清单

EXE 可由新终端仅通过程序名启动，where 程序名.exe 能找到它。
--help 或错误提示中能看到 --input_dir 与 --progress_file。
启动 15 秒内产生字段完整的合法进度 JSON。
进度计数满足 0 ≤ processed_files ≤ total_files，成功前写入 completed。
递归处理所有受支持扩展名，且不改变原始媒体。
TXT 是 UTF-8，每个非空行恰好六段，坐标与置信度均合法。
模型加载失败、参数错误或不可恢复异常时写入 failed 并返回非零退出码。
自动识别窗口命令明确指定所需模型，但不包含路径形式的 EXE、Shell 操作符或保留参数。