cv_resnet18_ocr-detection workdirs目录：模型输出路径全解
1. 模型与工具背景
1.1 cv_resnet18_ocr-detection 是什么
cv_resnet18_ocr-detection 是一个专为中文场景优化的轻量级 OCR 文字检测模型，底层基于 ResNet-18 主干网络构建，兼顾精度与推理效率。它不负责文字识别（OCR 中的 Recognition 部分），只专注解决“文字在哪”的核心问题——即精准定位图像中所有文本区域的四边形坐标（polygon detection）。这种“检测先行、识别后置”的设计，使其天然适配多语言、多字体、倾斜/弯曲排版等复杂真实场景。
该模型由科哥独立完成工程化封装与 WebUI 集成，已预训练于大量中文街景、文档、电商截图等真实数据，开箱即用，无需额外标注或调参即可应对日常办公、内容审核、自动化录入等高频需求。
1.2 为什么 workdirs 目录如此关键
在实际使用中，用户最常遇到的困惑不是“怎么检测”，而是“结果存哪了？”、“微调后的模型在哪找？”、“导出的 ONNX 文件藏在哪？”。这些问题的答案，几乎全部指向同一个目录：workdirs/。
它不是临时缓存，也不是日志归档区，而是整个 cv_resnet18_ocr-detection 系统的核心产出中枢——所有模型训练、导出、调试过程中生成的关键资产，都按规范结构沉淀于此。理解它的组织逻辑，等于掌握了整套工具链的“文件地图”。
2. workdirs 目录结构全景解析
2.1 根目录概览
进入项目根目录后，执行：
ls -l workdirs/你将看到类似如下结构：
workdirs/ ├── checkpoints/ # 训练过程中的模型快照 ├── exports/ # ONNX 导出产物 ├── logs/ # 训练与服务运行日志 ├── temp/ # 临时中间文件（如预处理图、缓存） └── train_20260105_143022/ # 单次训练会话专属目录（时间戳命名）注意：
workdirs/是相对路径，其物理位置始终位于项目根目录下（即/root/cv_resnet18_ocr-detection/workdirs/）。所有 WebUI 操作产生的持久化输出，均以此为统一落点。
2.2 checkpoints/：模型权重的保险库
该目录存放训练过程中自动保存的模型检查点（checkpoints），用于断点续训或效果回溯。
文件命名规则：
epoch_{N}_best.pth或epoch_{N}.pthepoch_{N}_best.pth：当前训练中验证指标最优的权重（如 F-measure 最高）epoch_{N}.pth：第 N 轮训练结束时的完整快照
典型内容示例：
workdirs/checkpoints/ ├── epoch_3_best.pth # 第3轮达到最佳效果 ├── epoch_5.pth # 第5轮完整快照 └── epoch_10.pth # 最终轮次实用建议：
- 生产部署推荐使用
*_best.pth文件，稳定性更高； - 若需对比不同训练阶段效果，可手动替换
models/下的权重并重启服务； - 该目录不随 WebUI 操作自动清理，请定期归档或删除旧版本释放空间。
- 生产部署推荐使用
2.3 exports/：ONNX 模型的交付中心
当你在 WebUI 的「ONNX 导出」Tab 中点击“导出”后，生成的.onnx文件将严格按输入尺寸命名，存入此目录。
文件命名规则：
model_{height}x{width}.onnx
例如：model_640x640.onnx、model_800x800.onnx、model_1024x1024.onnx配套文件：每次导出还会生成同名
.json元信息文件，记录：- 输入尺寸、归一化参数（mean/std）
- 检测头输出格式说明
- 模型构建时间与版本号
为什么尺寸要分开存？
不同输入尺寸对应不同计算图结构与内存占用。640×640 版本适合边缘设备快速推理，1024×1024 则为高精度场景保留细节。exports/目录让你能“一目了然”地管理多规格模型，避免混淆。
2.4 logs/：问题排查的第一现场
该目录是诊断系统行为的“黑匣子”，包含两类日志：
| 子目录 | 内容 | 更新频率 | 查阅场景 |
|---|---|---|---|
train/ | 每次训练的完整 stdout + stderr 输出 | 每次训练新建 | 训练失败时定位报错行、查看 loss 曲线收敛性 |
webui/ | WebUI 启动、请求处理、异常堆栈日志 | 持续追加 | 服务无响应、接口超时、上传失败等 |
日志文件命名：
train_20260105_143022.log/webui_20260105.log（日期前缀确保可追溯）高效查阅技巧：
# 实时跟踪最新 WebUI 日志 tail -f workdirs/logs/webui_*.log # 快速定位训练错误（搜索 ERROR 或 Traceback） grep -n "ERROR\|Traceback" workdirs/logs/train/*.log
2.5 temp/：临时文件的“中转站”
此目录存放 WebUI 运行时的瞬态数据，具有以下特点：
自动清理机制：服务重启后，该目录内容通常被清空（除非代码显式禁用）；
典型内容：
- 用户上传图片的原始副本（
upload_*.jpg） - 检测过程中的中间特征图（
.npy格式，仅调试开启时生成） - 批量任务的分片缓存（
batch_chunk_*.pkl）
- 用户上传图片的原始副本（
注意事项：
- 不建议依赖
temp/中的文件做长期存储； - 若发现磁盘空间异常增长，可安全清空此目录（需先停止 WebUI 服务）。
- 不建议依赖
2.6 train_YYYYMMDD_HHMMSS/：单次训练的完整档案
这是 workdirs 中最具“仪式感”的目录——每次点击「开始训练」，系统都会创建一个以启动时间精确命名的专属文件夹，完整封存本次训练的全部上下文。
标准结构：
train_20260105_143022/ ├── config.yaml # 训练参数快照（含 batch_size、lr、数据路径等） ├── model_best.pth # 最优权重（软链接至 checkpoints/） ├── model_last.pth # 最终权重（软链接至 checkpoints/） ├── metrics.json # 关键指标（precision/recall/fmeasure/loss） ├── visualization/ # 验证集检测效果可视化（原图+框+文本） │ ├── val_001_result.jpg │ └── val_002_result.jpg └── logs/ # 本次训练的详细日志（软链接至 logs/train/） └── train_20260105_143022.log核心价值：
- 可复现性：
config.yaml确保你能用完全相同的参数重新跑通实验； - 效果直观比对：
visualization/下的图片让你无需写代码，直接肉眼判断模型是否学到了关键特征； - 决策依据：
metrics.json提供量化指标，避免主观“感觉效果还行”。
- 可复现性：
3. workdirs 与 outputs 目录的关系辨析
初学者常混淆workdirs/和outputs/，二者定位截然不同：
| 维度 | workdirs/ | outputs/ |
|---|---|---|
| 核心定位 | 模型生命周期管理目录（训练、导出、调试） | 用户推理结果输出目录（检测、识别） |
| 内容性质 | 工程资产（权重、日志、配置、中间产物） | 业务结果（带框图、JSON 坐标、纯文本） |
| 生成触发 | WebUI 的「训练微调」「ONNX 导出」操作 | WebUI 的「单图检测」「批量检测」操作 |
| 命名逻辑 | 时间戳为主（train_2026...）、功能分类（exports/） | 严格时间戳（outputs_20260105143022/） |
| 是否可删除 | 可删，但会丢失训练成果与调试线索 | 可删，仅影响历史结果回溯 |
一句话记住：
workdirs/是“造车车间”，outputs/是“交车现场”。你想升级引擎，去workdirs/；你想查上个月的检测报告，去outputs/。
4. 实战：从零定位一次微调的完整产出
假设你在 WebUI 中完成了一次自定义训练，现在需要将最优模型部署到生产环境。以下是标准操作路径：
4.1 步骤一：确认训练会话目录
查看workdirs/下最新创建的train_*.*/目录：
ls -t workdirs/ | head -n 1 # 输出：train_20260105_1430224.2 步骤二：提取最优权重
进入该目录，找到model_best.pth（它是一个指向checkpoints/的软链接）：
cd workdirs/train_20260105_143022/ ls -lh model_best.pth # 输出：model_best.pth -> ../checkpoints/epoch_7_best.pth4.3 步骤三：验证模型有效性
利用 WebUI 的「单图检测」功能，上传一张验证集图片，将model_best.pth覆盖至models/目录并重启服务，观察检测框是否更贴合文字边缘、漏检率是否下降。
4.4 步骤四：导出为 ONNX 并交付
- 在 WebUI「ONNX 导出」Tab 中，选择与训练时一致的输入尺寸（如 800×800）；
- 导出完成后，前往
workdirs/exports/找到model_800x800.onnx； - 将该文件及配套
model_800x800.json一并交付给下游部署团队。
5. 进阶：自定义 workdirs 路径（高级用户）
默认workdirs/位于项目根目录，但可通过修改配置实现路径重定向：
5.1 修改 WebUI 启动脚本
编辑start_app.sh，在python launch.py命令前添加环境变量：
export WORKDIRS_ROOT="/data/ocr_workdirs" bash start_app.sh5.2 修改 Python 配置（需代码级调整）
若需永久生效，可编辑configs/config.yaml，新增：
workdirs: root: "/data/ocr_workdirs" subdirs: checkpoints: "checkpoints" exports: "exports" logs: "logs" temp: "temp"风险提示：自定义路径需确保目标目录存在且服务进程有读写权限，否则训练/导出将静默失败。
6. 总结：workdirs 是你的 OCR 工程仪表盘
workdirs/目录远不止是一个文件夹——它是 cv_resnet18_ocr-detection 的状态显示器、成果收纳箱、问题诊断台。掌握它的结构，你就拥有了：
- 掌控力：清楚知道每一次训练、每一次导出，究竟留下了什么；
- 可追溯性：当线上效果波动时，能快速定位是哪个模型版本、哪组参数导致；
- 协作效率：与同事共享
train_*/目录，等于共享了完整的实验上下文； - 运维信心：面对磁盘告警，能精准判断哪些子目录可清理、哪些必须保留。
不必死记硬背每个子目录，只需记住这个心法：凡是“我主动发起的、有状态变化的操作”，其结果必落于workdirs/；凡是“我被动接收的、面向业务的结果”，则存于outputs/。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
