CoolFace
Apppublic

wuxiaini/power-line-defect-detection

sourceHugging Facemitupdated 4d agoView on Hugging Face
0likes
App README

输电线路缺陷检测 Demo（YOLOv8 + Gradio）

项目简介（简历可直接引用，约 100 字）

基于 YOLOv8n 自研输电线路缺陷检测模型并完成云端部署：使用公开 CPLID 数据集训练，覆盖绝缘子与缺陷两类目标，mAP50 0.991、mAP50-95 0.829、缺陷召回率 100%；基于 Gradio 与 Hugging Face Spaces 搭建公开在线 Demo，上传图片即可输出缺陷框、类别、置信度与像素坐标，阈值可调，纯 CPU 推理、可现场演示。

功能特性

  • —上传输电线路 / 绝缘子图片，输出带检测框的标注图
  • —同步输出缺陷明细表：序号、类别、置信度、边界框坐标（x1/y1/x2/y2，像素）
  • —置信度阈值、NMS IoU 阈值可实时调节
  • —内置 2 张脱敏示例图，点击即自动出结果，无需现场找图
  • —纯 CPU 推理，无 GPU 依赖；类别名自动读取权重，不硬编码

目录说明

power-line-defect-demo/
├── app.py             # Gradio 主程序
├── requirements.txt   # 固定版本依赖
├── packages.txt       # Spaces 容器 apt 依赖
├── weights/best.pt    # YOLOv8n 模型权重（Git LFS 跟踪，随仓库推送）
└── examples/          # example1.jpg、example2.jpg（脱敏后，已紧密切裁）

一、本地跑通步骤

bash
# 1) 进入项目目录
cd power-line-defect-demo

# 2) 创建并激活虚拟环境（Python 3.10 及以上）
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

# 3) 安装依赖（固定版本，约 1~2 GB，含 PyTorch）
pip install -r requirements.txt

# 4) 放入权重：把训练得到的 best.pt 拷贝到 weights/best.pt
# 5) 放入示例图：把两张脱敏测试图命名为 example1.jpg、example2.jpg 放入 examples/
# 6) 启动
python app.py

浏览器打开终端提示的 http://127.0.0.1:7860 即可使用。 即使暂未放入权重或示例图，应用也能启动并在界面给出明确中文提示，不会报错崩溃。

二、推送到 Hugging Face Spaces（完整命令）

bash
# 0) 安装命令行工具并登录（Token 在 HF 网站 Settings → Access Tokens 创建，选 Write 权限）
pip install -U huggingface-hub
huggingface-cli login

# 1) 安装并初始化 Git LFS（权重、图片走 LFS，仅需执行一次）
git lfs install

# 2) 在你的 HF 账户下创建一个 Gradio 类型的 Space
huggingface-cli repo create power-line-defect-demo --space --space_sdk gradio

# 3) 初始化本地仓库并提交
git init
git add .
git commit -m "feat: YOLOv8 输电线路缺陷检测 Gradio Demo"

# 4) 关联远程 Space 仓库并推送（把 <你的用户名> 替换为实际 HF 用户名）
git branch -M main
git remote add space https://huggingface.co/spaces/<你的用户名>/power-line-defect-demo
git push -u space main

推送后在 Space 页面等待构建，状态变为 Running 后即可通过 https://huggingface.co/spaces/<你的用户名>/power-line-defect-demo 公开访问。 后续更新代码只需 git add . && git commit -m "update" && git push。

三、模型权重的三种托管方案对比

方案做法优点缺点适用情况
① Git LFS 随 Space（本项目默认，已采用）best.pt 放 weights/，由 .gitattributes 指定 LFS 跟踪，随 git push 上传最简单，一条命令完成；无额外配置；本地与线上路径完全一致权重与应用绑定；权重过大时 clone / 构建变慢权重 <500MB。本项目 YOLOv8n 的 pt 仅约 6MB，已采用此方案
② HF Hub 独立模型仓库新建一个 Model 类型仓库存权重，在 Space 的 Settings → Variables and secrets 配置变量 MODEL_REPO_ID=你的用户名/仓库名，应用启动时用 hf_hub_download 拉取应用与权重解耦；权重可独立版本管理、单独写进简历；支持大文件；更新权重无需重新构建镜像需多建一个仓库；冷启动首次多几秒下载权重较大（>500MB）、需多处复用权重
③ 云盘直链权重传 Google Drive / 百度网盘等，启动时用直链下载不占 HF 空间百度网盘等无稳定直链；Google Drive 大文件有确认页与限流；链接易失效；Spaces 构建机在海外，访问国内云盘常超时不推荐，仅在前两种都不可用时临时使用

