本项目是一款工业级钢铁表面缺陷智能质检平台，采用双架构体系设计：
- SteelEye 智能中控工作站 (React 19 + Python FastAPI)：主力生产版本。集成 YOLOv8 快速筛查与云端 VLM 语义复核双引擎，引入 RAG 国家钢铁规范（如
GB/T 3280-2015）生成物理根因及处置对策；打通人工确权与后台异步增量重训的“数据飞轮”闭环，并内嵌“AI 工艺助理”提供自然语言故障提问。 - 高性能边缘检测端 (C++ Drogon + Vue 3)：硬实时检测版本。在工控机上实现 C++ 图像预处理与 ONNX 推理，端到端延迟控制在
< 2.0 ms，吞吐量达> 500 FPS，并以 SVG 物理数字孪生传送带呈现质检看板。
| 指标维度 | V2.2.2 架构 (Python + Gradio) | V3.0 架构 (C++ ONNX + Vue 3) | 工业现实效益 |
|---|---|---|---|
| 端到端推理时延 | ~46 ms (P50 延迟，受限 Python GIL) | < 2.0 ms (C++ 预处理 + ONNX Runtime) | 时延缩减 95.6%，完美支持高倍率线阵在线检测。 |
| 系统最大吞吐 | ~143 FPS | > 500 FPS (在 RTX 5060 上) | 支持在 10m/s 的高速带钢流水线上实现毫秒级零丢帧扫描。 |
| 控制流管道设计 | 单线程同步阻塞，慢速 RAG 检索会导致主检测流停顿 | 多线程异步消费流水线 (Camera -> Ring Buffer -> Inference -> SQLite -> WS Broadcast) | 大模型会诊与 RAG 完全异步，全时段质检检测绝不卡顿。 |
| 前端视觉体验 | 粗糙的 HTML 跑马灯拼贴，缺少响应式布局 | SVG 动态数字孪生传送带，提供深色 HSL 科技感看板 | 带来震撼 of 数字化孪生沉浸感，摆脱 Gradio 模板感。 |
系统采用工业前后端分离微服务技术架构设计，主要包含两个核心版本：
- 前端展示层 (React 19 + TypeScript + Tailwind CSS)：即 SteelEye React 工作站。包含真彩/应力/边缘/偏光多视图滤镜、Canvas 钢板高保真标样渲染、实时缺陷密度热力图、5 种生产角色管理权限，以及内嵌的“AI 工艺助理”浮动对话窗口。
- 数据飞轮与服务后端 (FastAPI + SQLite WAL/SQLCipher)：即 server.py。在 YOLO 筛查与 VLM 复核基础上，实现 RAG 检索国家钢铁规范；支持人工修修正缺陷严重度与确权，提供后台
/api/train/start异步增量重训及进度状态接口。
- 前端展示层 (Vue 3 + Vite + TypeScript)：连接后端的 WebSocket 广播管道，实时同步检测帧、YOLO 缺陷坐标并呈现 SVG 动态数字孪生传送带。
- 边缘检测端 (C++ Drogon + ONNX Runtime)：硬实时核心。拉取线阵相机流，执行图像预处理、YOLOv8 推理和 NMS (非极大值抑制)，并通过 WAL 高性能模式持久化至 SQLite。
项目以多语言、双版本混合子工程形式组织，结构如下：
f:/gangtiebiaomianquexian/steel-defect-detection/
├── frontend/ # SteelEye React 生产级前端 (React 19 + TS + Tailwind)
│ ├── src/
│ │ ├── App.tsx # 包含“数据飞轮控制台”与“AI工艺助理”悬浮对话框
│ │ └── data/samples.ts # Canvas 真彩钢板表面纹理及标样配置
│ └── package.json # 前端依赖配置
│
├── steel-defect-detection-vue/ # Vue 3 前端子项目 (Vite + TypeScript + Pinia)
│ ├── src/
│ │ ├── store/defect.ts # 核心状态管理（WebSocket 连接与高保真仿真器）
│ │ └── views/Dashboard.vue # 钢铁之眼数字孪生中控面板
│
├── steel-defect-detection-cpp/ # C++ 高性能边缘端 (CMake + Drogon + ONNX Runtime)
│ ├── CMakeLists.txt # 编译配置文件
│ └── src/
│ ├── YoloDetector.cpp # YOLOv8 ONNX 推理与 NMS
│ └── DbManager.cpp # 线程安全 C++ SQLite3 API
│
├── src/ # Python 后端源代码目录
│ ├── db_manager.py # SQLite SQLCipher 数据库持久层，支持已审核数据导出
│ └── image_enhancer.py # 引入 CLAHE 自适应直方图均衡化与拉普拉斯细节融合的增强器
│
├── server.py # Python FastAPI 异步重训与 RAG 融合后端入口
└── scripts/ # 辅助脚本与算法微服务网关
└── vue_api_bridge.py # Python 微服务网关 (提供与 C++ 100% 兼容的 API 兼容层)
本项目为您配置了**“联机工控机环境”与“零门槛前端仿真环境”**两套运行方案：
我们在 Vue 3 中内置了全套高保真离线仿真引擎。无需配置任何 C++ 编译器或 Python 运行时，直接体验前端数字孪生大屏：
# 1. 进入 Vue 目录
cd steel-defect-detection-vue
# 2. 安装组件依赖
npm install
# 3. 启动开发服务器
npm run dev打开浏览器访问 http://localhost:5174/。系统在检测到 C++ 服务离线时，会自动启用高仿真的质检数据生成器，传送带、YOLO 框线、RAG 国标检索与 ECharts 数据图表将完美呈现。
利用您本地已有的 PyTorch + CUDA 环境，启动与 C++ API 100% 兼容的 Python 后台网关：
# 1. 启动 Python API 后端网关 (监听 8080 端口)
.venv\Scripts\python scripts/vue_api_bridge.py
# 2. 进入 Vue 3 前端并启动
cd steel-defect-detection-vue
npm run dev此时打开 http://localhost:5174/，前端大屏会直接与 Python 算法后端通过真实的高频 WebSocket 联机。系统将调用您的 YOLOv8 模型进行实时推理，并写入 SQLite3 数据库。
编译高性能 C++ 边缘检测工程：
cd steel-defect-detection-cpp
mkdir build
cd build
# 使用 CMake 编译 (需确保已通过 winget 或 vcpkg 安装 OpenCV, Drogon 和 ORT 依赖)
cmake ..
cmake --build . --config Release
# 运行 Drogon C++ 推理服务器 (监听 8080 端口)
./steel_defect_detection_cpp如果您希望省去 Node.js (Vue) 安装以及 C++ drogons/onnxruntime 环境编译配置，直接在单一 Python 进程内体验最初版 (Gradio 界面)，可以通过以下步骤极速部署与运行：
- 一键环境安装：
- Windows：双击运行项目根目录下的 setup.bat
- Linux / macOS：在终端运行
bashsetup.sh
- 一键启动 Web 工作台：
# 激活虚拟环境并启动主入口 .venv\Scripts\python main.py - 访问大屏：
在浏览器中访问
http://localhost:7860/。该界面包含了实时检测（YOLO/VLM/RAG）、人工审核工作台与报表导出三大核心模块，即装即用。
如果您要运行并体验本项目最新开发完成的 React 19 + Python FastAPI 体系（含数据飞轮增量重训及 AI 工艺助理浮动窗口），请按以下步骤操作：
- 启动 FastAPI 后端服务（运行于 8000 端口）：
# 激活虚拟环境并启动 API 服务 .venv\Scripts\python server.py - 启动 SteelEye React 前端服务（运行于 5173 端口）：
# 进入前端目录安装依赖并启动 cd frontend npm install npm run dev - 访问系统：
在浏览器中访问
http://localhost:5173/。- 默认账户：
admin/123456。 - 特色功能：
- 可视化：真彩、应力、边缘、偏光四通道 Canvas 滤镜与热力图。
- 数据飞轮：AI 工程师（
ai_engineer）角色登录后可在控制面板一键启动后台增量重训并实时查看 Epoch、Loss 与 mAP 进度条。 - AI 助理：在页面右下角使用“AI 工艺助理”悬浮对话框，直接向后台大模型检索 RAG 冶金知识库，提供实时问答服务。
- 默认账户：
系统数据库内置了国家权威钢铁生产标准规范（GB/T 1499.2-2018 和 GB/T 3280-2015 等 11 条核心切片）。 当检测到缺陷时，微服务大脑会自动匹配最精准的国标条例，拼装至 VLM Prompt 中，由 Gemini 模型输出权威整改指导。
为了满足大型钢铁集团智慧质检平台架构，我们已经确立了 V4.0 混合分布式微服务方案：
- Java Spring Boot：接管主业务层，用于权限控制、MES 生产系统对接与全局历史台账。
- C++ (ONNX/TensorRT)：专注于边缘硬实时检测（< 2ms），检测到异常时通过 gRPC 快速上报 Java。
- Python (FastAPI)：专注于复杂的多模态大模型 VLM 会诊与 RAG。 详细升级方案请参考：V4.0 混合微服务升级方案说明书。
- 🔍 前处理抗光照干扰 (CLAHE)：在 YOLO 推理前可选引入自适应直方图均衡化（CLAHE），拉伸局部对比度，有效克服工业现场光照不均，增强低召回缺陷的边缘特征。
- 📈 小样本与难检类别增强：升级了
scripts/augment_defects.py数据增强工具，针对低召回率类别inclusion(夹杂) 和rolled-in_scale(轧制氧化皮) 自动叠加亮度抖动与 CLAHE 增强进行数据增广，提高缺陷样本的多样性。 - ⚡ 连接高可用与自适应重连：Vue 3 前端引入了指数退避自动重连机制（间隔 1s, 2s, 4s, 8s... 最多 10 次）和 5 秒心跳机制（ping/pong），实现了网线瞬断自动重连且页面不卡顿，并辅以三态呼吸灯展示。
- 🛠️ 一键式运维诊断扩展：升级了
cli.py环境验证工具，支持自动加载.env，新增对 VLM API 节点网络连接平均时延（Round-Trip Time）的自动测算，并在时延过大时给出预警，辅助工业部署决策。
- 🚀 C++ 推理与 API 重构：完成了基于 ONNX Runtime C++ API 的极速预处理与 NMS C++ 算法，引入 C 风格
sqlite3精准 RAG 国家标准模糊匹配，并采用 Drogon 高性能服务器广播 WebSocket。 - 🎨 Vue 3 响应式数字孪生大屏：全面重写前端代码。利用 SVG +
requestAnimationFrame开发出流动式传送带物理模型，集成 YOLO 标记 Canvas 自适应框线、ECharts 看板、硬件 CPU/GPU 状态监控灯。 - 🔗 Python 兼容微服务网关：新撰写了
scripts/vue_api_bridge.py算法服务，利用已有的 Python 环境无缝兼容 V3.0 API，为用户提供零开销联机演示。
- 🔄 异步非阻塞检测流水线：解耦 YOLO 推理与慢速 VLM/RAG 流程，引入后台
Queue任务队列与守护 Worker，消除时延 Gap。 - 📚 工业级“双路容错”RAG 根因分析：在 SQLite 数据库中构建知识库并注入国家标准。
- 🧪 自动化测试与环境隔离：新增 12 个测试点，113 项全量测试 100% 通过。
本项目采用 MIT 许可证。详见 LICENSE 文件。