# industrial-defect-webapp

**Repository Path**: Zzn1234/industrial-defect-webapp

## Basic Information

- **Project Name**: industrial-defect-webapp
- **Description**: 基于 Qwen2.5-VL-3B-Instruct + QLoRA 的钢材工业缺陷检测垂直落地 Web 应用。纯本地方案，简单易操作，手机连同一 WiFi 即可拍照上传，AI 自动识别钢材表面缺陷并输出分析报告。Flask 后端 + SQLite 历史记录 + 响应式前端，手机电脑通用。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: https://gitee.com/Zzn1234/industrial-defect-webapp.git
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔍 工业缺陷检测系统（Industrial Defect Detection WebApp）

基于 **Qwen2.5-VL** 的工业缺陷检测系统，支持**本地部署（Qwen2.5-VL-3B-Instruct + QLoRA）**与**云端 API（Qwen2.5-VL-72B-Instruct）**双模式。内置**登录系统**、**API Token 认证**与**后端数据可视化**界面，手机与电脑连接同一 WiFi 即可使用。

## ✨ 功能特性

- 🔐 **登录系统**：质检用户与后端用户均使用「姓名 + 工号」登录，系统自动识别角色并跳转到对应界面
- 🔑 **API Token 认证**：登录即签发 Token（默认 24 小时有效），支持 `Authorization: Bearer` 头调用接口，浏览器页面仍走 Session，二者兼容
- ☁️ **云端/本地双模式**：配置 `QWEN_VL_API_KEY` 自动切换云端视觉模型（预留 Qwen2.5-VL-72B-Instruct Key 位置）；不配置则使用本地模型 + LoRA
- 📸 **质检检测页**：手机/电脑摄像头拍照、相册上传 → AI 自动检测 → 输出分析报告
- 📋 **个人历史**：质检用户可查看自己的检测记录（含图片缩略图、检测结果与报错标记）
- 📊 **后端可视化**：按质检用户分组展示质检图片与质检结果，含统计卡片、用户筛选、详情弹窗
- 🚨 **报错保留**：检测异常时完整保存报错信息，并在检测页、历史记录、可视化界面中保留展示
- 📱 **响应式设计**：手机、平板、电脑通用

## 🔑 账号体系

账号 = **姓名**，密码 = **工号**，角色分为：

| 角色 | 说明 | 登录后进入 |
|------|------|------------|
| `qc` 质检用户 | 现场拍照提交检测 | 检测页 |
| `admin` 后端用户 | 查看数据可视化 | 可视化页 |

首次启动会自动写入以下默认账号（存储于 SQLite 的 `users` 表，可在数据库中增删改）：

| 角色 | 姓名 | 工号 |
|------|------|------|
| 质检用户 | 张伟 | 1001 |
| 质检用户 | 李娜 | 1002 |
| 质检用户 | 王强 | 1003 |
| 质检用户 | 赵敏 | 1004 |
| 后端用户 | 刘洋 | 2001 |
| 后端用户 | 陈静 | 2002 |

> ⚠️ 请上线使用前务必修改或删除默认账号。

新增用户示例：

```bash
python -c "import sqlite3; c=sqlite3.connect('history.db'); c.execute(\"INSERT INTO users (name,password,role) VALUES ('姓名','工号','qc')\"); c.commit()"
```

## 🚀 快速开始

### 模式一：云端 API（推荐，无需本地显卡）

只需配置 Key 即可，无需安装 torch/模型权重：

```bash
# Windows PowerShell
copy .env.example .env
# 编辑 .env，填入你的 Key：
#   QWEN_VL_API_KEY=sk-你的Qwen2.5-VL-72B-Instruct Key

pip install flask requests
python app.py
```

### 模式二：本地部署（数据不出内网）

```bash
pip install -r requirements.txt
```

下载基础模型（可选，用 modelscope 加速）：

```bash
pip install modelscope
python -c "from modelscope import snapshot_download; snapshot_download('Qwen/Qwen2.5-VL-3B-Instruct', cache_dir='./models')"
```

启动：

```bash
set MODEL_PATH=./models/Qwen/Qwen2.5-VL-3B-Instruct
python app.py
```

启动输出示例：

```
检测模式: 本地模型 + LoRA   （或：云端 API（qwen2.5-vl-72b-instruct））
本地访问: http://127.0.0.1:5000
手机访问: http://192.168.1.100:5000
```

手机浏览器打开第二个地址即可使用。

> 说明：即使未安装模型依赖，服务也会正常启动，登录与可视化功能可用；此时提交检测会保存并展示报错信息，便于定位问题。

## 🔑 API Token 使用说明