权重超过 2GB 时怎么办（两种明确方案）：

  • —方案 A（推荐）：采用上面的方案②，权重放独立 HF Hub 模型仓库，运行时 hf_hub_download 拉取（HF 公开仓库单文件上限 50GB，免费 Space 磁盘 50GB，容量足够，但冷启动下载耗时增加）。
  • —方案 B（更彻底）：先压缩权重再部署——导出为 ONNX / OpenVINO 并做 INT8 量化，通常可把体积缩小数倍、推理更快，代价是精度可能小幅下降（需重新跑一遍测试集核对 mAP）。
  • —不要把 >2GB 权重直接塞进 Space 的 git 历史，会显著拖慢每次构建。

四、CPU 推理慢的优化建议

免费 Space 为 2 vCPU / 16GB 内存。按代价从低到高：

  1. 1.输入分辨率：app.py 中 INPUT_SIZE 默认 640（训练默认值，全规格通用、不掉点）。
  2. 2.降到 480：理论提速约 (640/480)²≈1.8 倍，小目标可能漏检；
  3. 3.降到 320：理论提速约 4 倍，小目标漏检风险明显。
  4. 4.取舍：追求面试流畅可试 480 并用自己的测试图核对检出效果；不建议在未验证的情况下直接用 320。
  5. 5.导出 OpenVINO / ONNX（推荐，提速且不掉点）：
bash
   yolo export model=weights/best.pt format=openvino imgsz=640

导出后把加载方式由 YOLO("weights/best.pt") 改为 YOLO("weights/best_openvino_model/")，CPU 上通常有明显提速；INT8 量化版本更快但需验证精度。

  1. 1.模型规格：若实际是 l/x 且延迟不可接受，重训一个 s 规格是最省心的选择（你的数据 mAP 余量很大）。
  2. 2.线程数：代码已默认 torch.set_num_threads(2) 与 2 vCPU 对齐，可通过环境变量 CPU_THREADS 调整。
  3. 3.面试前预热：提前 3–5 分钟打开一次链接，避免休眠冷启动等待。

五、局限性说明（请如实写进演示口径）

  • —模型基于自采 CPLID 数据集训练，覆盖的电压等级、杆塔 / 绝缘子型号、拍摄角度与光照条件有限；分布外图片可能出现漏检或误检。
  • —mAP50=0.991、缺陷召回率 100% 是在该测试集划分上的结果，不代表任意真实场景，样本量较小时指标置信区间较宽。
  • —Demo 仅输出缺陷的位置、类别与置信度，不评定缺陷严重程度，不给出检修结论，不能替代人工验收或生产安全系统。
  • —对严重遮挡、运动模糊、远距离小目标，定位与分类精度会下降。
  • —免费 CPU Space 存在休眠与冷启动，不保证实时性与可用性 SLA。

六、隐私与脱敏

内置示例图片已脱敏处理：杆塔编号、线路名称、地理特征等信息均已去除，图片长边压缩至 1280px 以内。请勿向公开 Space 上传含真实位置、资产编号等敏感信息的原始巡检图片。

七、实测环境与指标（2026-09-20）

  • —模型规格：YOLOv8n（nano），3,006,038 参数 / 8.1 GFLOPs；训练 50 epoch，best.pt 取自第 47 epoch（按 0.1·mAP50+0.9·mAP50-95 选优）。
  • —验证集指标（128 张 / 236 实例）：整体 P 0.961、R 0.993、mAP50 0.991、mAP50-95 0.829；insulator（195 实例）R 0.987、mAP50 0.987；defect（41 实例）R 1.000（41/41 全召回）、mAP50 0.995。
  • —示例图实测：example1.jpg 检出 defect 0.913 / insulator 0.912；example2.jpg 检出 insulator 0.897 / defect 0.888。
  • —本地推理速度（i7-13620H，CPU）：首次约 1.4 秒（含预热），热推理约 0.06 秒/张。
  • —Spaces 构建机为 Linux，requirements 中全部为跨平台包；Space Python 版本为 3.11 或 3.12。