布料缺陷检测与定位项目使用指南

前置条件

Python 版本 >= 3.11（本项目在 3.13.13 下验证通过）
Node.js 版本 >= 18（本项目在 24.15.0 下验证通过）
npm 版本 >= 11
CUDA GPU 可选（推荐 RTX 3050 4GB+，没有也可以使用 CPU 推理）

项目简介

纺织制造中的人工布料检测速度慢、一致性差、容易出错。检验员在疲劳状态下可能漏检缺陷，导致下游质量事故。本项目使用深度学习方案替代人工检测，通过实例分割技术实时检测并定位布料缺陷——为制造商提供像素级缺陷地图，而非仅仅是边界框。

本项目使用 YOLOv8m-seg 模型（COCO 预训练），在 2,473 张图片、4 类缺陷的数据集上训练 150 个 epoch，测试 mAP50 达到 0.9164。

类别	说明	AP50
破洞 (Hole)	布料上的物理破裂或穿孔	0.9502
污渍 (Stain)	布料表面的污染或变色	0.9256
线条 (Line)	横向或纵向的织线异常	0.9187
结头 (Knot)	线头堆积 / 织造错误	0.8712

安装

克隆仓库

打开 DarkForest-727/Automated-Fabric-Defect-Detection-and-Localization，复制仓库地址，打开终端，使用 git clone 命令将仓库克隆到本地。

安装 Python 依赖

cd Automated-Fabric-Defect-Detection-and-Localization
pip install -r requirements.txt

核心包：ultralytics、fastapi、uvicorn、opencv-python、pillow、numpy

安装前端依赖

cd fabric-defect-ui
npm install

核心包：react、axios、framer-motion、tailwindcss、vite

模型权重

将训练好的 best.pt 放到项目根目录（约 55 MB）。如果仓库中已经包含该文件，可以跳过这一步。

命令介绍

启动 FastAPI 后端（项目根目录执行）：

python -m uvicorn main:app --host 0.0.0.0 --port 8000

验证后端是否正常运行：

curl http://localhost:8000/health
# → {"status":"ok","model":"yolov8m-seg","classes":{"0":"Hole","1":"Knot","2":"Line","3":"Stain"}}

启动 React 前端（在 fabric-defect-ui 目录下，打开新终端执行）：

npm run dev

Vite 开发服务器启动于：http://localhost:5173

打包前端静态文件：

npm run build

使用

打开浏览器访问 **http://localhost:5173**，上传一张布料图片，后端会返回带有分割 mask、边界框和缺陷标签的标注图片。

前端通过 fabric-defect-ui/.env 中的 VITE_API_URL 访问后端接口，本地运行时请将其配置为 http://localhost:8000。

API 接口

方法	路径	说明
`GET`	`/health`	健康检查——返回模型名称和类别列表
`POST`	`/predict`	上传图片 → 返回标注图片 + 检测结果

POST /predict 响应示例：

json

{
  "inference_time_ms": 85,
  "image_base64": "/9j/4AAQ...",
  "detections": [
    {
      "class": "Hole",
      "confidence": 0.923,
      "bbox": [120, 340, 280, 510]
    }
  ],
  "verdict": "Defected"
}

未检测到缺陷时 verdict 为 "PASS"。

部署

这里只介绍了本地运行方式，你也可以将前端部署到 Cloudflare Workers，后端通过 Cloudflare Tunnel 暴露到公网。
部署之前，确保你已经修改 fabric-defect-ui/.env 中的 VITE_API_URL。

本地架构

text

浏览器 (:5173)  →  React (Vite)  →  FastAPI (:8000)  →  YOLOv8m-seg (best.pt)
                         ↕
              POST /predict  →  标注图片 (base64) + 检测结果 JSON