cv_resnet18如何启动服务？start_app.sh脚本使用详解-编程阁

cv_resnet18如何启动服务？start_app.sh脚本使用详解

1. 模型与服务概览

1.1 cv_resnet18_ocr-detection 是什么

cv_resnet18_ocr-detection 是一个专为中文场景优化的轻量级 OCR 文字检测模型，基于 ResNet-18 主干网络构建，兼顾精度与推理速度。它不负责文字识别（OCR 中的 Recognition 部分），而是专注解决“文字在哪”的核心问题——即精准定位图像中所有文字区域的位置，输出带坐标的检测框。

这个模型由科哥独立完成工程化封装，已集成完整 WebUI 界面，开箱即用，无需额外配置深度学习环境。你拿到的不是原始模型权重，而是一个可一键运行的服务镜像，背后自动处理了模型加载、推理引擎初始化、HTTP 接口绑定和前端交互逻辑。

它适合部署在边缘设备、开发测试机或小型服务器上，尤其适合对延迟敏感、资源受限但又需要稳定文字定位能力的场景，比如文档扫描预处理、票据结构化前的区域裁剪、APP 截图分析等。

1.2 为什么是 start_app.sh 而不是直接 python app.py

你可能会疑惑：既然这是个 Python Web 应用，为什么不直接运行python app.py？答案在于健壮性与一致性。

start_app.sh不只是一个简单的启动命令包装器，它承担了三项关键职责：

环境隔离：自动激活项目专属的 Python 虚拟环境（如venv/），避免系统全局包冲突；
进程守护：使用nohup后台运行，并将标准输出重定向到logs/app.log，确保终端关闭后服务不中断；
端口与日志标准化：统一指定 WebUI 端口为7860，并预设日志路径，方便后续排查问题。

换句话说，start_app.sh是科哥为你写好的“安全启动开关”，绕过它直接调用 Python 可能导致依赖缺失、端口占用或日志丢失等问题。

2. 启动服务全流程详解

2.1 执行前的必要检查

在运行start_app.sh前，请花 30 秒确认以下三点，能避免 90% 的启动失败：

目录是否正确：你必须位于模型根目录下，路径应为/root/cv_resnet18_ocr-detection（或你实际解压/克隆的位置）。可通过pwd命令验证。
脚本权限是否就绪：执行ls -l start_app.sh，确认输出中包含x（可执行位），如显示-rwxr-xr-x即正常。若无x，运行chmod +x start_app.sh补充权限。
端口是否空闲：WebUI 默认监听7860端口。执行lsof -ti:7860或netstat -tuln | grep :7860，若无任何输出，说明端口可用；若有输出，需先终止占用进程或修改脚本中的端口号。

2.2 启动脚本逐行解析

打开start_app.sh文件，你会看到类似如下内容（已去除注释，保留核心逻辑）：

#!/bin/bash cd "$(dirname "$0")" source venv/bin/activate nohup python webui.py --port 7860 --server-name 0.0.0.0 > logs/app.log 2>&1 & echo $! > logs/app.pid echo "============================================================" echo "WebUI 服务地址: http://0.0.0.0:7860" echo "日志文件: logs/app.log" echo "进程ID文件: logs/app.pid" echo "============================================================"

我们来逐句解释它在做什么：

cd "$(dirname "$0")"：无论你从哪个目录执行该脚本，它都会先切换到start_app.sh所在的目录，确保后续路径引用准确；
source venv/bin/activate：激活项目内置的虚拟环境，所有 Python 包（如gradio、torch、opencv-python）都从此环境加载；
nohup python webui.py ... > logs/app.log 2>&1 &：这是核心命令：
- nohup让进程忽略挂起信号（SIGHUP），即使你关闭 SSH 连接也不会退出；
- python webui.py是真正的 WebUI 入口，--port 7860指定端口，--server-name 0.0.0.0允许外部 IP 访问（非仅 localhost）；
- > logs/app.log 2>&1将程序的标准输出（stdout）和错误输出（stderr）全部重定向到日志文件，便于追踪；
- &表示后台运行；
echo $! > logs/app.pid：$!是上一条后台命令的进程 ID（PID），将其写入app.pid文件，为后续停止服务提供依据。