登录接口成功后会返回 `token`（明文仅返回一次，数据库只保存 SHA-256 哈希）与 `expires_at`。调用受保护接口时在请求头携带：

```
Authorization: Bearer <你的token>
```

curl 示例：

```bash
# 1. 登录获取 Token
curl -X POST http://127.0.0.1:5000/api/login ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"张伟\",\"password\":\"1001\"}"

# 2. 用 Token 提交图片检测（质检用户）
curl -X POST http://127.0.0.1:5000/api/analyze ^
  -H "Authorization: Bearer <token>" ^
  -F "image=@缺陷照片.jpg" ^
  -F "question=请检测图像缺陷并给出分析。"

# 3. 用 Token 查询历史记录
curl http://127.0.0.1:5000/api/history ^
  -H "Authorization: Bearer <token>"

# 4. 后端用户查看可视化数据
curl http://127.0.0.1:5000/api/dashboard ^
  -H "Authorization: Bearer <token>"

# 5. 退出登录（吊销 Token）
curl -X POST http://127.0.0.1:5000/api/logout ^
  -H "Authorization: Bearer <token>"
```

Token 默认 24 小时过期，可通过环境变量 `TOKEN_TTL_HOURS` 调整。退出登录会立即吊销当前 Token。

## 🤖 模型与权重说明（是否需要重新训练？）

- **本地模式**：`lora_adapter/` 内的 LoRA 权重是针对当前缺陷检测场景微调过的，效果已针对本场景优化，**无需重新训练**。
- **云端模式**：云端 API 是通用 `qwen2.5-vl-72b-instruct`，**无法挂载本地 LoRA 权重**，但 72B 基础能力远强于本地 3B，通常直接使用即可。
- 若云端通用模型在特定缺陷识别上准确率不达标，建议：先用系统提示词与提问方式调优 → 仍不达标再收集标注数据重新微调（可在阿里云百炼对 qwen-vl 系列微调，或继续本地 LoRA 训练）。
- 两种模式可随时切换、A/B 对比效果：配置 Key 走云端，删除/清空 Key 走本地。

## 🧭 页面与权限

| 路由 | 说明 | 访问权限 |
|------|------|----------|
| `/login` | 登录页 | 公开 |
| `/` | 质检检测页 | 质检用户 |
| `/dashboard` | 后端数据可视化 | 后端用户 |
| `/uploads/<文件名>` | 检测图片访问 | 登录后 |

## 🔌 API 一览

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/login` | POST | 无 | 登录（姓名 + 工号），返回 Token |
| `/api/logout` | POST | Session/Token | 退出登录并吊销 Token |
| `/api/analyze` | POST | Session/Token | 提交图片进行检测（质检用户） |
| `/api/history` | GET | Session/Token | 查询历史记录（质检用户看自己，后端用户看全部） |
| `/api/dashboard` | GET | Session/Token | 可视化数据：按质检用户返回图片与结果（后端用户） |

## 🗄️ 数据存储

- `history.db`（SQLite）
  - `users` 表：`id / name / password / role`
  - `records` 表：`id / username / question / answer / error / image_path / created_at`
  - `api_tokens` 表：`id / token_hash / username / role / created_at / expires_at`（Token 仅存哈希）
- `uploads/`：检测图片（自动创建）
- `.secret_key`：会话密钥（首次启动自动生成，已加入 `.gitignore`，不会上传）
- `.env`：环境变量配置（可选，参考 `.env.example`，已加入 `.gitignore`）

## 📂 目录结构

```
industrial-defect-webapp/
├── app.py                    # Flask 后端：登录 + Token 认证 + 模型推理 + 可视化 API
├── templates/
│   ├── login.html            # 登录页
│   ├── index.html            # 质检用户检测页
│   └── dashboard.html        # 后端数据可视化页
├── lora_adapter/             # 本地 LoRA 微调权重（仅本地模式使用）
│   ├── adapter_config.json
│   └── adapter_model.safetensors
├── .env.example              # 环境变量示例（含云端 API Key 预留位置）
├── requirements.txt
├── README.md
└── CHANGELOG.md              # 更新日志
```

## 🧱 技术栈

| 层 | 技术 |
|----|------|
| 前端 | HTML5 + CSS3 + JavaScript（原生，无构建） |
| 后端 | Flask (Python) + Session + API Token（SHA-256 哈希存储） |
| 模型 | 本地 Qwen2.5-VL-3B-Instruct + QLoRA / 云端 qwen2.5-vl-72b-instruct API |
| 数据库 | SQLite |
| 部署 | 局域网或公网均可，云端模式无需显卡 |

## 📝 更新日志

详见 [CHANGELOG.md](CHANGELOG.md)。

## 📄 许可证

Apache 2.0