2.3 启动后的状态验证

执行bash start_app.sh后，你会立即看到类似这样的提示：

============================================================ WebUI 服务地址: http://0.0.0.0:7860 日志文件: logs/app.log 进程ID文件: logs/app.pid ============================================================

但这只是脚本执行完成，并不代表服务已就绪。请按以下步骤验证服务真实状态：

检查进程是否存在：运行ps aux | grep webui.py | grep -v grep，应看到一行包含python webui.py --port 7860的进程；
检查端口监听：运行lsof -ti:7860，应返回一个数字（即 PID），证明端口已被成功绑定；
查看实时日志：运行tail -f logs/app.log，等待几秒，你会看到类似Running on public URL: http://xxx.xxx.xxx.xxx:7860的日志，此时服务真正就绪；
浏览器访问测试：在本地电脑浏览器中输入http://你的服务器IP:7860，若出现紫蓝渐变首页，即启动成功。

注意：首次启动可能需要 10–20 秒加载模型权重，日志中会出现Loading model...提示，耐心等待即可，不要重复执行脚本。

3. 服务管理：启动、停止与重启

3.1 如何优雅停止服务

start_app.sh只负责启动，停止需手动操作。最安全的方式是读取 PID 并发送终止信号：

# 读取进程ID PID=$(cat logs/app.pid) # 发送终止信号（gradio 会优雅关闭） kill $PID # 验证是否已退出 ps -p $PID > /dev/null || echo "服务已停止"

如果你不确定 PID 是否有效，或想强制终止，可使用：

pkill -f "webui.py --port 7860"

执行后，建议再运行lsof -ti:7860确认端口已释放。

3.2 一键重启脚本（推荐自建）

为提升效率，你可以在项目根目录下新建一个restart.sh脚本：

#!/bin/bash echo "正在停止服务..." PID=$(cat logs/app.pid 2>/dev/null) if [ -n "$PID" ] && kill -0 $PID 2>/dev/null; then kill $PID sleep 2 fi echo "正在启动服务..." bash start_app.sh

赋予执行权限：chmod +x restart.sh，之后只需bash restart.sh即可完成重启，无需记忆多条命令。

3.3 日志文件的实用价值

logs/app.log不仅记录启动信息，更是排障第一手资料。常见问题对应的关键日志线索如下：

模型加载失败：搜索OSError或FileNotFoundError，通常指向weights/目录下缺少.pth文件；
CUDA 错误（GPU 版本）：出现CUDA out of memory或cuDNN error，说明显存不足，需降低 batch size 或改用 CPU 模式；
端口被占用：日志末尾出现Address already in use，需先停止其他服务；
依赖缺失：报错ModuleNotFoundError: No module named 'xxx'，说明虚拟环境未正确激活或包安装不全，可重新运行pip install -r requirements.txt。

建议养成习惯：遇到任何异常，第一反应是tail -20 logs/app.log查看最近 20 行日志。

4. WebUI 核心功能实操指南

4.1 单图检测：从上传到结果解读

这是最常用的功能，整个流程不到 10 秒。以一张电商商品截图为例：

上传图片：点击“上传图片”区域，选择 JPG/PNG/BMP 格式文件。注意：图片尺寸建议不超过 2000×2000 像素，过大可能导致内存溢出；
观察预览：上传后左侧自动显示原图缩略图，确认内容无误；
调整阈值：拖动滑块至 0.25（默认值），若文字密集且清晰，可保持；若背景杂乱，可微调至 0.3；
触发检测：点击“开始检测”，右上角会出现旋转加载图标，同时日志中inference_time字段会记录本次耗时；
结果三件套：
- 文本列表：右侧显示带编号的纯文本，支持鼠标选中 → Ctrl+C 复制，适合粘贴到 Excel 或文档；
- 可视化图：下方显示叠加检测框的图片，每个框对应一行文本，颜色区分不同置信度；
- JSON 坐标：展开“检测框坐标 (JSON)”区域，你会看到boxes字段——这是一个八维数组[x1,y1,x2,y2,x3,y3,x4,y4]，代表文本框四个顶点的像素坐标，可直接用于后续裁剪或标注。

小技巧：检测完成后，页面 URL 会自动追加?image=xxx参数，刷新页面可复现该次结果，方便对比不同阈值效果。

4.2 批量检测：高效处理多张图片

当你有 10 张以上截图需要统一分析时，批量模式比单图重复操作快 5 倍以上：

上传方式：点击“上传多张图片”，按住Ctrl键可多选，或Shift键连续选择；
阈值同步：此处的阈值滑块与单图检测联动，调整一次即全局生效；
结果呈现：处理完毕后，页面以画廊形式展示所有结果图，每张图下方标注其检测到的文本行数；
下载限制说明：“下载全部结果”按钮当前仅下载首张图的可视化结果（detection_result.png），这是设计使然，非 Bug。如需全部结果，建议使用“单图检测”配合脚本自动化。

4.3 ONNX 导出：为生产环境铺路

ONNX 是工业界通用的模型交换格式，导出后你可脱离 Python 环境，在 C++、Java 或嵌入式设备上部署。操作虽简单，但有两点必须注意：

输入尺寸决定性能边界：640×640适合手机端实时检测，1024×1024适合高精度文档分析。一旦导出，该尺寸即固定，无法在推理时动态调整；
导出后务必验证：下载.onnx文件后，不要直接投入生产。用文末提供的 Python 示例代码快速跑通一次，确认输出boxes和scores与 WebUI 一致，再进行下一步集成。

5. 故障排除实战手册

5.1 “打不开网页”问题的三层诊断法

这是新手最高频问题，按以下顺序排查，95% 可解决：

第一层：网络连通性

在服务器上执行curl -I http://127.0.0.1:7860，若返回HTTP/1.1 200 OK，说明服务本身正常，问题出在网络；
若失败，则跳至第二层；
在本地电脑ping 服务器IP，确认基础连通；若不通，检查云服务器安全组是否放行7860端口。

第二层：服务进程状态

运行ps aux | grep webui.py，确认进程存在；
若无进程，检查logs/app.log是否有ImportError类错误；
若有进程但curl仍失败，执行lsof -ti:7860，确认端口是否真被绑定。

第三层：Gradio 配置细节

打开webui.py，查找launch()函数调用，确认参数含server_name="0.0.0.0"（允许外部访问）和share=False（禁用 Gradio 公网共享）；
若误设为server_name="127.0.0.1"，则只能本机访问，需修改后重启。

5.2 检测结果为空的三大原因

上传图片后，文本列表和可视化图均为空白？别急，按优先级检查：

图片无有效文字：用画图工具打开该图，放大至 200%，确认确实存在可读文字。纯色背景、极小字号（<10px）、严重模糊的图片，模型大概率无法检测；
阈值设置过高：将滑块拉到 0.05，重新检测。若此时出现结果，说明原阈值过滤掉了低置信度框，属正常现象；
模型权重损坏：进入weights/目录，运行ls -lh，确认resnet18_ocr_det.pth文件大小是否超过 40MB。若只有几 KB，说明下载不完整，需重新获取权重。

5.3 内存爆满的应急方案

当top显示内存使用率超 95%，服务响应缓慢甚至崩溃时：

立即措施：停止服务kill $(cat logs/app.pid)，释放内存；
长期方案：
- 在start_app.sh的python webui.py命令后添加--no-gradio-queue参数，关闭 Gradio 内部队列，减少内存缓存；
- 批量检测时，严格限制单次上传数量 ≤ 20 张；
- 若服务器内存 < 4GB，建议全程使用 CPU 模式，在webui.py中注释掉device = "cuda"相关行，强制使用device = "cpu"。